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

2026-10-26 22:54:55 +08:00
parent 02d7eb3c4d
commit b8f90b8e0d
12 changed files with 272 additions and 11 deletions
@@ -0,0 +1,30 @@
+import { h } from '@ui-arch/frame';
+import { copyButton } from './copyButton.js';
+import type { CodeBlockProps } from './types.js';
+
+/*** 代码块：等宽渲染多行代码，可选行号列与标题行（语言 / 文件名），右上角一键复制原文；只做展示不做高亮 ***/
+export function codeBlock(props: CodeBlockProps): HTMLElement {
+  const lines = props.code.replace(/\r?\n$/, '').split(/\r?\n/); // 末尾换行不生成空行：复制走原文，显示不多一行
+  const showNo = props.lineNumbers !== false && lines.length > 1; // 单行代码给行号只是噪音
+  const body = h(
+    'div',
+    { class: 'ua-code-body' },
+    ...lines.map((text, i) => h(
+      'div',
+      { class: 'ua-code-line' },
+      showNo ? h('span', { class: 'ua-code-no', 'aria-hidden': 'true' }, String(i + 1)) : null, // 行号是装饰，读屏跳过
+      h('span', { class: 'ua-code-text' }, text || ' '), // 空行补一个空格，撑住行高
+    )),
+  );
+  if (props.maxHeight !== undefined) body.style.maxHeight = `${props.maxHeight}px`; // 只在给了上限时限高，超出内部滚动
+  const title = props.title ?? props.lang; // 标题优先用文件名，其次语言名
+  const head = props.copyable === false && !title
+    ? null // 既无标题也不可复制：整个头部省掉，不留空条
+    : h(
+      'div',
+      { class: 'ua-code-head' },
+      title ? h('span', { class: 'ua-code-title' }, title) : h('span', null, ''),
+      props.copyable === false ? null : copyButton({ text: props.code, label: '复制', size: 'sm', variant: 'ghost', onCopied: props.onCopy }),
+    );
+  return h('div', { class: 'ua-code', role: 'group', 'aria-label': props.ariaLabel ?? '代码块' }, head, body);
+}
@@ -79,3 +79,4 @@ export { inputTag } from './inputTag.js';
 export { layout } from './layout.js';
 export { jsonViewer } from './jsonViewer.js';
 export { diffView } from './diffView.js';
+export { codeBlock } from './codeBlock.js';
@@ -1038,3 +1038,15 @@ export interface DiffViewProps {
  showStats?: boolean;             // 是否在顶部显示 +N / −N 统计条；缺省 true
  ariaLabel?: string;              // 可访问名；缺省自动播报「新增 N 行，删除 M 行」
 }
+
+/*** 代码块入参 ***/
+export interface CodeBlockProps {
+  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;              // 可访问名；缺省「代码块」
+}
@@ -93,7 +93,8 @@
      "inputTag(props)：标签输入，输入后回车 / 逗号成标签、chip 可单个删除、空框退格删末个，value 信号双向绑定，max 满额自动禁输",
      "layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）",
      "jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑",
-      "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计"
+      "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
+      "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮"
    ],
    "keyTypes": [
      "ButtonProps",
@@ -4111,6 +4112,61 @@
          "顶部统计条给 +N / −N，读屏在容器上直接播报同一组数字，不必逐行听",
          "超大文本（中间段行数乘积超过 40 万）会退化成「整段替换」——语义仍对，只是不再逐行对齐；要逐行对齐就先分段比对"
        ]
