Creation:2026-01-20Last update:2026-03-24

    HTML 内容 / Intlayer 中的 HTML

    Intlayer 支持 HTML 内容，允许你在字典中嵌入丰富的结构化内容。此类内容可以使用标准 HTML 标签渲染，或在运行时替换为自定义组件。

    声明 HTML 内容

    您可以使用 html 函数声明 HTML 内容，或简单地将其作为字符串。

    使用 html 函数显式声明 HTML 内容。即使自动检测被禁用，这也能确保标准标签被正确映射。

    htmlDictionary.content.ts
    import { html, type Dictionary } from "intlayer";const htmlDictionary = {  key: "app",  contentAutoTransformation: true, // 可在配置文件中设置  content: {    myHtmlContent:  html("<p>Hello <strong>World</strong></p>"),  },} satisfies Dictionary;export default htmlDictionary;

    html() 节点

    html() 函数是 Intlayer v8 中的一个新特性，它允许你在字典中显式定义 HTML 内容。虽然 Intlayer 通常可以自动检测 HTML 内容，但使用 html() 函数具有以下优势：

    • 类型安全：html() 函数允许你为自定义组件定义预期的 props，从而在编辑器中提供更好的自动补全和类型检查。
    • 显式声明：它确保字符串始终被视为 HTML，即使它不包含会触发自动检测的标准 HTML 标签。
    • 自定义组件定义：你可以向 html() 传递第二个参数来定义自定义组件及其预期的 prop 类型。
    typescript
    import { html } from "intlayer";const myContent = html(  "<MyCustomComponent title='你好'>世界</MyCustomComponent>",  {    MyCustomComponent: {      title: "string",      children: "node",    },  });

    在 HTML 节点上使用 .use() 方法时，你提供的组件将根据 html() 函数中提供的定义（如果可用）进行检查。

    渲染 HTML

    渲染可以由 Intlayer 的内容系统自动处理，也可以使用专用工具手动完成。

    自动渲染（使用 useIntlayer）

    通过 useIntlayer 访问内容时，HTML 节点已准备好渲染。

    HTML 节点可以直接作为 JSX 渲染。标准标签会自动生效。

    App.tsx
    import { useIntlayer } from "react-intlayer";const AppContent = () => {  const { myHtmlContent } = useIntlayer("app");  return <div>{myHtmlContent}</div>;};

    使用 .use() 方法可以提供自定义组件或覆盖标签：

    tsx
    {myHtmlContent.use({  p: (props) => <p className="prose" {...props} />,  CustomLink: ({ children }) => <a href="/details">{children}</a>,})}

    使用 HTMLProvider 的全局配置

    您可以为整个应用全局配置 HTML 渲染。这非常适合定义应在所有 HTML 内容中可用的自定义组件。

    AppProvider.tsx
    import { HTMLProvider } from "react-intlayer/html";export const AppProvider = ({ children }) => (  <HTMLProvider    components={{      p: (props) => <p className="prose" {...props} />,      CustomLink: ({ children }) => <a href="/details">{children}</a>,    }}  >    {children}  </HTMLProvider>);

    您也可以使用自己的 HTML 渲染器：

    AppProvider.tsx
    import { HTMLProvider } from "react-intlayer/html";export const AppProvider = ({ children }) => (  <HTMLProvider    renderHTML={async (html) => {      const { renderHTML } = await import('react-intlayer/html');      return renderHTML(html);    }}  >    {children}  </HTMLProvider>);
    动态导入 HTML 渲染器是减小应用程序Bundle 大小的好方法。

    手动渲染与高级工具

    如果你需要渲染原始 HTML 字符串或对组件映射有更多控制，请使用以下工具。

    <HTMLRenderer /> 组件

    tsx
    import { HTMLRenderer } from "react-intlayer/html";<HTMLRenderer components={{ p: MyCustomP }}>  {"<p>Hello World</p>"}</HTMLRenderer>

    useHTMLRenderer() Hook

    获取一个预配置的渲染器函数。

    tsx
    import { useHTMLRenderer } from "react-intlayer/html";const renderHTML = useHTMLRenderer({  components: { strong: (props) => <strong {...props} className="text-red-500" /> }});return renderHTML("<p>Hello <strong>World</strong></p>");

    renderHTML() 实用工具

    用于在组件外进行渲染的独立实用工具。

    tsx
    import { renderHTML } from "react-intlayer/html";const jsx = renderHTML("<p>Hello</p>", { components: { p: 'div' } });

    选项参考

    这些选项可以传递给 HTMLProvider、HTMLRenderer、useHTMLRenderer 和 renderHTML。

    选项 类型 默认 说明
    components Record<string, any> {} 一个将 HTML 标签或自定义组件名称映射到对应组件的映射表。
    renderHTML Function null 一个自定义渲染函数，用于完全替换默认的 HTML 解析器（仅适用于 Vue/Svelte 提供器）。
    注意：对于 React 和 Preact，标准 HTML 标签会自动提供。只有当你想覆盖它们或添加自定义组件时，才需要传入 components prop。
    Markdown
    函数获取