CodeBlock 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

清晰展示可复制的代码，支持语法着色、行号、全屏查看和尺寸调整，适合文档与开发工具。

使用选择

用于展示可复制的代码；使用其内置复制与展开能力。需要编辑代码时先核对支持范围，不假定展示组件是编辑器。

• 通过 code 提供代码；默认显示复制与展开按钮，visibleLines 控制初始可见行数。

• singleLine 是单行展示，没有语言、行号、展开面板或纵向滚动；as="trailing" 替换右侧动作区。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { CodeBlock } from '@snowui-design-system/components';	const exampleCode = ["import { Button } from '@snowui-design-system/components';", '', "const launchLabel = 'Explore components';", '', '<Button variant="filled" href="/components">', '  {launchLabel}', '</Button>'].join('\n');</script> <CodeBlock style="background-color: var(--background-1);" code={exampleCode} language="svelte" showLineNumbers visibleLines={7} />

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

内置组件双模式

• parts.Indicator：配置内置 resize Indicator。

• 需要替换手柄结构时使用文档既有 Indicator as 职责；外置显式 Props 高于 part。

代码块组件，支持语法显示、基础语法着色、行号、复制到剪贴板与全屏放大。全屏放大/缩小使用共享元素转场的 layout 策略：实际过渡位置与尺寸，不缩放代码字形；图标切换动效使用 REPLACEMENT_APPEAR_MOTION，避免继承浮层类动效语义。

关键字速查

singleLine 单行变体

variant="singleLine" 面向 import、install command、短配置值等独占一行的只读代码条。它仍使用 <pre><code>、内置轻量语法着色和 CopyButton，不改用 Input，也不引入表单语义。

布局参考 Input 的三槽协议：

单行态固定隐藏语言、行号和全屏按钮；visibleLines、showLanguage、showLineNumbers、showExpandButton 在该变体中不产生对应结构。根层不生成 Indicator，不接受拖拽高度，也不创建纵向 scrollbar / fade；内容横向溢出时默认常显 Overlay 横向滚动条，也可通过 horizontalScrollbarVisibility="hover" 改为仅在鼠标移入代码块时显示。默认 padding 与 Input 标准态一致：上下 --padding-3（12px）、左右 --padding-4（16px）；gap 首选 --gap-2（8px），有效间距至少4 CSS px并保留更大覆盖；复用Frame singleLine保持方向，Content继续Fill，附件不压缩；显式开启响应式时，继续按Frame原协议压缩／恢复首选间距。圆角为 --radius-4（16px）。

<CodeBlock    variant="singleLine"    code="import { Button } from '@snowui-design-system/components';"/>

需要 Leading 配件时：

<CodeBlock variant="singleLine" code="pnpm add @snowui-design-system/components">    <Icon as="leading"><Package /></Icon></CodeBlock>

自动代码格式化

默认 format={true}。使用 Prettier 的浏览器入口与官方 Svelte 插件，按需加载解析器；统一 Tab 缩进（宽度 4）、80 字符目标行宽、JS 单引号、分号、无尾逗号和多属性逐行排版。保留 Svelte 区块顺序和文本空白语义；长字符串不会强制截断。HTML/Markdown 中的空白和代码内容由对应解析器处理，不使用正则改写源码。

• code 或 children 文本是只读输入；只格式化展示副本，不修改调用方的数据或示例执行代码。

• 普通态、全屏、行号、高亮和复制共享同一份可见文本。

• format={false}、variant="singleLine"、不支持的显式语言、无效语法或超过 200,000 字符的输入保持原文；格式化不是 lint，不执行代码或补全缺失逻辑。

• SSR 先输出原文，客户端加载解析器后更新显示；加载期间原文仍可读可复制。异步结果仅提交到对应的当前输入，切换代码、语言或开关不会应用过期结果。依赖加载失败时保留原文。

• 解析器来自随包声明的 MIT 依赖 prettier / prettier-plugin-svelte；运行时不向格式化服务发送代码。格式化模块位于 internal/code-block/format.ts，由 CodeBlock 拥有，未新增 Frame 能力或公共格式化 API。

<CodeBlock language="svelte" code={exampleSource} /><CodeBlock language="svelte" code={exampleSource} format={false} />

语法着色

language="text"（别名 plain、plaintext、txt）保留原文与换行；英文标识和数字使用关键字粉色，http/https URL 使用注释灰色，其余正文使用默认文字色。文本中的 // 不启动注释；字体、字号和行高与其他语言共用同一套继承规则。仅保留复制操作时，传入 showLanguage={false} 和 showExpandButton={false}；默认开关不变。

当使用 code prop 时，组件内置轻量语法着色规则，覆盖 JS / TS / JSON / HTML / CSS 常见 token。规则来自参考仓库中 shiki / rehype-pretty-code 的高亮分层思路，但当前实现不新增依赖。

颜色按 Figma 设计稿固定写死，并已在 scripts/check-standards.js 中登记为 CodeBlock.svelte 例外：

