mod 界面元素图库

查看 Claude Code mod 可以绘制的界面元素，例如文本、按钮、输入框、Markdown、代码和 diff，并附有示例代码和终端截图。

mod 通过元素来绘制界面：文本、框、按钮、输入框，以及几个可为您格式化内容的元素。本页的示例展示了绘制各元素的代码，其中大多数还附有结果在终端窗格中的截图，方便您根据外观来挑选元素。

要了解绘制的工作原理，请从在界面中绘制开始。有关主要 props 以及哪些应用会绘制各个元素，请参阅元素参考。类型声明列出了所有 props。

试用示例

本页的示例是代码片段，而非完整的 mod。每个示例都是一个元素及其内部嵌套内容的代码。

要在您自己的终端中查看示例，请按以下步骤创建一个小型 mod，并将示例粘贴进去。该 mod 会添加一个 /gallery 命令，用于打开一个窗格并在其中绘制示例。窗格在宽屏全屏终端中是会话记录旁边的侧边栏，在其他情况下则是输入框上方带边框的区域。

{
"name": "gallery",
"version": "0.1.0",
"description": "Opens a pane that draws one sample",
"author": { "name": "Your Name" }
}

{
"modules": ["./register.js"]
}

// 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'] })
})
}

claude --plugin-dir ./gallery

选择元素

示例按您想在屏幕上显示的内容分组：

• 显示文本：Text、Markdown 和 Link
• 显示代码和更改：Code
• 排列元素：Box
• 接收输入：Button、Input 和 Select
• 绘制图形：Raster、Svg、Image 和 Client

显示文本

有三个元素可在屏幕上显示文字：Text 用于自定义样式，Markdown 用于已格式化的内容，Link 用于 URL。

`Text`

Text 使用您指定的样式绘制字符串。此示例每种样式显示一行：

Box({
  flexDirection: 'column',
  children: [
    Text({ children: ['Plain text'] }),
    Text({ bold: true, children: ['bold'] }),
    Text({ italic: true, children: ['italic'] }),
    Text({ underline: true, children: ['underline'] }),
    Text({ strikethrough: true, children: ['strikethrough'] }),
    Text({ dimColor: true, children: ['dimColor'] }),
    Text({ inverse: true, children: ['inverse'] }),
    Text({ color: 'red', children: ["color: 'red'"] }),
    Text({ backgroundColor: 'blue', children: ["backgroundColor: 'blue'"] }),
  ],
})

dimColor 以灰色绘制文本。backgroundColor 的填充宽度仅与文本相同。

`Markdown`

Markdown 按照 Claude 回复的格式来格式化文本。请通过 text 而非 children 传入内容：

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：

Link({ href: 'https://code.claude.com/docs', label: 'Claude Code docs' })

终端将 URL 作为文本绘制在标签之后。点击能否打开它取决于用户的终端。

显示代码和更改

Code 使用 Claude Code 自己的语法配色绘制源代码文本或 diff。

`Code`

指定 language，或传入 path 让 Claude Code 据此推断语言。使用 startLine 时，行号从该数字开始：

Code({
  language: 'javascript',
  startLine: 1,
  source: "const name = 'mods'\nconsole.log('hello ' + name)",
})

颜色来自用户的主题。

以 diff 形式使用 `Code`

使用 format: 'diff' 时，source 是一个或多个 unified diff hunk：

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 将其内部内容按行或列排布，并可绘制边框。此示例在一个带边框的框上方放置了一行文字：

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 键在它们之间移动，并操作获得焦点的那个控件。键盘焦点和快捷键介绍了哪些按键会传递给它们。

使用 focus: true 打开窗格会让该窗格获得键盘焦点。Input 获得焦点后才能接收键入的字母，因此对于应在窗格打开后立即接收输入的输入框，请添加 autoFocus: true。

`Button`

按钮会运行 onPress。此示例展示了默认形式、带快捷键的 plain 按钮，以及一个暗淡的按钮：

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：

Input({
  key: 'title',
  label: 'Title',
  placeholder: 'Type a title and press Enter',
  value: '',
  submitLabel: 'save',
  onSubmit: noop,
})

未获得焦点时，输入框显示其标签和占位文本：

获得焦点后，标签变为粗体，出现光标，并在 ⏎ 之后显示 submitLabel：

键入内容会替换占位文本：

`Select`

Select 让用户从多个选项中选择一个，并以该选项的 value 运行 onSelect：

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 所需的字符串。绘制彩色单元格网格对此进行了说明：

Raster({
  key: 'grid',
  columns: 3,
  rows: 2,
  cells: cellsOf([
    [['█', 0x2e7d32], ['█', 0xf9a825], ['█', 0xc62828]],
    [['█', 0x2e7d32], ['█', 0x2e7d32], ['█', 0xf9a825]],
  ]),
})

Raster 会将每种颜色近似到一个较小的调色板，因此 0x2e7d32 会绘制为 #337733。

`Svg`

Svg 在 Desktop 应用中绘制 SVG 文档：

Svg({
  alt: 'Three bars of rising height',
  width: 120,
  height: 60,
  source:
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 60"><rect x="10" y="40" width="20" height="20" fill="#2e7d32"/><rect x="50" y="25" width="20" height="35" fill="#f9a825"/><rect x="90" y="5" width="20" height="55" fill="#c62828"/></svg>',
})

在终端中，仅返回 Svg 的窗格打开后是空的。要在那里绘制其他内容，请检查 e.surface 并返回不同的元素树。

`Image` 和 `Client`

另有两个元素在此没有示例。Image 在终端中绘制 PNG 或原始像素。Client 是由您的另一个文件负责绘制的区域，用于动画和指针输入。元素参考列出了它们的 props。

除非 Claude Code 检测到终端能够绘制使用 Unicode 占位符的 kitty 图形协议图像，否则用户看到的将是以暗色显示的 Image 的 alt 文本，而不是图片。请编写能够独立表达含义的 alt 文本。检测在启动时运行：在 kitty 0.28 或更高版本以及 Ghostty 中，一旦终端响应了 Claude Code 的图形查询，检测即会成功；在以下情况下检测会失败：

• 其他终端：不属于上述两者的任何终端，或不响应该查询的终端。
• tmux 和 screen：在任何终端（包括 kitty 和 Ghostty）中运行于 tmux 或 screen 内的会话。
• 后台会话：每个后台会话，无论从哪个终端连接。

如果您的 mod 的用户在确实能够绘制这些占位符图像的终端中看到了暗色文本，可以将 CLAUDE_CODE_FORCE_TERMINAL_IMAGES 设置为 1，以跳过检测。在 tmux 或 screen 中这样做并无帮助：alt 文本会消失，而 Claude Code 发送图片时不会为 tmux 或 screen 直通对其进行包装。

了解 mod 可以在哪里绘制

这些示例都在窗格中绘制。mod 还可以在其他位置绘制，并可调用 Claude Code 为其显示内容：

• 窗格和横条：选择绘制位置
• Claude Code 自身的行，例如加载动画：更改 Claude Code 已绘制的内容
• Toast 通知、状态栏和日志行：在不开启轮次的情况下显示内容
• 问题对话框：暂停工具调用直到用户做出决定

后续步骤

• 在界面中绘制：逐步构建一个带标签页的窗格
• 测试绘制结果：在测试中按下您的按钮
• 元素参考：每个元素的主要 props 以及绘制它的应用