iter(g271): 新增手写签名板组件

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T14:54:40.928Z",
+  "generatedAt": "2026-10-26T14:56:09.624Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -223,7 +223,8 @@
           "layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）",
           "jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑",
           "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
-          "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮"
+          "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮",
+          "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）"
         ],
         "keyTypes": [
           "ButtonProps",
@@ -4296,6 +4297,56 @@
               "单行代码自动省掉行号列；想彻底不要行号传 lineNumbers: false",
               "不需要复制按钮（例如代码本身是操作步骤）传 copyable: false；连标题都没有时头部整条省掉"
             ]
+          },
+          {
+            "id": "signaturePad",
+            "title": "手写签名 SignaturePad",
+            "demo": "sec-sign",
+            "props": [
+              {
+                "n": "value",
+                "t": "Signal<string>",
+                "d": "签字结果 dataURL 信号，双向绑定；清空写空串"
+              },
+              {
+                "n": "height",
+                "t": "number",
+                "d": "画布高度（px）；缺省 160"
+              },
+              {
+                "n": "penWidth",
+                "t": "number",
+                "d": "笔宽（px）；缺省 2"
+              },
+              {
+                "n": "hint",
+                "t": "string",
+                "d": "底部提示文案；缺省「在上方区域手写签名」"
+              },
+              {
+                "n": "disabled",
+                "t": "boolean | Signal<boolean>",
+                "d": "禁用态：布尔或信号，禁用时不响应手写"
+              },
+              {
+                "n": "ariaLabel",
+                "t": "string",
+                "d": "画布可访问名；缺省「手写签名区」"
+              },
+              {
+                "n": "onChange",
+                "t": "(dataUrl: string) => void",
+                "d": "收笔 / 清空时回调（清空回调空串）"
+              }
+            ],
+            "example": "const pad = signaturePad({ value: sign, height: 140 }); mount('#box', () => pad.el); pad.toDataURL(); pad.clear();",
+            "steps": [
+              "把画布挂上去即可手写：宽度跟随容器、高度由 height 给（缺省 160），不用自己算 DP R",
+              "签字结果在收笔瞬间写回 value 信号（PNG dataURL）；要提交表单就把它塞进字段值，清空会写回空串",
+              "底部「清空」按钮在未落笔或禁用时自动不可点，避免空操作；也能用返回的 handle.clear() 外部触发",
+              "需要判空用 handle.isEmpty()，取图用 handle.toDataURL()；两者与信号同源，不会出现「有图但信号是空」",
+              "禁用传布尔或信号：布尔直接置位，信号随状态变灰并挡住手写；移动端画布已关掉浏览器手势，不会边签边滚页"
+            ]
           }
         ]
       },

AGENTS.md

@@ -21,7 +21,7 @@
 
 - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核
 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架
-- `packages/skin/ui`（@ui-arch/ui）：80 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
+- `packages/skin/ui`（@ui-arch/ui）：81 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌
 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private）
 - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html

ARCHITECTURE.md

@@ -34,7 +34,7 @@ ui-arch-mvp/
 │   │   ├── table-core/       # 表格状态内核
 │   │   └── frame/            # 信号 + hyperscript 微框架
 │   ├── skin/                 # 皮肤层（DOM 组件，可发布）
-│   │   └── ui/               # 80 个组件 + ui.css
+│   │   └── ui/               # 81 个组件 + ui.css
 │   ├── design/               # 资产层（可发布）
 │   │   └── tokens/           # --ua-* 设计令牌
 │   └── tools/                # 工程层（private，不发布）

README.md

