xtf-canvas

组件说明

xtf-canvas 是画布组件，封装了 uni-app 的 canvas 能力，提供绘图、手写签名、撤销/重做、导出图片等功能。支持画笔/橡皮擦切换、笔画历史管理、网格显示和命令式绘图，适用于手写签名、涂鸦画板和自定义图表等场景。

基础用法

1. 最简示例

设置画布尺寸，开启绘图模式即可手写：

vue

<template>
  <xtf-canvas
    ref="canvas"
    width="600"
    height="400"
    drawing
    background-color="#ffffff"
    @ready="onReady"
  />
</template>

<script>
export default {
  methods: {
    onReady(meta) {
      console.log('画布就绪', meta.canvasId)
    }
  }
}
</script>

2. 画笔与橡皮擦

通过 tool 切换画笔/橡皮擦，通过 strokeColor 和 strokeWidth 控制笔画样式：

vue

<template>
  <view>
    <xtf-button-group :gap="12" style="margin-bottom: 16rpx">
      <xtf-button
        label="画笔"
        size="sm"
        :type="tool === 'pen' ? 'solid' : 'light'"
        @click="tool = 'pen'"
      />
      <xtf-button
        label="橡皮擦"
        size="sm"
        :type="tool === 'eraser' ? 'solid' : 'light'"
        @click="tool = 'eraser'"
      />
    </xtf-button-group>
    <xtf-canvas
      ref="canvas"
      width="600"
      height="400"
      drawing
      :tool="tool"
      stroke-color="#333333"
      :stroke-width="4"
      background-color="#ffffff"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      tool: 'pen'
    }
  }
}
</script>

3. 撤销与重做

通过 undo / redo 方法操作历史记录：

vue

<template>
  <view>
    <xtf-button-group :gap="12" style="margin-bottom: 16rpx">
      <xtf-button label="撤销" size="sm" type="light" @click="undo" />
      <xtf-button label="重做" size="sm" type="light" @click="redo" />
      <xtf-button label="清空" size="sm" type="light" theme="danger" @click="clearCanvas" />
      <xtf-button label="导出" size="sm" type="solid" @click="exportImage" />
    </xtf-button-group>
    <xtf-canvas
      ref="canvas"
      width="600"
      height="400"
      drawing
      background-color="#ffffff"
      :history-limit="30"
    />
  </view>
</template>

<script>
export default {
  methods: {
    undo() {
      this.$refs.canvas.undo()
    },
    redo() {
      this.$refs.canvas.redo()
    },
    clearCanvas() {
      this.$refs.canvas.clear()
    },
    exportImage() {
      this.$refs.canvas.exportImage().then((res) => {
        console.log('导出图片路径:', res.tempFilePath)
      })
    }
  }
}
</script>

4. 网格与空状态

通过 showGrid 显示网格辅助线，通过 emptyText 设置空状态提示：

vue

<template>
  <xtf-canvas
    ref="canvas"
    width="600"
    height="400"
    drawing
    show-grid
    grid-size="40"
    grid-color="rgba(148, 163, 184, 0.18)"
    background-color="#ffffff"
    empty-text="在画布上绘制内容"
  />
</template>

全部属性

