Code Block

Code Block

동적인 코드 블록을 표시하고 하이라이트할 때 사용하는 컴포넌트예요. Shiki나 Highlight.js 하이라이팅 엔진을 지원해요.

출처: 문서

본문

사용법 (Usage)

import { CodeBlock } from "@chakra-ui/react"

<CodeBlock.AdapterProvider>
  <CodeBlock.Root>
    <CodeBlock.Header>
      <CodeBlock.Title />
      <CodeBlock.Control>
        <CodeBlock.CopyTrigger />
        <CodeBlock.CollapseTrigger />
      </CodeBlock.Control>
    </CodeBlock.Header>
    <CodeBlock.Content>
      <CodeBlock.Code>
        <CodeBlock.CodeText />
      </CodeBlock.Code>
    </CodeBlock.Content>
  </CodeBlock.Root>
</CodeBlock.AdapterProvider>

어댑터 (Adapters)

CodeBlock 컴포넌트는 Shiki와 Highlight.js 하이라이팅 엔진을 지원해요.

문서에서는 기본적으로 Shiki를 가정해요.

코드 블록 컴포넌트를 설정하려면 다음을 해야 해요:

  • 선호하는 어댑터(Shiki 또는 Highlight.js)를 구성한다.
  • 최상위 레벨에서 어댑터를 CodeBlock.AdapterProvider에 제공한다.
  • CodeBlock.AdapterProvider 안에서 CodeBlock.Root 컴포넌트를 렌더링한다.

Shiki

shiki 패키지를 설치해 주세요.

npm install shiki

그런 다음, 선택된 언어에 대해 shiki 하이라이터를 동적으로 로드하는 shiki 어댑터를 만들어요.

import type { HighlighterGeneric } from "shiki"
import { createShikiAdapter } from "@chakra-ui/react"

const shikiAdapter = createShikiAdapter<HighlighterGeneric<any, any>>({
  async load() {
    const { createHighlighter } = await import("shiki")
    return createHighlighter({
      langs: ["tsx", "json"],
      themes: ["github-dark", "github-light"],
    })
  },
})

<CodeBlock.AdapterProvider value={shikiAdapter}>
  {/* ... */}
</CodeBlock.AdapterProvider>

Highlight.js

highlight.js 패키지를 설치해 주세요.

npm install highlight.js

그런 다음, 선택된 언어를 동적으로 로드하는 highlight.js 어댑터를 만들어요.

import { createHighlightJsAdapter } from "@chakra-ui/react"
import hljs from "highlight.js/lib/core"

const highlightJsAdapter = createHighlightJsAdapter<typeof hljs>({
  async load() {
    const languages = {
      tsx: () => import("highlight.js/lib/languages/typescript"),
      html: () => import("highlight.js/lib/languages/xml"),
    }
    await Promise.all(
      Object.entries(languages).map(async ([language, file]) => {
        const { default: langModule } = await file()
        hljs.registerLanguage(language, langModule)
      }),
    )
    return hljs
  },
})

예시 (Examples)

크기 (Sizes)

size prop을 사용하면 코드 블록 컴포넌트의 크기를 바꿀 수 있어요.

제목 (Title)

CodeBlock.Header 컴포넌트 안에서 CodeBlock.Title 컴포넌트를 렌더링하면 코드 블록에 제목을 추가할 수 있어요.

복사 버튼 (Copy button)

copyButton prop을 사용하면 코드 블록에 복사 버튼을 추가할 수 있어요.

줄 번호 (Line numbers)

줄 번호는 특정 코드 줄을 참조하기 쉽게 만들어 줘요. meta.showLineNumbers prop을 전달하면 코드 블록에 줄 번호가 표시돼요.

줄 하이라이트 (Line highlighting)

CodeBlock.Root 컴포넌트에 meta.highlightLines prop을 전달하면 특정 코드 줄을 하이라이트할 수 있어요. 이 prop은 줄 번호의 배열을 받아요.

줄 포커스 (Line focus)

CodeBlock.Root 컴포넌트에 meta.focusedLineNumbers prop을 전달하면 특정 코드 줄에 포커스를 줄 수 있어요. 이 prop은 줄 번호의 배열을 받아요.

Diff (차이)

Diff는 소스 코드 변경 사항을 강조할 때 유용해요. meta.addedLineNumbers와 meta.removedLineNumbers prop을 사용하면 코드 블록에 줄 번호를 추가할 수 있어요.

이 prop은 줄 번호의 배열을 받아요. 줄 번호는 1부터 시작해요.

최대 줄 수 (Max lines)

meta.maxLines prop을 사용하면 코드 블록의 줄 수를 제한할 수 있어요. 기본적으로 코드 블록은 콘텐츠에 맞게 확장돼요.

언어 전환기 (Language switcher)

CodeBlock과 Select 컴포넌트를 조합해 API 엔드포인트 요청 컴포넌트를 재현한 예시예요.

플로팅 복사 버튼 (Floating copy button)

코드 블록에 플로팅 복사 버튼을 추가하는 예시예요.

탭 (Tabs)

CodeBlock 컴포넌트를 Tabs 컴포넌트와 조합해 탭이 있는 코드 블록을 만드는 예시예요.

탭 동기화 (Tabs sync)

같은 storage key를 공유하는 모든 코드 블록을 자동으로 동기화하는 예시예요. 문서 사이트에서 패키지 매니저 또는 프레임워크별 코드 블록에 유용해요.

테마 (Themes)

meta.colorScheme prop을 사용하면 코드 블록에 테마를 추가할 수 있어요. 이 예시에서는 colorScheme을 useColorMode 훅의 color mode로 설정했어요.

줄바꿈 (Wrap overflow)

meta.wordWrap prop을 사용하면 코드 블록에서 줄바꿈을 적용할 수 있어요.

줄바꿈과 함께하는 줄 번호 (Line numbers with word wrap)

meta.showLineNumbers와 meta.wordWrap을 모두 true로 설정하면 줄 번호와 줄바꿈을 함께 사용할 수 있어요. 줄 번호는 줄바꿈된 텍스트와 올바르게 정렬돼요.

Highlight.js

highlight.js를 사용해 코드 블록을 하이라이트하는 예시예요.

평문 (Plain text)

코드 블록은 기본적으로 평문으로 대체돼요. 평문 코드 블록을 만들려면 CodeBlock.AdapterProvider 사용을 제거하면 돼요.

Props

해당 컴포넌트에 전달할 수 있는 prop은 Code 컴포넌트의 Props 표를 확인해 주세요.

더 알아보기 (Learn more)

Chakra UI의 Code Block 컴포넌트에 대해 더 자세히 알아보려면 공식 문서를 확인해 보세요.