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

    HTML 콘텐츠 / Intlayer의 HTML

    Intlayer는 HTML 콘텐츠를 지원하여 사전(dictionary) 내에 풍부하고 구조화된 콘텐츠를 포함할 수 있습니다. 이 콘텐츠는 표준 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 렌더러를 동적으로 가져오는 것은 애플리케이션의 번들 크기를 줄이는 좋은 방법입니다.

    수동 렌더링 및 고급 도구

    원시 HTML 문자열을 렌더링하거나 컴포넌트 매핑을 더 세밀하게 제어해야 하는 경우, 다음 도구들을 사용하세요.

    <HTMLRenderer /> 컴포넌트

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

    useHTMLRenderer() 훅

    미리 구성된 렌더러 함수를 얻습니다.

    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
    함수 가져오기