外置 style 的 background / background-* 声明在普通态、全屏进入、全屏展示和退出期间保持生效。全屏层同步这些声明及其依赖的外置 CSS 变量，保留 Token 解析与动态更新；普通态的宽高、定位和内边距不随之带入全屏。未设置外置背景时继续使用默认 Background/2。

代码块根容器默认设置 font-size: var(--text-12) 与 line-height: var(--leading-12)；内部行号、pre、code、代码行全部继承根容器排版。font-family 默认继承外部上下文，不设置具体字体族，忽略设计稿中的字体设置。

默认态与全屏态的右上 CopyButton / ExpandButton 仍使用 bare emphasis="muted" 的图标强调与复制反馈；每个按钮独立使用上下 4px、左右 8px 的 padding、8px 圆角、半透明代码块语义背景及 20px backdrop blur，hover 时继续由 Button 将强调度提升到 100%。键盘焦点有可见轮廓。singleLine 的行内 trailing 复制按钮不使用这组右上视觉。

语言标签与动作组之间的有效间距至少4 CSS px；普通态与全屏态一致，纯图标组和代码字符／行号间距不由本规则改写。工具栏使用内部 Pin 布局固定到 pin-top-right，距上边缘 8px、右边缘 4px；过长语言标签在可用宽度内省略。代码内容和纵向滚动条从工具栏下方开始，不被按钮覆盖。右下角尺寸手柄复用 Indicator appearance="corner"，仅角点附近可拖动，默认同时调整宽高；常态 2px / Black/10，自身 hover、focus 或 dragging 时变为 4px / Black/20。

内置 Icon

默认图标由真实CopyButton／ExpandButton子组件拥有并经内部ComponentIcon解析；调用方无需额外import这些内部依赖：

外置 Icon 替换

推荐使用与 Input 一致的 as="trailing" 写法替换右侧默认动作区：

<CodeBlock code="console.log('hello')">    <Icon as="trailing"><Lightning /></Icon></CodeBlock>

也保留精确替换单个内置图标的兼容入口：

Icon 动效行为

图标替换进入动效引用 REPLACEMENT_APPEAR_MOTION。具体 duration / easing / scale 以 motion preset catalog 为准，Frame appear 桥接变量名仅作为兼容入口保留。

滚动条与高度

默认代码区高度由代码内容和 visibleLines 共同控制：内容不足 visibleLines 时按内容自适应（hug 高度），内容超过后固定到 visibleLines 行并滚动。默认 visibleLines={5}，与 Textarea 的自动高度上限保持一致。右下角提供与 Textarea 一致的拖拽手柄；拖拽后进入手动高度，代码区占满容器剩余高度并滚动。

消费方可通过 style 提供初始高度；首次拖拽后，交互产生的手动高度优先于初始 style 中的 height，避免外部初始值持续覆盖拖拽写回。其余用户样式仍保持最高合并优先级。

当代码区发生垂直滚动时，顶部和尾部会显示透明渐隐。渐隐复用 layout.css 的 .snowui-scroll-mask 通用能力（即「内容渐隐层」基础共享能力的 CSS 静态形态，能力总览见 ../lib/edge-fade.md（源码参考：components/src/lib/edge-fade.md）），通过 mask-image 只改变内容 alpha，不绘制可见色块。滚动条复用 scrollbar.css 的通用浮层滚动条：

CodeBlock 的默认态、全屏态和 singleLine 都由 useOverlayScrollbar 管理横向溢出；默认态和全屏态同时管理纵向溢出。组件只声明轨道定位，滚动条尺寸、显隐、hover 形态与鼠标拖拽由共享样式承接。纵向条随宿主 hover 显隐；横向条默认在内容溢出时始终显示，horizontalScrollbarVisibility="hover" 时随宿主 hover 显隐。

Frame 能力接入说明

基础用法

<CodeBlock code={`const x = 1;`} language="ts" />

children 直接写代码

<CodeBlock language="ts">{`const x = 1;console.log(x);`}</CodeBlock>

显示行号

<CodeBlock code={codeStr} language="tsx" showLineNumbers />

设置显示行数

<CodeBlock code={codeStr} language="tsx" visibleLines={8} />

隐藏按钮

<CodeBlock code={codeStr} showCopyButton={false} showExpandButton={false} />

隐藏语言标识

<CodeBlock code={codeStr} language="tsx" showLanguage={false} />

自定义复制超时

<CodeBlock code={codeStr} copyTimeout={3000} />

外置 trailing Icon

<CodeBlock language="bash">    <Icon as="trailing"><Lightning /></Icon>    {`pnpm installpnpm build`}</CodeBlock>

布局模型

默认态主布局模型：复合管理布局（参见 LayoutProtocol.md §12.6（源码参考：specs/maintainers/LayoutProtocol.md））。singleLine 改用槽位宿主布局，根层直接管理 Leading / Content / Trailing，且不生成下列默认态的滚动、全屏与 resize 子树。

组件内部包含：

• 工具栏区域（固定在顶部，不随代码滚动）

• 可滚动代码区域（overflow-x: auto）

• 全屏覆盖层（position: fixed，按需渲染）