uview-plus

# Canvas 画布 3.8.76

up-canvas 是 uview-plus 的底层画布承载组件，用于统一 H5、小程序、App Vue 与 App nvue 的 Canvas 初始化、绘制、导出和像素读写能力。

使用建议

如果只是生成二维码、条形码、海报、签名、裁剪图片或上传视频封面，优先使用 up-qrcode、u-barcode、up-poster、up-signature、u-cropper、up-upload 等业务组件。只有需要自定义绘制逻辑时，才建议直接使用 up-canvas。

# 平台差异说明

App（vue） App（nvue） H5 小程序
√ √ √ √

App nvue 下由 up-canvas 内部承载 gcanvas，业务代码仍通过同一套 ref 方法调用。

# 基本使用

通过 ref 获取组件实例，再调用绘图方法。组件触发 ready 后表示画布已经完成初始化。

<template>
  <view>
    <up-canvas
      ref="canvasRef"
      canvas-id="demoCanvas"
      :width="300"
      :height="180"
      bg-color="#ffffff"
      @ready="draw"
    ></up-canvas>

    <up-button text="导出图片" @click="exportImage"></up-button>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const canvasRef = ref(null)

const draw = () => {
  const canvas = canvasRef.value
  canvas.setFillStyle('#f5f7fa')
  canvas.fillRect(0, 0, 300, 180)

  canvas.setFillStyle('#2979ff')
  canvas.fillRect(24, 24, 120, 64)

  canvas.setFillStyle('#303133')
  canvas.setFontSize(18)
  canvas.fillText('up-canvas', 24, 120)

  canvas.draw(false)
}

const exportImage = async () => {
  const tempFilePath = await canvasRef.value.exportImage('png', 1)
  console.log('导出图片:', tempFilePath)
}
</script>

# 绘制图片

drawImage 支持图片路径、临时文件路径、H5 图片对象、小程序 CanvasImage 等平台可识别的图片源。H5 和小程序 2D Canvas 下传入字符串路径时，组件会先加载图片再绘制。

const canvas = canvasRef.value
await canvas.drawImage('/static/logo.png', 20, 20, 80, 80)
canvas.draw(false)

# 导出图片

toTempFilePath 保留 uni-app 风格的回调参数，同时返回 Promise。

const res = await canvasRef.value.toTempFilePath({
  x: 0,
  y: 0,
  width: 300,
  height: 180,
  destWidth: 600,
  destHeight: 360,
  fileType: 'png',
  quality: 1
})

console.log(res.tempFilePath || res.apFilePath)

# API

# Props

参数 说明 类型 默认值 可选值
canvasId 画布 ID，同一页面内需保持唯一 String 随机生成 -
width 画布宽度 String / Number 300 -
height 画布高度 String / Number 300 -
unit 宽高单位 String px px / rpx / upx
useRootHeightAndWidth 是否使用根节点宽高作为画布尺寸 Boolean false true
bgColor 画布背景色，传 transparent 可保持透明 String #ffffff -
disableScroll 触摸画布时是否禁止页面滚动 Boolean false true

# Events

事件名 说明 回调参数
ready 画布初始化完成 { width, height }
touchstart 手指触摸开始 event
touchmove 手指触摸移动 event
touchend 手指触摸结束 event

# Methods

通过 ref 获取 up-canvas 实例后调用。

方法名 说明 返回值
initCanvas(force = false) 初始化画布，force 为 true 时强制重建上下文 Promise<Boolean>
refresh() 强制刷新画布上下文 Promise<Boolean>
getCanvasElement() 获取底层 canvas 节点或 nvue gcanvas 对象 Object / null
getRawContext() 获取底层原始 2D 上下文 Object / null
clearCanvas() 清空画布并按 bgColor 重绘背景 -
draw(isLastDraw = false, callback) 提交绘制，兼容旧版 CanvasContext -
toTempFilePath(options) 导出图片，参数兼容 uni.canvasToTempFilePath Promise<Object>
exportImage(fileType = 'png', quality = 1) 导出图片并直接返回临时路径 Promise<String>
getImageData(options) 读取像素数据，参数兼容 uni.canvasGetImageData Promise<Object>
putImageData(options) 写入像素数据，参数兼容 uni.canvasPutImageData Promise<Object>
drawImage(source, ...args) 绘制图片 Promise<Boolean>
measureText(text) 测量文本宽度 Object

# 绘图方法

up-canvas 封装了常用 Canvas 2D 绘图方法，优先使用平台原生能力，并对旧版 CanvasContext 做兼容。

分类 方法
路径 beginPath、closePath、moveTo、lineTo、arc、bezierCurveTo、quadraticCurveTo、rect、clip
矩形 clearRect、fillRect、strokeRect
样式 setFillStyle、setStrokeStyle、setLineWidth、setLineCap、setLineJoin、setGlobalAlpha、setShadow
文本 setFontSize、setFont、setTextAlign、setTextBaseline、fillText、measureText
变换 save、restore、translate、rotate、scale
渐变 createLinearGradient、createRadialGradient

# 注意事项

  1. canvasId 在同一页面内必须唯一，否则导出和像素读写可能命中错误画布。
  2. 画布绘制应在 ready 事件后，或手动 await initCanvas() 后执行。
  3. App nvue 图片绘制依赖 gcanvas 能访问的图片路径，跨域或权限受限资源需先转为本地临时路径。
  4. H5 导出跨域图片时，请确保图片服务允许跨域访问，否则浏览器会限制 toDataURL。

← Qrcode 二维码 →