@@ -12,13 +12,13 @@ npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全
 npm run changelog       # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移）
 ```
 
-## 组件（共 80 个）
+## 组件（共 81 个）
 
 <!-- ua:components -->
-accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · codeBlock · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
+accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · codeBlock · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · signaturePad · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
 <!-- /ua:components -->
 
-分组：表单（button / copyButton / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / jsonViewer / diffView / codeBlock / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。
+分组：表单（button / copyButton / signaturePad / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / jsonViewer / diffView / codeBlock / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。
 
 ## 可访问性约定
 
@@ -34,7 +34,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup
 |---|---|
 | `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） |
 | `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） |
-| `packages/skin/ui` | @ui-arch/ui：80 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
+| `packages/skin/ui` | @ui-arch/ui：81 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
 | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
 | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
 | `apps/demo` | 交互演示（esbuild 打包成单文件） |

apps/demo/main.ts

@@ -72,6 +72,7 @@ import {
   segmented,
   select,
   showToast,
+  signaturePad,
   skeleton,
   splitter,
   slider,
@@ -1784,6 +1785,16 @@ const content = h(
       ].join('\n'),
     }),
   ),
+  section(
+    'sec-sign',
+    '手写签名',
+    'signaturePad：指针手写、位图按 DPR 放大不糊，收笔即把 PNG dataURL 写回信号；底部清空在未落笔时自动禁用。',
+    (() => {
+      const sign = signal('');
+      const pad = signaturePad({ value: sign, height: 140 });
+      return h('div', null, pad.el, h('div', { class: 'out' }, () => (sign() ? '已签字（dataURL 长度 ' + sign().length + '）' : '尚未签字')));
+    })(),
+  ),
 );
 
 // 悬浮按钮：fixed 定位，挂 body 不参与页面布局

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T14:54:40.928Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T14:56:09.624Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2287,6 +2287,34 @@ codeBlock({ code: source, title: 'main.ts', lang: 'ts', maxHeight: 320 })
 
 现场演示：apps/docs/demo.html#sec-code
 
+### signaturePad — 手写签名 SignaturePad
+
+参数：
+
+- value：Signal<string> —— 签字结果 dataURL 信号，双向绑定；清空写空串
+- height：number —— 画布高度（px）；缺省 160
+- penWidth：number —— 笔宽（px）；缺省 2
+- hint：string —— 底部提示文案；缺省「在上方区域手写签名」
+- disabled：boolean | Signal<boolean> —— 禁用态：布尔或信号，禁用时不响应手写
+- ariaLabel：string —— 画布可访问名；缺省「手写签名区」
+- onChange：(dataUrl: string) => void —— 收笔 / 清空时回调（清空回调空串）
+
+示例：
+
+```
+const pad = signaturePad({ value: sign, height: 140 }); mount('#box', () => pad.el); pad.toDataURL(); pad.clear();
+```
+
+手把手：
+
+1. 把画布挂上去即可手写：宽度跟随容器、高度由 height 给（缺省 160），不用自己算 DP R
+2. 签字结果在收笔瞬间写回 value 信号（PNG dataURL）；要提交表单就把它塞进字段值，清空会写回空串
+3. 底部「清空」按钮在未落笔或禁用时自动不可点，避免空操作；也能用返回的 handle.clear() 外部触发
+4. 需要判空用 handle.isEmpty()，取图用 handle.toDataURL()；两者与信号同源，不会出现「有图但信号是空」
+5. 禁用传布尔或信号：布尔直接置位，信号随状态变灰并挡住手写；移动端画布已关掉浏览器手势，不会边签边滚页
+
+现场演示：apps/docs/demo.html#sec-sign
+
 API 速览：
 
 - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调
@@ -2371,6 +2399,7 @@ API 速览：
 - jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑
 - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计
 - codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮
+- signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）
 
 一行用法：
 

llms.txt

@@ -129,6 +129,7 @@
   - jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑
   - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计
   - codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮
+  - signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）
 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
 - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调

packages/skin/ui/src/index.ts

@@ -80,3 +80,4 @@ export { layout } from './layout.js';
 export { jsonViewer } from './jsonViewer.js';
 export { diffView } from './diffView.js';
 export { codeBlock } from './codeBlock.js';
+export { signaturePad } from './signaturePad.js';

packages/skin/ui/src/signaturePad.ts

@@ -0,0 +1,111 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import { trackSize } from './watch.js';
+import type { SignaturePadHandle, SignaturePadProps } from './types.js';
+
+// 缺省画布高度与笔宽：160px 够签一个名字，2px 在 1x 屏上也不显细
+const PAD_H = 160;
+const PEN_W = 2;
+
+/*** 签名板：指针手写，canvas 位图按 DPR 放大保证线条不糊，笔色读 canvas 的 color 走令牌；签字结果写回 value 信号 ***/
+export function signaturePad(props: SignaturePadProps): SignaturePadHandle {
+  // —— 状态集中声明 ——
+  const height = props.height ?? PAD_H; // 画布 CSS 高度
+  const penW = props.penWidth ?? PEN_W; // 笔宽（CSS 像素）
+  const signed = signal(false); // 是否已落笔：决定清空按钮可用性与「未签」提示
+  const canvas = h('canvas', { class: 'ua-sign-canvas', role: 'img', 'aria-label': props.ariaLabel ?? '手写签名区' }) as HTMLCanvasElement;
+  const ctx = canvas.getContext('2d');
+  let drawing = false;                // 指针是否按住
+  let lastX = 0;                      // 上一落点 x（CSS 像素坐标系）
+  let lastY = 0;                      // 上一落点 y
+  let snap = '';                      // 尺寸变化前的内容快照：重设位图会清空画布，先存后用
+
+  /*** 取得当前笔色：读 canvas 计算样式的 color，颜色令牌换了笔色自动跟随 ***/
+  const penColor = (): string => getComputedStyle(canvas).color || '#000';
+
+  /*** 位图尺寸同步：按 CSS 宽 × DPR 设置位图，再把坐标系缩回 CSS 像素，避免高分屏线条发虚 ***/
+  const resize = (): void => {
+    const cssW = canvas.clientWidth || canvas.parentElement?.clientWidth || 320; // 宽度跟随容器，取不到就退 320
+    const ratio = window.devicePixelRatio || 1;
+    const nextW = Math.round(cssW * ratio);
+    const nextH = Math.round(height * ratio);
+    if (canvas.width === nextW && canvas.height === nextH) return; // 尺寸没变：不动位图（也不清内容）
+    snap = signed() ? canvas.toDataURL() : ''; // 有内容才快照，空白不浪费一次编码
+    canvas.width = nextW;
+    canvas.height = nextH;
+    if (!ctx) return;
+    ctx.setTransform(ratio, 0, 0, ratio, 0, 0); // 之后的坐标都按 CSS 像素算
+    ctx.lineCap = 'round'; // 圆头：手写笔迹不该是方角
+    ctx.lineJoin = 'round';
+    if (!snap) return;
+    const img = new Image();
+    img.onload = () => ctx.drawImage(img, 0, 0, cssW, height); // 快照按 CSS 尺寸贴回，缩放后笔迹仍在
+    img.src = snap;
+  };
+
+  /*** 落笔点换算：指针坐标减画布位置，得到 CSS 像素坐标 ***/
+  const pointOf = (e: PointerEvent): [number, number] => {
+    const box = canvas.getBoundingClientRect();
+    return [e.clientX - box.left, e.clientY - box.top];
+  };
+
+  /*** 画到新点：从上一落点连线，单点（点一下）也要画出一个圆点 ***/
+  const stroke = (x: number, y: number): void => {
+    if (!ctx) return;
+    ctx.strokeStyle = penColor();
+    ctx.lineWidth = penW;
+    ctx.beginPath();
+    ctx.moveTo(lastX, lastY);
+    ctx.lineTo(x, y);
+    ctx.stroke();
+    lastX = x;
+    lastY = y;
+  };
+
+  /*** 收笔：写回 dataURL，空画布不算签字 ***/
+  const commit = (): void => {
+    const url = canvas.toDataURL('image/png');
+    if (props.value) props.value(url);
+    if (props.onChange) props.onChange(url);
+  };
+
+  /*** 清空：复位位图 + 状态 + 信号，一次到位（三处不同源会立刻不同步） ***/
+  const clear = (): void => {
+    if (ctx) ctx.clearRect(0, 0, canvas.width, canvas.height);
+    signed(false);
+    snap = '';
+    if (props.value) props.value('');
+    if (props.onChange) props.onChange('');
+  };
+
+  canvas.addEventListener('pointerdown', (e: PointerEvent) => {
+    if (props.disabled === true) return; // 卫语句：布尔禁用直接挡住
+    drawing = true;
+    canvas.setPointerCapture(e.pointerId); // 指针捕获：手滑出画布也继续跟笔
+    [lastX, lastY] = pointOf(e);
+    stroke(lastX, lastY); // 先落一个点，单击也能留下痕迹
+    signed(true);
+  });
+  canvas.addEventListener('pointermove', (e: PointerEvent) => {
+    if (!drawing) return; // 卫语句：没按住不画
+    const [x, y] = pointOf(e);
+    stroke(x, y);
+  });
+  const finish = (): void => {
+    if (!drawing) return; // 卫语句：未落笔不重复提交
+    drawing = false;
+    commit();
+  };
+  canvas.addEventListener('pointerup', finish);
+  canvas.addEventListener('pointercancel', finish);
+  canvas.style.height = `${height}px`; // 高度只在这一次写：resize 里读它，不重复推导
+
+  const clearBtn = h('button', { type: 'button', class: 'ua-sign-clear', onClick: clear }, '清空') as HTMLButtonElement;
+  effect(() => { clearBtn.disabled = !signed() || props.disabled === true || (typeof props.disabled === 'function' && Boolean(props.disabled())); }); // 空白或信号禁用时不给出无效操作
+  const el = h('div', { class: 'ua-sign' }, canvas, h('div', { class: 'ua-sign-bar' }, h('span', { class: 'ua-sign-hint' }, props.hint ?? '在上方区域手写签名'), clearBtn));
+  if (typeof props.disabled === 'function') effect(() => { el.classList.toggle('is-disabled', Boolean(props.disabled && typeof props.disabled === 'function' && props.disabled())); }); // 信号禁用：跟着变灰
+  if (props.disabled === true) el.classList.add('is-disabled');
+  trackSize(el, resize); // 容器宽度变化后重算位图，笔迹按快照贴回
+  requestAnimationFrame(resize); // 首帧：布局完成后再定位图尺寸，避免 clientWidth 为 0
+
+  return { el, clear, toDataURL: () => canvas.toDataURL('image/png'), isEmpty: () => !signed() };
+}

packages/skin/ui/src/types.ts

@@ -1050,3 +1050,22 @@ export interface CodeBlockProps {
   onCopy?: (text: string) => void; // 复制成功回调（参数为实际写入剪贴板的内容）
   ariaLabel?: string;              // 可访问名；缺省「代码块」
 }
+
+/*** 签名板入参 ***/
+export interface SignaturePadProps {
+  value?: Signal<string>;                // 签字结果 dataURL 信号，双向绑定；清空写空串
+  height?: number;                       // 画布高度（px）；缺省 160
+  penWidth?: number;                     // 笔宽（px）；缺省 2
+  hint?: string;                         // 底部提示文案；缺省「在上方区域手写签名」
+  disabled?: boolean | Signal<boolean>;  // 禁用态：布尔或信号，禁用时不响应手写
+  ariaLabel?: string;                    // 画布可访问名；缺省「手写签名区」
+  onChange?: (dataUrl: string) => void;  // 收笔 / 清空时回调（清空回调空串）
+}
+
+/*** 签名板句柄 ***/
+export interface SignaturePadHandle {
+  el: HTMLElement;                       // 组件根（画布 + 底部条）
+  clear(): void;                         // 清空画布并复位信号
+  toDataURL(): string;                   // 取当前签字 PNG dataURL（未签也返回空白图）
+  isEmpty(): boolean;                    // 是否尚未落笔
+}

packages/skin/ui/ua.manifest.json

@@ -94,7 +94,8 @@
       "layout(props, ...children)：布局骨架，页头 / 侧栏 / 内容 / 页脚四区一次成型，侧栏可折叠（collapsed 信号双向绑定）",
       "jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑",
       "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
-      "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮"
+      "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮",
+      "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -4167,6 +4168,56 @@
           "单行代码自动省掉行号列；想彻底不要行号传 lineNumbers: false",
           "不需要复制按钮（例如代码本身是操作步骤）传 copyable: false；连标题都没有时头部整条省掉"
         ]
+      },
+      {
+        "id": "signaturePad",
+        "title": "手写签名 SignaturePad",
+        "demo": "sec-sign",
+        "props": [
+          {
+            "n": "value",
+            "t": "Signal<string>",
+            "d": "签字结果 dataURL 信号，双向绑定；清空写空串"
+          },
+          {
+            "n": "height",
+            "t": "number",
+            "d": "画布高度（px）；缺省 160"
+          },
+          {
+            "n": "penWidth",
+            "t": "number",
+            "d": "笔宽（px）；缺省 2"
+          },
+          {
+            "n": "hint",
+            "t": "string",
+            "d": "底部提示文案；缺省「在上方区域手写签名」"
+          },
+          {
+            "n": "disabled",
+            "t": "boolean | Signal<boolean>",
+            "d": "禁用态：布尔或信号，禁用时不响应手写"
+          },
+          {
+            "n": "ariaLabel",
+            "t": "string",
+            "d": "画布可访问名；缺省「手写签名区」"
+          },
+          {
+            "n": "onChange",
+            "t": "(dataUrl: string) => void",
+            "d": "收笔 / 清空时回调（清空回调空串）"
+          }
+        ],
+        "example": "const pad = signaturePad({ value: sign, height: 140 }); mount('#box', () => pad.el); pad.toDataURL(); pad.clear();",
+        "steps": [
+          "把画布挂上去即可手写：宽度跟随容器、高度由 height 给（缺省 160），不用自己算 DP R",
+          "签字结果在收笔瞬间写回 value 信号（PNG dataURL）；要提交表单就把它塞进字段值，清空会写回空串",
+          "底部「清空」按钮在未落笔或禁用时自动不可点，避免空操作；也能用返回的 handle.clear() 外部触发",
+          "需要判空用 handle.isEmpty()，取图用 handle.toDataURL()；两者与信号同源，不会出现「有图但信号是空」",
+          "禁用传布尔或信号：布尔直接置位，信号随状态变灰并挡住手写；移动端画布已关掉浏览器手势，不会边签边滚页"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -5685,3 +5685,58 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
 .ua-code-line:hover {
   background: var(--ua-color-tint-accent-weak);
 }
+
+/* ---- 签名板：画布边框只一道，手写区留白不压内距（笔迹要贴边才好签） ---- */
+.ua-sign {
+  overflow: hidden;
+  border: 1px solid var(--ua-border-subtle);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface);
+  color: var(--ua-color-text);
+}
+
+.ua-sign.is-disabled {
+  opacity: 0.6; /* 禁用态整块降权：单个控件灰掉就够，不给画布加遮罩 */
+}
+
+.ua-sign-canvas {
+  display: block;
+  width: 100%;
+  border-bottom: 1px solid var(--ua-border-subtle);
+  cursor: crosshair;
+  touch-action: none; /* 关掉浏览器手势：手写要独占指针，否则移动端会滚页面 */
+}
+
+.ua-sign-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ua-space-2);
+  padding: var(--ua-space-2) var(--ua-space-3);
+}
+
+.ua-sign-hint {
+  color: var(--ua-color-text-faint);
+  font-size: var(--ua-font-size-xs);
+}
+
+.ua-sign-clear {
+  padding: var(--ua-space-1) var(--ua-space-2);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  background: transparent;
+  color: var(--ua-color-text-secondary);
+  font-size: var(--ua-font-size-xs);
+  cursor: pointer;
+  transition: color var(--ua-duration-fast) var(--ua-ease), border-color var(--ua-duration-fast) var(--ua-ease);
+}
+
+.ua-sign-clear:hover:not(:disabled) {
+  border-color: var(--ua-color-accent);
+  color: var(--ua-color-accent);
+}
+
+.ua-sign-clear:disabled {
+  color: var(--ua-color-text-faint);
+  cursor: not-allowed;
+}