xtf-canvas

组件说明

xtf-canvas 是画布，用于管理 Canvas 绘制上下文与导出操作。当前实现通过 ready 等事件反馈交互、提供实例方法。

• 实际 Demo 路由：#/pages/components/xtf-canvas/index
• Demo 源码

---

基础用法

1. 最小可用

提供能够直接看到或操作组件的最少业务内容。

<template>
  <view class="doc-minimum">
    <XtfCanvas canvas-id="doc-canvas" />
  </view>
</template>

<script setup lang="uts">
import XtfCanvas from "@/uni_modules/xtf-linkuiunix/components/xtf-canvas/xtf-canvas.uvue"

</script>

<style>
.doc-minimum { display: flex; flex-direction: column; padding: 24rpx; }
</style>

2. 核心数据与主要事件

使用组件真实数据入口，并记录当前源码声明的主要事件。

<template>
  <view class="doc-core">
    <XtfCanvas canvas-id="doc-canvas" @ready="onPrimaryEvent" />
  </view>
</template>

<script setup lang="uts">
import XtfCanvas from "@/uni_modules/xtf-linkuiunix/components/xtf-canvas/xtf-canvas.uvue"

function onPrimaryEvent(payload: any): void { console.log("xtf-canvas:ready", payload) }
</script>

<style>
.doc-core { display: flex; flex-direction: column; padding: 24rpx; }
</style>

3. 动态 disableScroll 状态

运行时切换 disableScroll，观察组件对应状态变化。

<template>
  <view class="doc-dynamic">
    <XtfCanvas canvas-id="doc-canvas" :disable-scroll="state" />
    <button class="doc-action-button" @click="toggleState">切换 disableScroll</button>
    <text class="doc-state-text">disableScroll: {{ state }}</text>
  </view>
</template>

<script setup lang="uts">
import XtfCanvas from "@/uni_modules/xtf-linkuiunix/components/xtf-canvas/xtf-canvas.uvue"

import { ref } from "vue"