属性	类型	默认值	作用描述	适用范围
`canvasId`	`String`	`''`	画布 ID，不设则自动生成	自定义 ID
`width`	`String \| Number`	`600`	画布宽度（rpx）	控制宽度
`height`	`String \| Number`	`400`	画布高度（rpx）	控制高度
`backgroundColor`	`String`	`''`	背景色	背景色
`disableScroll`	`Boolean`	`true`	是否禁用画布区域滚动	防止滚动
`autoCreateContext`	`Boolean`	`true`	是否自动创建绘图上下文	自动初始化
`drawing`	`Boolean`	`false`	是否开启绘图模式	手写绘图
`tool`	`String`	`'pen'`	工具：`'pen'` / `'eraser'`	切换工具
`strokeColor`	`String`	`'#111827'`	画笔颜色	画笔颜色
`strokeWidth`	`String \| Number`	`6`	画笔宽度（rpx）	画笔粗细
`minDistance`	`String \| Number`	`2`	最小采样距离（rpx）	采样精度
`pressure`	`Boolean`	`false`	是否启用压感	压感支持
`historyLimit`	`String \| Number`	`50`	历史记录上限	历史限制
`strokes`	`Array`	`[]`	外部笔画数据	导入笔画
`commands`	`Array`	`[]`	命令式绘图指令	命令绘图
`showGrid`	`Boolean`	`false`	是否显示网格	网格辅助
`gridSize`	`String \| Number`	`40`	网格大小（rpx）	网格间距
`gridColor`	`String`	`'rgba(148, 163, 184, 0.18)'`	网格颜色	网格颜色
`emptyText`	`String`	`''`	空状态提示文字	空状态
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

事件

事件名称	触发时机	回调参数	参数说明
`ready`	画布上下文初始化完成	`(meta)`	`{ canvasId, context, width, height, strokeCount, canUndo, canRedo }`
`touchstart` / `touchmove` / `touchend` / `touchcancel`	原生触摸阶段触发	`(event)`	原生触摸事件；组件继续执行内部绘制逻辑
`mousedown` / `mousemove` / `mouseup` / `mouseleave`	H5 鼠标阶段触发	`(event)`	原生鼠标事件；用于桌面端交互监听
`draw-start`	开始绘制一笔时触发	`(payload)`	含起始 `point` 与画布元数据
`draw-move`	绘制过程追加采样点时触发	`(payload)`	含当前 `point` 与画布元数据
`draw-end`	一笔绘制完成时触发	`(payload)`	含完成的 `stroke` 与画布元数据
`change`	笔画或命令变更	`(payload)`	含 `reason`、`strokes` 或 `commands` 和画布元数据
`update:strokes`	内部笔画数据变更时触发	`(strokes: Array)`	可用于同步外部 `strokes` 数据
`update:commands`	内部命令数据变更时触发	`(commands: Array)`	可用于同步外部 `commands` 数据
`undo`	撤销时触发	`(strokes)`	撤销后的笔画
`redo`	重做时触发	`(strokes)`	重做后的笔画
`clear`	清空时触发	-	-
`export`	导出时触发	`(res)`	导出结果
`error`	出错时触发	`(error)`	错误对象

方法

方法名	参数	返回值	说明
`getContext`	-	`Object`	获取画布上下文
`getCanvasId`	-	`String`	获取画布 ID
`undo`	-	-	撤销上一笔
`redo`	-	-	重做上一笔
`clear`	-	-	清空画布
`exportImage`	`(options)`	`Promise`	导出临时图片；成功时触发 `export`
`getStrokes` / `setStrokes` / `clearStrokes`	数据 / -	数据 / -	读取、替换、清空笔画
`getCommands` / `setCommands` / `addCommand` / `removeCommand` / `clearCommands`	命令或 ID	数据 / ID / Boolean	管理命令绘图
`drawRect`、`drawCircle`、`drawEllipse`、`drawRoundRect`、`drawArc`、`drawLine`、`drawPoints`、`drawPolygon`、`drawPath`、`drawText`、`drawIcon`、`drawImage`	图形参数	`String`	添加对应命令并返回命令 ID
`redraw`	`(callback)`	-	重绘画布

主题说明

画布本身不使用主题变量，颜色由 backgroundColor、strokeColor、gridColor 等属性控制
画笔颜色和宽度可通过属性自定义
网格颜色默认为半透明灰色

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。

xtf-canvas ​

组件说明 ​

基础用法 ​

1. 最简示例 ​

2. 画笔与橡皮擦 ​

3. 撤销与重做 ​

4. 网格与空状态 ​

全部属性 ​

事件 ​

方法 ​

主题说明 ​