Appearance
xtf-signature
组件说明
xtf-signature 是手写签名，用于在画布上采集、清除和导出签名。当前实现通过 start 等事件反馈交互、提供实例方法。
- 实际 Demo 路由：
#/pages/components/xtf-signature/index - Demo 源码
基础用法
1. 最小可用
提供能够直接看到或操作组件的最少业务内容。
vue
<template>
<view class="doc-minimum">
<XtfSignature placeholder="请输入内容" />
</view>
</template>
<script setup lang="uts">
import XtfSignature from "@/uni_modules/xtf-linkuiunix/components/xtf-signature/xtf-signature.uvue"
</script>
<style>
.doc-minimum { display: flex; flex-direction: column; padding: 24rpx; }
</style>2. 核心数据与主要事件
使用组件真实数据入口，并记录当前源码声明的主要事件。
vue
<template>
<view class="doc-core">
<XtfSignature placeholder="请输入内容" @start="onPrimaryEvent" />
</view>
</template>
<script setup lang="uts">
import XtfSignature from "@/uni_modules/xtf-linkuiunix/components/xtf-signature/xtf-signature.uvue"
function onPrimaryEvent(payload: any): void { console.log("xtf-signature:start", payload) }
</script>
<style>
.doc-core { display: flex; flex-direction: column; padding: 24rpx; }
</style>3. 动态 disabled 状态
运行时切换 disabled，观察组件对应状态变化。
vue
<template>
<view class="doc-dynamic">
<XtfSignature placeholder="请输入内容" :disabled="state" />
<button class="doc-action-button" @click="toggleState">切换 disabled</button>
<text class="doc-state-text">disabled: {{ state }}</text>
</view>
</template>
<script setup lang="uts">
import XtfSignature from "@/uni_modules/xtf-linkuiunix/components/xtf-signature/xtf-signature.uvue"
import { ref } from "vue"
const state = ref(false)
function toggleState(): void { state.value = !state.value; console.log("disabled", state.value) }
</script>
<style>
.doc-dynamic { display: flex; flex-direction: column; padding: 24rpx; }
.doc-action-button { margin-top: 16rpx; }
.doc-state-text { margin-top: 12rpx; color: #475569; font-size: 24rpx; }
</style>4. 调用 refresh()
重新计算或刷新；签名为 refresh(): void。
vue
<template>
<view class="doc-method">
<XtfSignature placeholder="请输入内容" ref="componentRef" />
<button class="doc-action-button" @click="callMethod">重新计算或刷新</button>
</view>
</template>
<script setup lang="uts">
import XtfSignature from "@/uni_modules/xtf-linkuiunix/components/xtf-signature/xtf-signature.uvue"
import { ref } from "vue"
const componentRef = ref<any>(null)
function callMethod(): void { componentRef.value?.refresh(); console.log("调用 refresh") }
</script>
<style>
.doc-method { display: flex; flex-direction: column; padding: 24rpx; }
.doc-action-button { margin-top: 16rpx; }
</style>5. 父布局变化后显式 refresh()
弹层展开、隐藏容器恢复或父布局变化完成后调用 refresh；Canvas/Signature 应先收到 ready。此方法返回 void，不代表设备绘图或导出已完成。
vue
<template>
<view class="doc-layout-refresh">
<view :style="{ width: layoutWidth }"><XtfSignature placeholder="请输入内容" ref="componentRef" /></view>
<button class="doc-action-button" @click="refreshLayout">切换父宽度并刷新尺寸</button>
</view>
</template>
<script setup lang="uts">
import XtfSignature from "@/uni_modules/xtf-linkuiunix/components/xtf-signature/xtf-signature.uvue"
import { nextTick, ref } from "vue"
const componentRef = ref<any>(null)
const layoutWidth = ref("100%")
async function refreshLayout(): Promise<void> { layoutWidth.value = layoutWidth.value == "100%" ? "80%" : "100%"; await nextTick(); componentRef.value?.refresh(); console.log("refresh 已请求") }
</script>
<style>
.doc-layout-refresh { display: flex; flex-direction: column; padding: 24rpx; }
.doc-action-button { margin-top: 16rpx; }
</style>全部属性
| 属性 | 源码类型 | withDefaults 默认值 | 实际行为 / 范围 | 适用范围 |
|---|---|---|---|---|
width | string | number | '100%' | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 46、script 行 332 | 需要覆盖组件默认业务值时设置。 |
height | string | number | 360 | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 46、script 行 332 | 需要覆盖组件默认业务值时设置。 |
lineWidth | string | number | 6 | 设置对应区域宽度；消费位置：script 行 59、script 行 173 | 需要调整布局或视觉表现时设置。 |
initialStrokes | any[] | () => [] | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 329、script 行 334 | 需要覆盖组件默认业务值时设置。 |
minDistance | string | number | 2 | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 182 | 需要覆盖组件默认业务值时设置。 |
historyLimit | string | number | 0 | 兼容接收，当前实现未消费/不产生行为 | 仅用于兼容现有调用；当前版本不应依赖其效果。 |
strokeStyle | string | '' | 覆盖或追加对应内部区域的样式对象；消费位置：script 行 58、script 行 173 | 需要调整布局或视觉表现时设置。 |
strokeColor | string | '' | 设置对应区域的颜色；消费位置：script 行 58、script 行 173 | 需要调整布局或视觉表现时设置。 |
backgroundColor | string | '' | 设置对应区域的颜色；消费位置：script 行 46、script 行 146、script 行 307、script 行 333 | 需要调整布局或视觉表现时设置。 |
placeholder | string | '' | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：template 行 8 | 需要提供业务文案或图标内容时设置。 |
radius | string | number | 28 | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 46 | 需要覆盖组件默认业务值时设置。 |
disabled | boolean | false | 参与组件运行逻辑；源码在 3 处读取该值；消费位置：script 行 45、script 行 331、template 行 2 | 需要控制显示、可用性或交互状态时设置。 |
readonly | boolean | false | 参与组件运行逻辑；源码在 4 处读取该值；消费位置：script 行 44、script 行 45、script 行 331、template 行 2 | 需要控制显示、可用性或交互状态时设置。 |
previewImage | string | '' | 参与组件运行逻辑；源码在 3 处读取该值；消费位置：script 行 44、script 行 327、template 行 3 | 需要覆盖组件默认业务值时设置。 |
previewMode | string | 'aspectFit' | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：template 行 3 | 需要覆盖组件默认业务值时设置。 |
forceBackground | boolean | true | 参与组件运行逻辑；源码在 3 处读取该值；消费位置：script 行 146、script 行 293、script 行 333 | 需要覆盖组件默认业务值时设置。 |
trimWhitespace | boolean | false | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 290 | 需要覆盖组件默认业务值时设置。 |
exportPadding | string | number | 24 | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 291 | 需要覆盖组件默认业务值时设置。 |
exportScale | string | number | 1 | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 292 | 需要覆盖组件默认业务值时设置。 |
status | string | 'draft' | 参与组件运行逻辑；源码在 3 处读取该值；消费位置：script 行 26、script 行 329、script 行 330 | 需要覆盖组件默认业务值时设置。 |
signLimit | string | number | 0 | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 153、script 行 171 | 需要覆盖组件默认业务值时设置。 |
signerInfo | any | () => ({}) | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 156、script 行 319 | 需要覆盖组件默认业务值时设置。 |
auditInfo | any | () => ({}) | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 156、script 行 320 | 需要覆盖组件默认业务值时设置。 |
signArea | any | () => ({}) | 参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 156、script 行 320 | 需要覆盖组件默认业务值时设置。 |
customClass | string | '' | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：template 行 2 | 需要调整布局或视觉表现时设置。 |
customStyle | any | '' | 参与组件运行逻辑；源码在 1 处读取该值；消费位置：template 行 2 | 需要调整布局或视觉表现时设置。 |
事件
| 事件名称 | 源码触发边界 | 回调参数 | 参数说明 |
|---|---|---|---|
start | beginStroke 内触发（script 行 176）；参数表达式：point；前置 guard：point == null || !ready.value || activeStroke.value != null、locked.value、limit > 0 && strokes.value.length >= limit | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
change | appendPoint 内触发（script 行 185）；参数表达式：getStrokeMeta()；前置 guard：point == null || activeStroke.value == null || locked.value、Math.hypot(point.x - last.x, point.y - last.y) < Math.max(0, number(props.minDistance, 2)) | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
end | finishStroke 内触发（script 行 194）；参数表达式：getStrokeMeta()；前置 guard：activeStroke.value == null | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
clear | clear 内触发（script 行 217）；参数表达式：无回调参数 | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
undo | undo 内触发（script 行 228）；参数表达式：getStrokeMeta()；前置 guard：stroke == null | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
redo | redo 内触发（script 行 239）；参数表达式：getStrokeMeta()；前置 guard：stroke == null | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
save | getImageData 内触发（script 行 322）；参数表达式：result | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
export | getImageData 内触发（script 行 323）；参数表达式：result | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
error | setup 内触发（script 行 75）；参数表达式：{ message: '无法创建画布上下文' }；前置 guard：disposed || id !== requestId、context == nullsetup 内触发（script 行 90）；参数表达式：error | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
ready | setup 内触发（script 行 88）；参数表达式：无回调参数；前置 guard：disposed || id !== requestId、context == null | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
update:strokes | finishStroke 内触发（script 行 193）；参数表达式：cloneStrokes(strokes.value)；前置 guard：activeStroke.value == nullsetStrokes 内触发（script 行 215）；参数表达式：cloneStrokes(strokes.value)undo 内触发（script 行 227）；参数表达式：cloneStrokes(strokes.value)；前置 guard：stroke == nullredo 内触发（script 行 238）；参数表达式：cloneStrokes(strokes.value)；前置 guard：stroke == null | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
status-change | syncStatus 内触发（script 行 54）；参数表达式：{ status, reason }；前置 guard：status === internalStatus.value | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
blocked | beginStroke 内触发（script 行 170）；参数表达式：{ status: internalStatus.value }；前置 guard：point == null || !ready.value || activeStroke.value != null、locked.value | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
limit-exceed | beginStroke 内触发（script 行 172）；参数表达式：getStrokeMeta()；前置 guard：point == null || !ready.value || activeStroke.value != null、locked.value、limit > 0 && strokes.value.length >= limit | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
replay-start | replay 内触发（script 行 251）；参数表达式：无回调参数；前置 guard：!ready.value || strokes.value.length === 0 | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
replay-end | step 内触发（script 行 262）；参数表达式：无回调参数；前置 guard：!replaying.value || disposed、stroke == null | (...args: any[]) | 表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。 |
插槽
| 插槽 | Scope 参数 | 实际渲染位置 |
|---|---|---|
| - | - | 当前模板没有公开 slot。 |
方法
实例方法
| 方法 | 签名 / 返回值 | 调用边界 |
|---|---|---|
refresh | refresh(): void | 重新计算或刷新；通过组件 ref 调用，参数和返回值按签名处理。 |
clear | clear(): void | 清空内容；通过组件 ref 调用，参数和返回值按签名处理。 |
reset | reset(value: any[] | null = null): void | 恢复初始状态；通过组件 ref 调用，参数和返回值按签名处理。 |
undo | undo(): boolean | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
redo | redo(): boolean | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
setStrokes | setStrokes(value: any[]): void | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
replay | replay(speed: number = 16): Promise<boolean> | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
stopReplay | stopReplay(): void | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
getImageData | getImageData(options: any = {}): Promise<any> | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
exportImage | exportImage(options: any = {}): Promise<any> | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
isEmpty | isEmpty(): boolean | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
setStatus | setStatus(value: string): void | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
getStrokeMeta | getStrokeMeta(): any | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
getDrawingBounds | getDrawingBounds(): any | 调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。 |
公开状态
| 状态 | 类型 / 包装 | 读取边界 |
|---|---|---|
| - | - | 当前组件没有公开状态。 |
主题说明
- 当前组件 CSS 未读取
var(--xtf-*)主题变量；颜色或尺寸可能来自 props、固定样式或父级上下文。
平台与实现边界
- 基线为 HBuilderX 5.26+ 与 uni-app x；当前报告已验证 Web Chromium 的对应 Demo，不据此承诺 Safari、小程序或 App 原生端等价。
- Android、iOS、HarmonyOS、Vapor 原生路径、触摸手势、字体、Canvas、安全区和系统权限能力，只有源码或完整性报告明确覆盖的部分才可视为已验证。
- 本文按当前源码生成，不补入旧版
xtf-linkui存在但迁移版未实现的 props、事件、slot 或方法。 - 当前仅兼容接收、未发现运行消费的 props：
historyLimit。 - refresh(): void 在 ready 且尺寸/DPR 改变时停止回放、更新位图并重绘，不修改笔画与撤销历史，也不按新尺寸缩放笔画坐标。WEB || APP 条件编译 UniResizeObserver，小程序需在父布局变化后显式调用；未 ready、零尺寸或卸载后不处理，观察器在重建/卸载时断开。
- 详细公共边界见 平台与实现边界，逐项运行证据见项目根目录 COMPONENT_COMPLETENESS.md。