ZCode 中的 AI Elements CodeBlock 组件实战语法高亮、行号与一键复制【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode本篇文章聚焦 ZCode 仓库中 AI Elements 组件体系里的CodeBlock组件讲解其安装方式、可组合composable架构、完整 Props 列表并结合packages/ui/src/components/ai-elements/code-block.tsx的源码实现剖析语法高亮、行号、一键复制、主题切换与 Mermaid 渲染背后的原理。读完本文你将能够在 ZCode 的 UI 工程中熟练组装、定制并扩展CodeBlock让 AI 会话中的代码展示既专业又易用。CodeBlock 是什么CodeBlock是 AI Elements 组件库为代码块提供的一体化展示组件核心能力包括语法高亮Syntax Highlighting、行号Line Numbers与复制到剪贴板Copy to Clipboard。它最大的特点是完全可组合fully composable——头部Header、动作按钮Actions与内容区域都可以自由定制而不是一个锁死的黑盒。在 ZCode 仓库中该组件由 Vercel 的 vercel/ai-elements并遵循 Apache-2.0 许可许可与来源信息见仓库根目录的 THIRD-PARTY-NOTICES.md。它在 ZCode 的桌面端 UI 中被大量用于展示工具调用结果例如 ToolCallBlocks/renderers/mcp.tsx 中的 MCP 工具返回、eval-workflow-snippet工作流代码片段、node-repl执行输出等场景。安装在 ZCode 项目中安装CodeBlock组件使用 AI Elements 提供的 CLI 即可npx ai-elementslatest add code-block注意请始终使用项目packageManager对应的包运行器执行 CLI 命令如npx ai-elementslatest、pnpm dlx ai-elementslatest或bunx --bun ai-elementslatest下面示例统一用npx书写。安装前置条件与 AI Elements 整体要求一致Node.js 18、一个已集成 AI SDK 的 Next.js 项目以及已配置好的 shadcn/ui未安装时 CLI 会自动安装。默认情况下组件会被添加到项目的/components/ai-elements/目录安装成功后即可像普通 React 组件一样导入使用。基本用法CodeBlock采用可组合架构代码内容与界面元素分离先看一个最基础的示例完整示例见 .agents/skills/ai-elements/scripts/code-block.tsximport { CodeBlock, CodeBlockActions, CodeBlockCopyButton, CodeBlockFilename, CodeBlockHeader, CodeBlockTitle, } from /components/ai-elements/code-block; import { FileIcon } from lucide-react; export const Example () ( CodeBlock code{code} languagetypescript CodeBlockHeader CodeBlockTitle FileIcon size{14} / CodeBlockFilenameexample.ts/CodeBlockFilename /CodeBlockTitle CodeBlockActions CodeBlockCopyButton / /CodeBlockActions /CodeBlockHeader /CodeBlock );这里的组合关系是CodeBlock负责承载代码与高亮渲染CodeBlockHeader是顶部工具条容器CodeBlockTitle放文件名与图标CodeBlockActions放右侧动作按钮如复制按钮。你也可以不传任何子元素——ZCode 的实现里CodeBlockHeader内置了默认头部自动生成文件名与复制按钮此时组件开箱即用。组合式架构的核心价值正因为头部与内容分离你可以在CodeBlockTitle中自由组合图标、文件名乃至任意 React 节点在CodeBlockActions中任意排列复制按钮、语言选择器、换行开关等动作传入children之外还可以通过contentClassName独立控制正文区域的限高避免滚动时把 Header 上的复制/换行按钮一起卷走。功能特性CodeBlock提供的功能清单如下基于 Shiki 的语法高亮Syntax highlighting with Shiki可选的行号Line numbers, optional复制到剪贴板Copy to clipboard functionality通过 CSS 变量自动切换明暗主题Automatic light/dark theme switching via CSS variables面向多语言示例的语言选择器Language selector for multi-language examples完全可组合的架构Fully composable architecture无障碍设计Accessible design示例暗色模式在暗色模式下使用CodeBlock只需将其包裹在带darkclass 的div中即可div classNamedark CodeBlock code{code} languagejsx CodeBlockHeader CodeBlockTitle FileIcon size{14} / CodeBlockFilenameMyComponent.jsx/CodeBlockFilename /CodeBlockTitle CodeBlockActions CodeBlockCopyButton onCopy{handleCopy} onError{handleCopyError} / /CodeBlockActions /CodeBlockHeader /CodeBlock /div完整示例见 .agents/skills/ai-elements/scripts/code-block-dark.tsx。其主题切换原理是ZCode 的CodeViewer通过 CSS 变量如--diffs-bg、--diffs-light-bg、--diffs-dark-bg与根元素上的darkclass 配合实现明暗配色自动切换组件自身无需在 JS 中维护主题状态。示例语言选择器语言选择器用于在同一代码块中切换不同语言的实现如 TypeScript / Python / Rust / Go其组合方式如下完整示例见 .agents/skills/ai-elements/scripts/code-block.tsxCodeBlock code{code} language{language} CodeBlockHeader CodeBlockTitle FileIcon size{14} / CodeBlockFilename{filename}/CodeBlockFilename /CodeBlockTitle CodeBlockActions CodeBlockLanguageSelector onValueChange{handleLanguageChange} value{language} CodeBlockLanguageSelectorTrigger CodeBlockLanguageSelectorValue / /CodeBlockLanguageSelectorTrigger CodeBlockLanguageSelectorContent {languages.map((lang) ( CodeBlockLanguageSelectorItem key{lang.value} value{lang.value} {lang.label} /CodeBlockLanguageSelectorItem ))} /CodeBlockLanguageSelectorContent /CodeBlockLanguageSelector CodeBlockCopyButton onCopy{handleCopy} onError{handleCopyError} / /CodeBlockActions /CodeBlock /CodeBlock语言选择器基于 shadcn/ui 的Select组件封装触发按钮、值展示、下拉内容与选项项全部拆分为独立子组件便于按需替换样式。切换语言时只需更新CodeBlock的code与language两个 Props即可实现高亮语言与代码内容的联动刷新。Props 完整参考以下 Props 表完整继承自组件文档并结合 ZCode 源码实现补充说明。CodeBlock /PropTypeDefaultDescriptioncodestring-要展示的代码内容。languageBundledLanguage-用于语法高亮的编程语言。showLineNumbersbooleanfalse是否显示行号。childrenReact.ReactNode-子元素如CodeBlockHeader。classNamestring-附加 CSS 类。ZCode 扩展 Props见 code-block.tsx——这些 Props 在原文档基础上由 ZCode 本地化整合时加入值得重点掌握PropTypeDefaultDescriptionenableSyntaxHighlightingbooleantrue是否启用语法高亮关闭后仅做纯文本渲染。themeBundledTheme-透传给 Shiki 的高亮主题占用theme名。appThemeTheme-应用主题仅透传给 Mermaid 渲染分支theme已被 Shiki 占用故另起名。缺省时 Mermaid 按system兜底。wrapLongLinesbooleanfalse长行是否自动换行。fontSizePxnumber14正文字号像素。renderMermaidbooleantrue是否启用 Mermaid 图表代码块的自动渲染。contentClassNamestring-正文独立限高避免滚动时 Header 的复制/换行按钮一起被卷走。focusedRange{ startLine: number; endLine: number } \| nullnull行定位高亮行区间配合focusRequestId触发滚动到该区间。focusRequestIdstring-变化时触发滚动到focusedRange指定区间。markedLinesreadonly number[]-需要点名警示的行号1 起只把行号染成警示色编译反馈卡用它标出被诊断指到的行。CodeBlockHeader /头部行的容器使用justify-between的 flexbox 布局ZCode 实现为flex items-center justify-between gap-3 px-3 py-2。PropTypeDefaultDescriptionchildrenReact.ReactNode-头部内容CodeBlockTitle、CodeBlockActions等。classNamestring-附加 CSS 类。ZCode 扩展 PropsdisplayFile?: string覆盖按语言推断的展示文件名、language?: string用于自动推断文件名与语言标签、showWrapButton?: boolean默认true控制是否显示换行按钮。不传children时Header 会根据语言自动生成“文件图标 语言名 动作按钮Mermaid 预览 / 换行 / 复制”的默认头部。CodeBlockTitle /左对齐的标题容器图标 文件名使用gap-2的 flexbox 布局。PropTypeDefaultDescriptionchildrenReact.ReactNode-标题内容图标、CodeBlockFilename等。classNamestring-附加 CSS 类。CodeBlockFilename /以等宽字体font-mono展示文件名。PropTypeDefaultDescriptionchildrenReact.ReactNode-要显示的文件名。classNamestring-附加 CSS 类。CodeBlockActions /右对齐的动作按钮容器使用gap-2的 flexbox 布局ZCode 实现为flex items-center gap-1并带负外边距对齐头部边缘。PropTypeDefaultDescriptionchildrenReact.ReactNode-动作按钮CodeBlockCopyButton、CodeBlockLanguageSelector等。classNamestring-附加 CSS 类。CodeBlockCopyButton /PropTypeDefaultDescriptiononCopy() void-复制成功后的回调。onError(error: Error) void-复制失败时的回调。timeoutnumber2000“已复制”状态显示的时长毫秒。childrenReact.ReactNode-按钮的自定义内容默认是复制/勾选图标。classNamestring-附加 CSS 类。实现要点code-block.tsx复制通过navigator.clipboard.writeText实现当浏览器环境缺少 Clipboard API 时会立即回调onError点击后进入isCopied状态图标从复制切换为勾选并在timeout默认 2000ms后自动复原组件卸载时会清理定时器避免内存泄漏。按钮自带aria-label与 tooltip保证无障碍体验。CodeBlockLanguageSelector /语言选择器容器继承 shadcn/ui 的Select组件。PropTypeDefaultDescriptionvaluestring-当前选中的语言。onValueChange(value: string) void-语言变化时的回调。childrenReact.ReactNode-选择器子组件Trigger、Content、Items。CodeBlockLanguageSelectorTrigger /语言选择器下拉的触发按钮已针对代码块头部预置样式无边框、透明背景、小尺寸。CodeBlockLanguageSelectorValue /展示当前选中的语言值。CodeBlockLanguageSelectorContent /下拉内容容器默认alignend右对齐。CodeBlockLanguageSelectorItem /下拉中的单个语言选项。PropTypeDefaultDescriptionvaluestring-语言值。childrenReact.ReactNode-展示标签。CodeBlockContainer /底层容器组件带性能优化contentVisibility由CodeBlock内部使用。ZCode 实现code-block.tsx细节如下类名group relative w-full overflow-hidden rounded-xl bg-background text-foreground支持圆角与背景适配主题通过containIntrinsicSize: auto 200px与contentVisibility: auto让浏览器在代码块滚出视口时跳过渲染同时预留约 200px 的固有高度避免长列表如消息流出现滚动性能问题通过data-language属性暴露语言信息便于外部选择器定位。CodeBlockContent /底层组件负责语法高亮由CodeBlock内部使用也可直接用于自定义布局。PropTypeDefaultDescriptioncodestring-要展示的代码内容。languageBundledLanguage-用于语法高亮的编程语言。showLineNumbersbooleanfalse是否显示行号。ZCode 源码级纵深CodeBlock 的扩展实现默认文件名的语言推断CodeBlockHeader在未显式传displayFile时会通过 LANGUAGE_DISPLAY_FILE_BY_LANGUAGE 映射表按语言推断展示文件名例如typescript/ts对应index.ts、python/py对应main.py、markdown/md对应README.md、yaml/yml对应config.yaml等未命中时回退为code.language。这让没有显式文件名的代码块也能展示直观的文件标签。Mermaid 代码块自动渲染ZCode 为CodeBlock引入了 Mermaid 图表渲染分支renderMermaid默认开启。当shouldRenderMermaidCodeBlock(language, code)判定为 Mermaid 语言时组件会通过useDocumentVisibilityRevision监听页面visibilitychange仅在页面可见时推进渲染预算调用resolveMermaidAutoRenderDecision决定是否立即渲染避免在不可见页面浪费渲染资源渲染成功后在 Header 显示“放大预览”按钮CodeBlockMermaidPreviewButton点击可打开DiagramPreviewDialog全屏查看 SVG。这一机制由 mermaidLanguage.ts 与 mermaidRenderBudget.ts 支撑体现了代码块组件在真实 AI 会话场景中的性能取舍。与 CodeViewer 的协作当代码不是 Mermaid 时正文交由 components/ui/code-viewer.tsx 渲染。CodeViewer基于pierre/diffs实现支持语法高亮、行号、长行换行、focusedRange滚动高亮与markedLines警示行号。CodeBlock向它透传这些能力并额外覆盖一组 CSS 变量--diffs-bg、--diffs-light-bg、--diffs-dark-bg、--diffs-gap-block确保在 Markdown 卡片背景下行间距与配色一致。这也解释了CodeBlock为何能支持“行定位”“诊断行标注”这类编辑器级能力——它们全部来自CodeViewer的底层实现。真实调用场景在 ZCode 的 UI 中CodeBlock是消息流与工具调用展示的事实标准。以 ToolCallBlocks/renderers/mcp.tsx 为例MCP 工具返回的 JSON 结果会序列化为字符串stringifyMcpResult对非字符串结果做JSON.stringify(value, null, 2)美化然后交给CodeBlock展示Header 中组合CodeBlockWrapButton长结果换行开关与CodeBlockCopyButton复制当结果超过COMPACT_RESULT_MAX_LENGTH160 字符时进入折叠态并显式覆盖contentVisibility为visible以配合折叠面板。类似用法还出现在eval-workflow-snippet、node-repl、submit-result等多个渲染器中CodeBlock已成为 ZCode 代码呈现的统一抽象层。无障碍与可访问性CodeBlock的无障碍设计体现在多处复制按钮带aria-label未指定时使用 i18n 文案codeBlock.copyCode与 tooltip换行按钮带aria-pressed状态屏幕阅读器可感知开关状态Mermaid 预览按钮在预览不可用时自动disabled所有图标按钮均通过ControlHintTooltip提供悬停提示。由于组件代码直接存在于项目源码中你完全可以按需调整这些细节使其更贴合你的无障碍标准。小结与最佳实践优先组合而非覆盖CodeBlockHeader/CodeBlockTitle/CodeBlockActions的组合足够表达绝大多数头部布局无需重写整个组件善用扩展 Props长代码场景开启wrapLongLines编译诊断场景使用markedLines与focusedRange图表场景依赖默认开启的renderMermaid依赖源码确认行为复制按钮依赖 Clipboard API、主题依赖 CSS 变量与根元素darkclass、性能依赖contentVisibility——这些行为都可直接在 code-block.tsx 与 code-viewer.tsx 中验证是排查“样式未生效”“复制失败”“滚动卡顿”等问题的第一现场。组件文档的其余部分安装前置条件、组件导入路径、示例脚本分别见 .agents/skills/ai-elements/SKILL.md 与 .agents/skills/ai-elements/scripts/ 目录下的示例文件可作为继续深入 AI Elements 组件体系的入口。【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZCode 中的 AI Elements CodeBlock 组件实战：语法高亮、行号与一键复制
ZCode 中的 AI Elements CodeBlock 组件实战语法高亮、行号与一键复制【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode本篇文章聚焦 ZCode 仓库中 AI Elements 组件体系里的CodeBlock组件讲解其安装方式、可组合composable架构、完整 Props 列表并结合packages/ui/src/components/ai-elements/code-block.tsx的源码实现剖析语法高亮、行号、一键复制、主题切换与 Mermaid 渲染背后的原理。读完本文你将能够在 ZCode 的 UI 工程中熟练组装、定制并扩展CodeBlock让 AI 会话中的代码展示既专业又易用。CodeBlock 是什么CodeBlock是 AI Elements 组件库为代码块提供的一体化展示组件核心能力包括语法高亮Syntax Highlighting、行号Line Numbers与复制到剪贴板Copy to Clipboard。它最大的特点是完全可组合fully composable——头部Header、动作按钮Actions与内容区域都可以自由定制而不是一个锁死的黑盒。在 ZCode 仓库中该组件由 Vercel 的 vercel/ai-elements并遵循 Apache-2.0 许可许可与来源信息见仓库根目录的 THIRD-PARTY-NOTICES.md。它在 ZCode 的桌面端 UI 中被大量用于展示工具调用结果例如 ToolCallBlocks/renderers/mcp.tsx 中的 MCP 工具返回、eval-workflow-snippet工作流代码片段、node-repl执行输出等场景。安装在 ZCode 项目中安装CodeBlock组件使用 AI Elements 提供的 CLI 即可npx ai-elementslatest add code-block注意请始终使用项目packageManager对应的包运行器执行 CLI 命令如npx ai-elementslatest、pnpm dlx ai-elementslatest或bunx --bun ai-elementslatest下面示例统一用npx书写。安装前置条件与 AI Elements 整体要求一致Node.js 18、一个已集成 AI SDK 的 Next.js 项目以及已配置好的 shadcn/ui未安装时 CLI 会自动安装。默认情况下组件会被添加到项目的/components/ai-elements/目录安装成功后即可像普通 React 组件一样导入使用。基本用法CodeBlock采用可组合架构代码内容与界面元素分离先看一个最基础的示例完整示例见 .agents/skills/ai-elements/scripts/code-block.tsximport { CodeBlock, CodeBlockActions, CodeBlockCopyButton, CodeBlockFilename, CodeBlockHeader, CodeBlockTitle, } from /components/ai-elements/code-block; import { FileIcon } from lucide-react; export const Example () ( CodeBlock code{code} languagetypescript CodeBlockHeader CodeBlockTitle FileIcon size{14} / CodeBlockFilenameexample.ts/CodeBlockFilename /CodeBlockTitle CodeBlockActions CodeBlockCopyButton / /CodeBlockActions /CodeBlockHeader /CodeBlock );这里的组合关系是CodeBlock负责承载代码与高亮渲染CodeBlockHeader是顶部工具条容器CodeBlockTitle放文件名与图标CodeBlockActions放右侧动作按钮如复制按钮。你也可以不传任何子元素——ZCode 的实现里CodeBlockHeader内置了默认头部自动生成文件名与复制按钮此时组件开箱即用。组合式架构的核心价值正因为头部与内容分离你可以在CodeBlockTitle中自由组合图标、文件名乃至任意 React 节点在CodeBlockActions中任意排列复制按钮、语言选择器、换行开关等动作传入children之外还可以通过contentClassName独立控制正文区域的限高避免滚动时把 Header 上的复制/换行按钮一起卷走。功能特性CodeBlock提供的功能清单如下基于 Shiki 的语法高亮Syntax highlighting with Shiki可选的行号Line numbers, optional复制到剪贴板Copy to clipboard functionality通过 CSS 变量自动切换明暗主题Automatic light/dark theme switching via CSS variables面向多语言示例的语言选择器Language selector for multi-language examples完全可组合的架构Fully composable architecture无障碍设计Accessible design示例暗色模式在暗色模式下使用CodeBlock只需将其包裹在带darkclass 的div中即可div classNamedark CodeBlock code{code} languagejsx CodeBlockHeader CodeBlockTitle FileIcon size{14} / CodeBlockFilenameMyComponent.jsx/CodeBlockFilename /CodeBlockTitle CodeBlockActions CodeBlockCopyButton onCopy{handleCopy} onError{handleCopyError} / /CodeBlockActions /CodeBlockHeader /CodeBlock /div完整示例见 .agents/skills/ai-elements/scripts/code-block-dark.tsx。其主题切换原理是ZCode 的CodeViewer通过 CSS 变量如--diffs-bg、--diffs-light-bg、--diffs-dark-bg与根元素上的darkclass 配合实现明暗配色自动切换组件自身无需在 JS 中维护主题状态。示例语言选择器语言选择器用于在同一代码块中切换不同语言的实现如 TypeScript / Python / Rust / Go其组合方式如下完整示例见 .agents/skills/ai-elements/scripts/code-block.tsxCodeBlock code{code} language{language} CodeBlockHeader CodeBlockTitle FileIcon size{14} / CodeBlockFilename{filename}/CodeBlockFilename /CodeBlockTitle CodeBlockActions CodeBlockLanguageSelector onValueChange{handleLanguageChange} value{language} CodeBlockLanguageSelectorTrigger CodeBlockLanguageSelectorValue / /CodeBlockLanguageSelectorTrigger CodeBlockLanguageSelectorContent {languages.map((lang) ( CodeBlockLanguageSelectorItem key{lang.value} value{lang.value} {lang.label} /CodeBlockLanguageSelectorItem ))} /CodeBlockLanguageSelectorContent /CodeBlockLanguageSelector CodeBlockCopyButton onCopy{handleCopy} onError{handleCopyError} / /CodeBlockActions /CodeBlock /CodeBlock语言选择器基于 shadcn/ui 的Select组件封装触发按钮、值展示、下拉内容与选项项全部拆分为独立子组件便于按需替换样式。切换语言时只需更新CodeBlock的code与language两个 Props即可实现高亮语言与代码内容的联动刷新。Props 完整参考以下 Props 表完整继承自组件文档并结合 ZCode 源码实现补充说明。CodeBlock /PropTypeDefaultDescriptioncodestring-要展示的代码内容。languageBundledLanguage-用于语法高亮的编程语言。showLineNumbersbooleanfalse是否显示行号。childrenReact.ReactNode-子元素如CodeBlockHeader。classNamestring-附加 CSS 类。ZCode 扩展 Props见 code-block.tsx——这些 Props 在原文档基础上由 ZCode 本地化整合时加入值得重点掌握PropTypeDefaultDescriptionenableSyntaxHighlightingbooleantrue是否启用语法高亮关闭后仅做纯文本渲染。themeBundledTheme-透传给 Shiki 的高亮主题占用theme名。appThemeTheme-应用主题仅透传给 Mermaid 渲染分支theme已被 Shiki 占用故另起名。缺省时 Mermaid 按system兜底。wrapLongLinesbooleanfalse长行是否自动换行。fontSizePxnumber14正文字号像素。renderMermaidbooleantrue是否启用 Mermaid 图表代码块的自动渲染。contentClassNamestring-正文独立限高避免滚动时 Header 的复制/换行按钮一起被卷走。focusedRange{ startLine: number; endLine: number } \| nullnull行定位高亮行区间配合focusRequestId触发滚动到该区间。focusRequestIdstring-变化时触发滚动到focusedRange指定区间。markedLinesreadonly number[]-需要点名警示的行号1 起只把行号染成警示色编译反馈卡用它标出被诊断指到的行。CodeBlockHeader /头部行的容器使用justify-between的 flexbox 布局ZCode 实现为flex items-center justify-between gap-3 px-3 py-2。PropTypeDefaultDescriptionchildrenReact.ReactNode-头部内容CodeBlockTitle、CodeBlockActions等。classNamestring-附加 CSS 类。ZCode 扩展 PropsdisplayFile?: string覆盖按语言推断的展示文件名、language?: string用于自动推断文件名与语言标签、showWrapButton?: boolean默认true控制是否显示换行按钮。不传children时Header 会根据语言自动生成“文件图标 语言名 动作按钮Mermaid 预览 / 换行 / 复制”的默认头部。CodeBlockTitle /左对齐的标题容器图标 文件名使用gap-2的 flexbox 布局。PropTypeDefaultDescriptionchildrenReact.ReactNode-标题内容图标、CodeBlockFilename等。classNamestring-附加 CSS 类。CodeBlockFilename /以等宽字体font-mono展示文件名。PropTypeDefaultDescriptionchildrenReact.ReactNode-要显示的文件名。classNamestring-附加 CSS 类。CodeBlockActions /右对齐的动作按钮容器使用gap-2的 flexbox 布局ZCode 实现为flex items-center gap-1并带负外边距对齐头部边缘。PropTypeDefaultDescriptionchildrenReact.ReactNode-动作按钮CodeBlockCopyButton、CodeBlockLanguageSelector等。classNamestring-附加 CSS 类。CodeBlockCopyButton /PropTypeDefaultDescriptiononCopy() void-复制成功后的回调。onError(error: Error) void-复制失败时的回调。timeoutnumber2000“已复制”状态显示的时长毫秒。childrenReact.ReactNode-按钮的自定义内容默认是复制/勾选图标。classNamestring-附加 CSS 类。实现要点code-block.tsx复制通过navigator.clipboard.writeText实现当浏览器环境缺少 Clipboard API 时会立即回调onError点击后进入isCopied状态图标从复制切换为勾选并在timeout默认 2000ms后自动复原组件卸载时会清理定时器避免内存泄漏。按钮自带aria-label与 tooltip保证无障碍体验。CodeBlockLanguageSelector /语言选择器容器继承 shadcn/ui 的Select组件。PropTypeDefaultDescriptionvaluestring-当前选中的语言。onValueChange(value: string) void-语言变化时的回调。childrenReact.ReactNode-选择器子组件Trigger、Content、Items。CodeBlockLanguageSelectorTrigger /语言选择器下拉的触发按钮已针对代码块头部预置样式无边框、透明背景、小尺寸。CodeBlockLanguageSelectorValue /展示当前选中的语言值。CodeBlockLanguageSelectorContent /下拉内容容器默认alignend右对齐。CodeBlockLanguageSelectorItem /下拉中的单个语言选项。PropTypeDefaultDescriptionvaluestring-语言值。childrenReact.ReactNode-展示标签。CodeBlockContainer /底层容器组件带性能优化contentVisibility由CodeBlock内部使用。ZCode 实现code-block.tsx细节如下类名group relative w-full overflow-hidden rounded-xl bg-background text-foreground支持圆角与背景适配主题通过containIntrinsicSize: auto 200px与contentVisibility: auto让浏览器在代码块滚出视口时跳过渲染同时预留约 200px 的固有高度避免长列表如消息流出现滚动性能问题通过data-language属性暴露语言信息便于外部选择器定位。CodeBlockContent /底层组件负责语法高亮由CodeBlock内部使用也可直接用于自定义布局。PropTypeDefaultDescriptioncodestring-要展示的代码内容。languageBundledLanguage-用于语法高亮的编程语言。showLineNumbersbooleanfalse是否显示行号。ZCode 源码级纵深CodeBlock 的扩展实现默认文件名的语言推断CodeBlockHeader在未显式传displayFile时会通过 LANGUAGE_DISPLAY_FILE_BY_LANGUAGE 映射表按语言推断展示文件名例如typescript/ts对应index.ts、python/py对应main.py、markdown/md对应README.md、yaml/yml对应config.yaml等未命中时回退为code.language。这让没有显式文件名的代码块也能展示直观的文件标签。Mermaid 代码块自动渲染ZCode 为CodeBlock引入了 Mermaid 图表渲染分支renderMermaid默认开启。当shouldRenderMermaidCodeBlock(language, code)判定为 Mermaid 语言时组件会通过useDocumentVisibilityRevision监听页面visibilitychange仅在页面可见时推进渲染预算调用resolveMermaidAutoRenderDecision决定是否立即渲染避免在不可见页面浪费渲染资源渲染成功后在 Header 显示“放大预览”按钮CodeBlockMermaidPreviewButton点击可打开DiagramPreviewDialog全屏查看 SVG。这一机制由 mermaidLanguage.ts 与 mermaidRenderBudget.ts 支撑体现了代码块组件在真实 AI 会话场景中的性能取舍。与 CodeViewer 的协作当代码不是 Mermaid 时正文交由 components/ui/code-viewer.tsx 渲染。CodeViewer基于pierre/diffs实现支持语法高亮、行号、长行换行、focusedRange滚动高亮与markedLines警示行号。CodeBlock向它透传这些能力并额外覆盖一组 CSS 变量--diffs-bg、--diffs-light-bg、--diffs-dark-bg、--diffs-gap-block确保在 Markdown 卡片背景下行间距与配色一致。这也解释了CodeBlock为何能支持“行定位”“诊断行标注”这类编辑器级能力——它们全部来自CodeViewer的底层实现。真实调用场景在 ZCode 的 UI 中CodeBlock是消息流与工具调用展示的事实标准。以 ToolCallBlocks/renderers/mcp.tsx 为例MCP 工具返回的 JSON 结果会序列化为字符串stringifyMcpResult对非字符串结果做JSON.stringify(value, null, 2)美化然后交给CodeBlock展示Header 中组合CodeBlockWrapButton长结果换行开关与CodeBlockCopyButton复制当结果超过COMPACT_RESULT_MAX_LENGTH160 字符时进入折叠态并显式覆盖contentVisibility为visible以配合折叠面板。类似用法还出现在eval-workflow-snippet、node-repl、submit-result等多个渲染器中CodeBlock已成为 ZCode 代码呈现的统一抽象层。无障碍与可访问性CodeBlock的无障碍设计体现在多处复制按钮带aria-label未指定时使用 i18n 文案codeBlock.copyCode与 tooltip换行按钮带aria-pressed状态屏幕阅读器可感知开关状态Mermaid 预览按钮在预览不可用时自动disabled所有图标按钮均通过ControlHintTooltip提供悬停提示。由于组件代码直接存在于项目源码中你完全可以按需调整这些细节使其更贴合你的无障碍标准。小结与最佳实践优先组合而非覆盖CodeBlockHeader/CodeBlockTitle/CodeBlockActions的组合足够表达绝大多数头部布局无需重写整个组件善用扩展 Props长代码场景开启wrapLongLines编译诊断场景使用markedLines与focusedRange图表场景依赖默认开启的renderMermaid依赖源码确认行为复制按钮依赖 Clipboard API、主题依赖 CSS 变量与根元素darkclass、性能依赖contentVisibility——这些行为都可直接在 code-block.tsx 与 code-viewer.tsx 中验证是排查“样式未生效”“复制失败”“滚动卡顿”等问题的第一现场。组件文档的其余部分安装前置条件、组件导入路径、示例脚本分别见 .agents/skills/ai-elements/SKILL.md 与 .agents/skills/ai-elements/scripts/ 目录下的示例文件可作为继续深入 AI Elements 组件体系的入口。【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考