iter(g270): 新增代码块组件

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T14:53:11.893Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T14:54:40.928Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2258,6 +2258,35 @@ diffView({ before: oldText, after: newText })
 
 现场演示：apps/docs/demo.html#sec-diff
 
+### codeBlock — 代码块 CodeBlock
+
+参数：
+
+- code：string —— 代码原文：显示与复制都用它（不读 DOM，避免行号混进剪贴板）
+- lang：string —— 语言名（如 ts / css）；无 title 时作头部标题
+- title：string —— 头部标题（如文件名）；优先于 lang
+- lineNumbers：boolean —— 是否显示行号列；缺省 true（单行代码自动省略）
+- maxHeight：number —— 代码区最高高度（px），超出在框内滚动；缺省不限高
+- copyable：boolean —— 右上角是否出现复制按钮；缺省 true
+- onCopy：(text: string) => void —— 复制成功回调（参数为实际写入剪贴板的内容）
+- ariaLabel：string —— 可访问名；缺省「代码块」
+
+示例：
+
+```
+codeBlock({ code: source, title: 'main.ts', lang: 'ts', maxHeight: 320 })
+```
+
+手把手：
+
+1. 把代码原文交给 code：显示与复制都读这一份，不要从 DOM 里取文本（行号会污染剪贴板）
+2. 头部标题用 title（文件名）或 lang（语言名），两者都给时 title 优先
+3. 长代码给 maxHeight，超出在框内滚动；滚动条已是统一细条，暗色下不会露原生亮条
+4. 单行代码自动省掉行号列；想彻底不要行号传 lineNumbers: false
+5. 不需要复制按钮（例如代码本身是操作步骤）传 copyable: false；连标题都没有时头部整条省掉
+
+现场演示：apps/docs/demo.html#sec-code
+
 API 速览：
 
 - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调
@@ -2341,6 +2370,7 @@ API 速览：
 - layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）
 - jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑
 - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计
+- codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮
 
 一行用法：