+      },
+      {
+        "id": "codeBlock",
+        "title": "代码块 CodeBlock",
+        "demo": "sec-code",
+        "props": [
+          {
+            "n": "code",
+            "t": "string",
+            "d": "代码原文：显示与复制都用它（不读 DOM，避免行号混进剪贴板）"
+          },
+          {
+            "n": "lang",
+            "t": "string",
+            "d": "语言名（如 ts / css）；无 title 时作头部标题"
+          },
+          {
+            "n": "title",
+            "t": "string",
+            "d": "头部标题（如文件名）；优先于 lang"
+          },
+          {
+            "n": "lineNumbers",
+            "t": "boolean",
+            "d": "是否显示行号列；缺省 true（单行代码自动省略）"
+          },
+          {
+            "n": "maxHeight",
+            "t": "number",
+            "d": "代码区最高高度（px），超出在框内滚动；缺省不限高"
+          },
+          {
+            "n": "copyable",
+            "t": "boolean",
+            "d": "右上角是否出现复制按钮；缺省 true"
+          },
+          {
+            "n": "onCopy",
+            "t": "(text: string) => void",
+            "d": "复制成功回调（参数为实际写入剪贴板的内容）"
+          },
+          {
+            "n": "ariaLabel",
+            "t": "string",
+            "d": "可访问名；缺省「代码块」"
+          }
+        ],
+        "example": "codeBlock({ code: source, title: 'main.ts', lang: 'ts', maxHeight: 320 })",
+        "steps": [
+          "把代码原文交给 code：显示与复制都读这一份，不要从 DOM 里取文本（行号会污染剪贴板）",
+          "头部标题用 title（文件名）或 lang（语言名），两者都给时 title 优先",
+          "长代码给 maxHeight，超出在框内滚动；滚动条已是统一细条，暗色下不会露原生亮条",
+          "单行代码自动省掉行号列；想彻底不要行号传 lineNumbers: false",
+          "不需要复制按钮（例如代码本身是操作步骤）传 copyable: false；连标题都没有时头部整条省掉"
+        ]
      }
    ]
  }
@@ -4995,7 +4995,8 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
 .ua-timepicker-col,
 .ua-layout-content,
 .ua-json,
-.ua-diff {
+.ua-diff,
+.ua-code-body {
  scrollbar-width: thin; /* 标准属性：Firefox / Chromium 121+ 生效，细条不挤内容 */
  scrollbar-color: var(--ua-color-scrollbar) transparent; /* 拇指走令牌、轨道透明，避免画出方块底 */
 }
@@ -5629,3 +5630,58 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
 .ua-diff-row.is-del .ua-diff-sign {
  color: var(--ua-color-danger);
 }
+
+/* ---- 代码块：等宽 + 行号靠右，头部只放标题与复制，不叠边框（容器已有一道） ---- */
+.ua-code {
+  overflow: hidden;
+  border: 1px solid var(--ua-border-subtle);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface-inset);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; /* 等宽：代码缩进与对齐是语义的一部分 */
+  font-size: var(--ua-font-size-sm);
+  line-height: var(--ua-leading-normal);
+}
+
+.ua-code-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ua-space-2);
+  padding: var(--ua-space-1) var(--ua-space-2) var(--ua-space-1) var(--ua-space-3);
+  border-bottom: 1px solid var(--ua-border-subtle);
+  background: var(--ua-color-surface);
+}
+
+.ua-code-title {
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-xs);
+}
+
+.ua-code-body {
+  overflow: auto;
+  padding: var(--ua-space-2) 0;
+}
+
+.ua-code-line {
+  display: flex;
+  gap: var(--ua-space-3);
+  padding: 0 var(--ua-space-3);
+  white-space: pre; /* 长行横向滚动而不是折行：折行会让行号对不上内容 */
+}
+
+.ua-code-no {
+  flex: 0 0 auto;
+  min-width: var(--ua-space-4);
+  color: var(--ua-color-text-faint);
+  text-align: right;
+  user-select: none; /* 行号不进复制内容：复制按钮走原文，手动选择也不该带走行号 */
+}
+
+.ua-code-text {
+  flex: 1 1 auto;
+}
+
+/* 悬停整行提亮一档：读长代码时能追住当前行 */
+.ua-code-line:hover {
+  background: var(--ua-color-tint-accent-weak);
+}