> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 모드용 인터페이스 갤러리
> 텍스트, 버튼, 필드, Markdown, 코드, diff 등 Claude Code 모드가 그릴 수 있는 인터페이스 요소를 샘플 코드 및 터미널 스크린샷과 함께 살펴봅니다.
모드는 요소를 사용해 인터페이스를 그립니다. 요소에는 텍스트, 박스, 버튼, 필드, 그리고 콘텐츠 서식을 대신 지정해 주는 몇 가지 요소가 있습니다. 이 페이지의 샘플은 요소를 그리는 코드를 보여 주며, 대부분은 터미널 창에 그려진 결과 스크린샷을 함께 제공하므로 모양을 보고 요소를 고를 수 있습니다.
그리기가 작동하는 방식을 알아보려면 [인터페이스에 그리기](/docs/ko/plugins/mods/interface)부터 시작하십시오. 주요 props와 각 요소를 그리는 앱은 [요소 레퍼런스](/docs/ko/plugins/mods/reference#elements)를 참조하십시오. [타입 선언](/docs/ko/plugins/mods/create#get-the-types-for-your-build)에는 모든 prop이 나열되어 있습니다.
샘플 사용해 보기
이 페이지의 샘플은 완전한 모드가 아니라 코드 조각입니다. 각 샘플은 하나의 요소와 그 안에 중첩된 모든 항목에 대한 코드입니다.
샘플을 직접 터미널에서 확인하려면 다음 단계에 따라 작은 모드를 만들고 샘플을 붙여 넣으십시오. 이 모드는 창을 열고 그 안에 샘플을 그리는 `/gallery` 명령을 추가합니다. [창](/docs/ko/plugins/mods/interface#pick-where-to-draw)은 넓은 전체 화면 터미널에서는 트랜스크립트 옆의 사이드바이고, 그 외의 경우에는 프롬프트 위의 테두리가 있는 영역입니다.
`gallery`라는 디렉터리를 만들고 그 안에 `.claude-plugin` 및 `hooks` 디렉터리를 만드십시오. 파일에 대한 설명은 [모드 만들기](/docs/ko/plugins/mods/create#write-a-mod-yourself)를 참조하십시오.
매니페스트를 `gallery/.claude-plugin/plugin.json`으로 저장합니다.
```json gallery/.claude-plugin/plugin.json theme={null}
{
"name": "gallery",
"version": "0.1.0",
"description": "Opens a pane that draws one sample",
"author": { "name": "Your Name" }
}
```
`gallery/hooks/hooks.json`에 진입점을 지정합니다.
```json gallery/hooks/hooks.json theme={null}
{
"modules": ["./register.js"]
}
```
코드를 `gallery/hooks/register.js`로 저장합니다. 이 코드는 창을 여는 `/gallery` 명령을 추가하고 그 창에 `Plain text`를 그립니다.
```javascript gallery/hooks/register.js theme={null}
// Stands in for your own callback in the samples that take one
const noop = () => {}
// The Select sample keeps its choice here
let picked = 'md'
// The Raster sample packs its cells with this function
const DEFAULT_COLOR = 0x01000000
function cellsOf(rows) {
const numbers = rows.flat().flatMap(([char, color]) => [char.codePointAt(0), color, DEFAULT_COLOR])
return new Uint8Array(Uint32Array.from(numbers).buffer).toBase64()
}
export function register(on) {
on('session.start', async ($, e, next) => {
await $.command.register({ name: 'gallery', description: 'Open the sample pane' })
return next(e)
})
on('command.run', { command: 'gallery' }, async ($) => {
await $.ui.open({ id: 'gallery', focus: true, closeOnEscape: true })
return {}
})
on('ui.render', { component: 'Pane' }, async ($, e, next) => {
if (e.requestId !== 'gallery') return next(e)
const { Box, Text, Button, Input, Select, Link, Markdown, Code, Raster, Svg } = $.ui.resolve(e)
// Replace the element after return with a sample
return Text({ children: ['Plain text'] })
})
}
```
셸에서 `gallery`가 있는 디렉터리에서 Claude Code를 시작합니다.
```bash theme={null}
claude --plugin-dir ./gallery
```
Claude Code 프롬프트에서 `/gallery`를 실행합니다. `Plain text`가 표시된 창이 열립니다.
이 페이지에서 샘플을 복사합니다. `register.js`에서 `Text({ children: ['Plain text'] })` 위치에 샘플을 붙여 넣어 `return` 뒤에 오도록 한 다음 파일을 저장합니다. Claude Code는 저장할 때마다 모듈을 다시 로드하므로, `/gallery`를 다시 실행하면 새 샘플을 볼 수 있습니다.
요소 선택하기
샘플은 화면에 표시하려는 내용에 따라 분류되어 있습니다.
* **[텍스트 표시하기](#show-text)**: `Text`, `Markdown`, `Link`
* **[코드 및 변경 사항 표시하기](#show-code-and-changes)**: `Code`
* **[요소 배치하기](#arrange-elements)**: `Box`
* **[입력 받기](#take-input)**: `Button`, `Input`, `Select`
* **[그림 그리기](#draw-pictures)**: `Raster`, `Svg`, `Image`, `Client`
텍스트 표시하기
화면에 글자를 표시하는 요소는 세 가지입니다. 직접 스타일을 지정할 때는 `Text`, 이미 서식이 지정된 콘텐츠에는 `Markdown`, URL에는 `Link`를 사용합니다.
`Markdown`은 Claude의 응답과 같은 방식으로 텍스트 서식을 지정합니다. 콘텐츠는 `children`이 아닌 `text`로 전달하십시오.
```javascript theme={null}
Markdown({
text: '## Release notes\n\nThis build has **two** fixes and one `flag`:\n\n- Faster start\n- Fewer prompts\n\n> Quoted text',
})
```
제목은 `#` 기호 없이 굵게 그려집니다. 인라인 코드는 백틱 없이 색으로 그려집니다. 인용문은 왼쪽에 막대가 있는 기울임꼴로 그려집니다.
`Link`
`Link`는 레이블과 그 뒤에 URL을 그립니다.
```javascript theme={null}
Link({ href: 'https://code.claude.com/docs', label: 'Claude Code docs' })
```
터미널은 레이블 뒤에 URL을 텍스트로 그립니다. 클릭으로 URL이 열리는지 여부는 사용자의 터미널에 따라 다릅니다.
코드 및 변경 사항 표시하기
`Code`는 Claude Code 자체의 구문 색상으로 소스 텍스트를 그리거나 diff를 그립니다.
`Code`
`language`를 지정하거나, Claude Code가 언어를 추론할 수 있도록 `path`를 전달하십시오. `startLine`을 지정하면 해당 번호부터 줄 번호가 매겨집니다.
```javascript theme={null}
Code({
language: 'javascript',
startLine: 1,
source: "const name = 'mods'\nconsole.log('hello ' + name)",
})
```
색상은 사용자의 테마를 따릅니다.
diff로 표시하는 `Code`
`format: 'diff'`를 지정하면 `source`는 하나 이상의 unified diff 헝크가 됩니다.
```javascript theme={null}
Code({
format: 'diff',
source: '@@ -1,3 +1,3 @@\n # Mods\n-A mod is a plugin.\n+A mod is a plugin that runs code.\n Read on.',
})
```
Claude Code는 `@@` 줄 대신 줄 번호를 그립니다. 삭제된 줄과 추가된 줄이 비슷한 경우, 변경된 단어는 더 진한 음영으로 표시됩니다.
요소 배치하기
`Box`
`Box`는 내부 요소를 행 또는 열로 배치하며 테두리를 그릴 수 있습니다. 이 샘플은 단어 한 행을 테두리가 있는 박스 위에 배치합니다.
```javascript theme={null}
Box({
flexDirection: 'column',
gap: 1,
children: [
Box({
flexDirection: 'row',
columnGap: 4,
children: [Text({ children: ['a row'] }), Text({ children: ['of three'] }), Text({ children: ['items'] })],
}),
Box({
borderStyle: 'round',
paddingX: 1,
children: [Text({ children: ["borderStyle: 'round'"] })],
}),
],
})
```
테두리는 창의 너비만큼 늘어납니다.
입력 받기
`Button`, `Input`, `Select`는 컨트롤입니다. 사용자는 Tab으로 컨트롤 사이를 이동하고 포커스가 있는 컨트롤을 사용합니다. 어떤 키가 컨트롤에 전달되는지는 [키보드 포커스 및 단축키](/docs/ko/plugins/mods/interface#know-which-keys-your-mod-can-receive)에서 설명합니다.
`focus: true`로 창을 열면 창에 키보드 포커스가 주어집니다. 입력한 글자는 `Input`에 포커스가 있을 때 전달되므로, 창이 열리자마자 입력을 받아야 하는 필드에는 `autoFocus: true`를 추가하십시오.
`Button`
버튼은 `onPress`를 실행합니다. 이 샘플은 기본 형태, 단축키가 있는 `plain` 버튼, 흐리게 표시된 버튼을 보여 줍니다.
```javascript theme={null}
Box({
flexDirection: 'column',
children: [
Button({ key: 'save', label: 'Save', onPress: noop }),
Button({ key: 'next', label: 'Next', hotkey: 'n', plain: true, onPress: noop }),
Button({ key: 'skip', label: 'Skip', dimColor: true, onPress: noop }),
],
})
```
포커스가 있는 버튼은 반전 표시로 그려집니다. 다음은 사용자가 Tab을 두 번 누른 상태입니다.
`Input`
`Input`은 사용자가 Enter를 누르면 `onSubmit`을 실행하는 한 줄 텍스트 필드입니다.
```javascript theme={null}
Input({
key: 'title',
label: 'Title',
placeholder: 'Type a title and press Enter',
value: '',
submitLabel: 'save',
onSubmit: noop,
})
```
포커스가 없으면 필드에 레이블과 플레이스홀더가 표시됩니다.
포커스가 있으면 레이블이 굵게 바뀌고 커서가 나타나며, `⏎` 뒤에 `submitLabel`이 표시됩니다.
입력을 시작하면 플레이스홀더가 대체됩니다.
`Select`
`Select`를 사용하면 사용자가 여러 옵션 중 하나를 선택할 수 있으며, 선택한 옵션의 `value`로 `onSelect`를 실행합니다.
```javascript theme={null}
Select({
key: 'format',
label: 'Format',
value: picked,
options: [
{ value: 'md', label: 'Markdown' },
{ value: 'html', label: 'HTML' },
{ value: 'txt', label: 'Plain text' },
],
onSelect: (value) => {
picked = value
},
})
```
닫힌 상태에서는 레이블과 현재 옵션이 표시됩니다.
열린 상태에서는 옵션 목록이 표시되고 그중 하나가 강조됩니다.
사용자가 옵션을 선택하면 목록이 닫힙니다.
그림 그리기
`Raster`
`Raster`는 색이 입혀진 문자 셀의 격자로, 히트맵, 스파크라인, 게임 보드 등에 사용합니다. 터미널이 이를 그립니다. 이 샘플은 시작 모듈의 `cellsOf` 함수를 사용하며, 이 함수는 셀을 `Raster`가 받는 문자열로 압축합니다. 자세한 설명은 [색이 입혀진 셀 격자 그리기](/docs/ko/plugins/mods/interface#draw-a-grid-of-colored-cells)를 참조하십시오.
```javascript theme={null}
Raster({
key: 'grid',
columns: 3,
rows: 2,
cells: cellsOf([
[['█', 0x2e7d32], ['█', 0xf9a825], ['█', 0xc62828]],
[['█', 0x2e7d32], ['█', 0x2e7d32], ['█', 0xf9a825]],
]),
})
```
`Raster`는 각 색상을 더 작은 팔레트로 반올림하므로 `0x2e7d32`는 `#337733`으로 그려집니다.
`Svg`
`Svg`는 Desktop 앱에서 SVG 문서를 그립니다.
```javascript theme={null}
Svg({
alt: 'Three bars of rising height',
width: 120,
height: 60,
source:
'',
})
```
터미널에서는 `Svg`만 반환하는 창이 빈 상태로 열립니다. 터미널에서 다른 것을 그리려면 [`e.surface`](/docs/ko/plugins/mods/interface#pick-where-to-draw)를 확인하고 다른 트리를 반환하십시오.
`Image` 및 `Client`
두 요소는 여기에 샘플이 없습니다. `Image`는 터미널에서 PNG 또는 원시 픽셀을 그립니다. `Client`는 애니메이션과 포인터 입력을 위해 사용자가 작성한 두 번째 파일이 그리는 영역입니다. 해당 props는 [요소 레퍼런스](/docs/ko/plugins/mods/reference#elements)에 나열되어 있습니다.
모드가 그릴 수 있는 위치 확인하기
모든 샘플은 창에 그립니다. 모드는 다른 위치에도 그릴 수 있으며, Claude Code를 호출해 무언가를 대신 표시하게 할 수도 있습니다.
* **창 및 밴드**: [그릴 위치 선택하기](/docs/ko/plugins/mods/interface#pick-where-to-draw)
* **스피너 등 Claude Code 자체의 행**: [Claude Code가 이미 그리는 내용 변경하기](/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws)
* **토스트, 상태줄, 로그 줄**: [턴을 시작하지 않고 무언가 표시하기](/docs/ko/plugins/mods/api#show-something-without-starting-a-turn)
* **질문 대화 상자**: [사용자가 결정할 때까지 도구 호출 보류하기](/docs/ko/plugins/mods/events#hold-a-tool-call-until-the-user-decides)
다음 단계
* [인터페이스에 그리기](/docs/ko/plugins/mods/interface): 탭이 있는 창을 단계별로 만들어 봅니다
* [그리기 테스트하기](/docs/ko/plugins/mods/test#test-a-drawing): 테스트에서 버튼을 눌러 봅니다
* [요소 레퍼런스](/docs/ko/plugins/mods/reference#elements): 각 요소의 주요 props와 해당 요소를 그리는 앱을 확인합니다
`dimColor`는 텍스트를 회색으로 그립니다. `backgroundColor`는 텍스트 너비만큼만 채웁니다.
제목은 `#` 기호 없이 굵게 그려집니다. 인라인 코드는 백틱 없이 색으로 그려집니다. 인용문은 왼쪽에 막대가 있는 기울임꼴로 그려집니다.
터미널은 레이블 뒤에 URL을 텍스트로 그립니다. 클릭으로 URL이 열리는지 여부는 사용자의 터미널에 따라 다릅니다.
색상은 사용자의 테마를 따릅니다.
Claude Code는 `@@` 줄 대신 줄 번호를 그립니다. 삭제된 줄과 추가된 줄이 비슷한 경우, 변경된 단어는 더 진한 음영으로 표시됩니다.
테두리는 창의 너비만큼 늘어납니다.
포커스가 있는 버튼은 반전 표시로 그려집니다. 다음은 사용자가 Tab을 두 번 누른 상태입니다.
포커스가 있으면 레이블이 굵게 바뀌고 커서가 나타나며, `⏎` 뒤에 `submitLabel`이 표시됩니다.
입력을 시작하면 플레이스홀더가 대체됩니다.
열린 상태에서는 옵션 목록이 표시되고 그중 하나가 강조됩니다.
사용자가 옵션을 선택하면 목록이 닫힙니다.
`Raster`는 각 색상을 더 작은 팔레트로 반올림하므로 `0x2e7d32`는 `#337733`으로 그려집니다.