const state = ref(false)
function toggleState(): void { state.value = !state.value; console.log("disableScroll", 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。

<template>
  <view class="doc-method">
    <XtfCanvas canvas-id="doc-canvas" ref="componentRef" />
    <button class="doc-action-button" @click="callMethod">重新计算或刷新</button>
  </view>
</template>

<script setup lang="uts">
import XtfCanvas from "@/uni_modules/xtf-linkuiunix/components/xtf-canvas/xtf-canvas.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，不代表设备绘图或导出已完成。

<template>
  <view class="doc-layout-refresh">
    <view :style="{ width: layoutWidth }"><XtfCanvas canvas-id="doc-canvas" ref="componentRef" /></view>
    <button class="doc-action-button" @click="refreshLayout">切换父宽度并刷新尺寸</button>
  </view>
</template>

<script setup lang="uts">
import XtfCanvas from "@/uni_modules/xtf-linkuiunix/components/xtf-canvas/xtf-canvas.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 默认值	实际行为 / 范围	适用范围
canvasId	string	""	参与组件运行逻辑；源码在 3 处读取该值；消费位置：script 行 100、script 行 828	需要覆盖组件默认业务值时设置。
width	string | number	600	参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 111、script 行 826	需要覆盖组件默认业务值时设置。
height	string | number	400	参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 112、script 行 827	需要覆盖组件默认业务值时设置。
backgroundColor	string	""	设置对应区域的颜色；消费位置：script 行 113、script 行 429、script 行 430、script 行 642	需要调整布局或视觉表现时设置。
disableScroll	boolean	true	参与组件运行逻辑；源码在 1 处读取该值；消费位置：template 行 9	需要覆盖组件默认业务值时设置。
autoCreateContext	boolean	true	开关对应显示或交互行为；消费位置：script 行 164	需要提供业务文案或图标内容时设置。
drawing	boolean	false	参与组件运行逻辑；源码在 5 处读取该值；消费位置：script 行 106、script 行 713、script 行 720、script 行 730	需要覆盖组件默认业务值时设置。
tool	string	"pen"	参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 101	需要覆盖组件默认业务值时设置。
strokeColor	string	"#111827"	设置对应区域的颜色；消费位置：script 行 699	需要调整布局或视觉表现时设置。
strokeWidth	string | number	6	设置对应区域宽度；消费位置：script 行 102	需要调整布局或视觉表现时设置。
minDistance	string | number	2	参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 103	需要覆盖组件默认业务值时设置。
pressure	boolean	false	参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 695	需要覆盖组件默认业务值时设置。
historyLimit	string | number	50	参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 104	需要覆盖组件默认业务值时设置。
strokes	XtfCanvasStroke[]	() => [] as XtfCanvasStroke[]	参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 814、script 行 842	需要覆盖组件默认业务值时设置。
commands	XtfCanvasCommand[]	() => [] as XtfCanvasCommand[]	参与组件运行逻辑；源码在 2 处读取该值；消费位置：script 行 821、script 行 843	需要覆盖组件默认业务值时设置。
showGrid	boolean	false	开关对应显示或交互行为；消费位置：script 行 433、script 行 830	需要控制显示、可用性或交互状态时设置。
gridSize	string | number	40	设置对应元素尺寸；消费位置：script 行 434、script 行 831	需要调整布局或视觉表现时设置。
gridColor	string	"rgba(148, 163, 184, 0.22)"	设置对应区域的颜色；消费位置：script 行 435、script 行 832	需要调整布局或视觉表现时设置。
emptyText	string	""	设置对应区域的显示文案；消费位置：script 行 116、template 行 20	需要提供业务文案或图标内容时设置。
customClass	string	""	参与组件运行逻辑；源码在 1 处读取该值；消费位置：script 行 108	需要调整布局或视觉表现时设置。
customStyle	string | UTSJSONObject	""	参与组件运行逻辑；源码在 1 处读取该值；消费位置：template 行 2	需要调整布局或视觉表现时设置。

XtfCanvasStroke 数据结构

字段	源码类型	字段语义
id	string	数据标识
tool	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
color	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
width	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
points	XtfCanvasPoint[]	源码声明的业务扩展字段；当前实现未提供更具体语义。

XtfCanvasCommand 数据结构

字段	源码类型	字段语义
id	string	数据标识
type	string	类型标识
x	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
y	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
x2	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
y2	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
width	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
height	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
radius	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
radiusX	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
radiusY	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
startAngle	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
endAngle	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
counterClockwise	boolean	源码声明的业务扩展字段；当前实现未提供更具体语义。
color	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
fill	boolean	源码声明的业务扩展字段；当前实现未提供更具体语义。
fillColor	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
stroke	boolean	源码声明的业务扩展字段；当前实现未提供更具体语义。
strokeColor	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
lineWidth	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
lineCap	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
lineJoin	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
points	XtfCanvasPoint[]	源码声明的业务扩展字段；当前实现未提供更具体语义。
segments	XtfCanvasPathSegment[]	源码声明的业务扩展字段；当前实现未提供更具体语义。
text	string	显示文本
fontSize	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
font	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
textAlign	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
textBaseline	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
maxWidth	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
name	string	名称或兼容显示字段
icon	string	图标名称
size	number	资源大小
anchor	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
cutout	boolean	源码声明的业务扩展字段；当前实现未提供更具体语义。
cutoutColor	string	源码声明的业务扩展字段；当前实现未提供更具体语义。
alpha	number	源码声明的业务扩展字段；当前实现未提供更具体语义。
composite	string	源码声明的业务扩展字段；当前实现未提供更具体语义。

---

事件

事件名称	源码触发边界	回调参数	参数说明
ready	initContext 内触发（script 行 165）；参数表达式：{ "meta": getCanvasMeta(), "context": null, "renderingContext": null }；前置 guard：disposed、!props.autoCreateContext setup 内触发（script 行 190）；参数表达式：{ "meta": getCanvasMeta(), "context": canvasContext, "renderingContext": renderingContext }；前置 guard：disposed || requestId != contextRequestId、context2d == null	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
touchstart	仅声明，当前未找到触发路径。	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
touchmove	仅声明，当前未找到触发路径。	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
touchend	仅声明，当前未找到触发路径。	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
touchcancel	仅声明，当前未找到触发路径。	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
mousedown	仅声明，当前未找到触发路径。	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
mousemove	仅声明，当前未找到触发路径。	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
mouseup	仅声明，当前未找到触发路径。	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
mouseleave	仅声明，当前未找到触发路径。	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
draw-start	startDrawing 内触发（script 行 716）；参数表达式：{ "point": cloneCanvasPoint(point), "stroke": cloneCanvasStroke(activeStroke.value!), "canvas": getCanvasMeta() }；前置 guard：!props.drawing	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
draw-move	moveDrawing 内触发（script 行 726）；参数表达式：{ "point": cloneCanvasPoint(point), "stroke": cloneCanvasStroke(activeStroke.value!), "canvas": getCanvasMeta() }；前置 guard：!props.drawing || activeStroke.value == null、pointDistance(lastPoint, point) < resolvedMinDistance.value	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
draw-end	endDrawing 内触发（script 行 744）；参数表达式：{ "stroke": cloneCanvasStroke(completed), "canvas": getCanvasMeta() }；前置 guard：!props.drawing || activeStroke.value == null	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
change	emitStrokeChange 内触发（script 行 757）；参数表达式：{ "reason": reason, "strokes": strokes, "canvas": getCanvasMeta() } emitCommandChange 内触发（script 行 763）；参数表达式：{ "reason": reason, "commands": commands, "canvas": getCanvasMeta() }	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
update:strokes	emitStrokeChange 内触发（script 行 755）；参数表达式：strokes	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
update:commands	emitCommandChange 内触发（script 行 762）；参数表达式：commands	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
undo	undo 内触发（script 行 394）；参数表达式：getCanvasMeta()；前置 guard：internalStrokes.value.length == 0	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
redo	redo 内触发（script 行 404）；参数表达式：getCanvasMeta()；前置 guard：redoStack.value.length == 0	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
clear	clear 内触发（script 行 374）；参数表达式：getCanvasMeta()	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
export	exportImage 内触发（script 行 806）；参数表达式：result；前置 guard：canvasContext == null || !contextReady.value	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。
error	emitError 内触发（script 行 157）；参数表达式：{ "canvasId": resolvedCanvasId.value, "operation": operation, "message": message, "error": error }	(...args: any[])	表中参数表达式来自当前源码直接调用点；禁用、守卫失败或未进入该函数分支时不会触发。

---

插槽

插槽	Scope 参数	实际渲染位置
-	-	当前模板没有公开 slot。

---

方法

实例方法

方法	签名 / 返回值	调用边界
refresh	refresh(): void	重新计算或刷新；通过组件 ref 调用，参数和返回值按签名处理。
initContext	initContext(): void	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
recreateContext	recreateContext(): void	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
getCanvasMeta	getCanvasMeta(): XtfCanvasMeta	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
getCanvasId	getCanvasId(): string	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
getCanvasContext	getCanvasContext(): CanvasContext | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
getContext	getContext(): CanvasRenderingContext2D | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
getRenderingContext	getRenderingContext(): CanvasRenderingContext2D | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
getStrokes	getStrokes(): XtfCanvasStroke[]	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
getCommands	getCommands(): XtfCanvasCommand[]	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
setStrokes	setStrokes(strokes: XtfCanvasStroke[]): void	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
setCommands	setCommands(commands: XtfCanvasCommand[]): void	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
addCommand	addCommand(command: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
removeCommand	removeCommand(commandId: string): boolean	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
clearCommands	clearCommands(): void	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawRect	drawRect(options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawCircle	drawCircle(options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawEllipse	drawEllipse(options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawRoundRect	drawRoundRect(options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawArc	drawArc(options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawLine	drawLine(options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawPoints	drawPoints(points: XtfCanvasPoint[], options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawPolygon	drawPolygon(points: XtfCanvasPoint[], options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawPath	drawPath(segments: XtfCanvasPathSegment[], options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawText	drawText(text: string, options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
drawIcon	drawIcon(name: string, options: XtfCanvasCommand): string | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
draw	draw(callback: (context: CanvasRenderingContext2D) => void, _reserve: boolean = false): void	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
redraw	redraw(): void	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
clear	clear(done: (() => void) | null = null): void	清空内容；通过组件 ref 调用，参数和返回值按签名处理。
clearStrokes	clearStrokes(): void	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
undo	undo(): boolean	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
redo	redo(): boolean	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。
exportImage	exportImage(_options: any = null): XtfCanvasExportResult | null	调用该公开实例能力；通过组件 ref 调用，参数和返回值按签名处理。

公开状态

状态	类型 / 包装	读取边界
-	-	当前组件没有公开状态。

---

主题说明

• var(--xtf-color-primary)：组件样式实际读取的主题变量，可在 xtf-config-provider 作用域或主题 class 下覆盖。
• var(--xtf-color-text-secondary)：组件样式实际读取的主题变量，可在 xtf-config-provider 作用域或主题 class 下覆盖。

---

平台与实现边界

• 基线为 HBuilderX 5.26+ 与 uni-app x；当前报告已验证 Web Chromium 的对应 Demo，不据此承诺 Safari、小程序或 App 原生端等价。
• Android、iOS、HarmonyOS、Vapor 原生路径、触摸手势、字体、Canvas、安全区和系统权限能力，只有源码或完整性报告明确覆盖的部分才可视为已验证。
• 本文按当前源码生成，不补入旧版 xtf-linkui 存在但迁移版未实现的 props、事件、slot 或方法。
• 仅声明但当前未找到触发路径的事件：touchstart、touchmove、touchend、touchcancel、mousedown、mousemove、mouseup、mouseleave。
• refresh(): void 在上下文 ready 且尺寸大于零时检查逻辑尺寸与 DPR，变化后重新配置位图并 redraw；无变化或未 ready 时不处理，不是清空 API。WEB || APP 条件编译 UniResizeObserver，小程序需在布局完成后显式调用；重建上下文与卸载会解除旧观察。
• 详细公共边界见 平台与实现边界，逐项运行证据见项目根目录 COMPONENT_COMPLETENESS.md。