画布组件

canvas 组件是 Uniapp 中用于绘制图形、处理图像和进行自由渲染的基础组件，广泛用于图表、动画、图片处理等场景。canvas 组件支持 2D 和 WebGL 两种渲染模式，具有较高的灵活性和跨平台兼容性。

1. 什么是 canvas 组件？

canvas 组件用于在网页或应用中动态绘制内容，支持 2D 和 WebGL 渲染模式。开发者可以通过 JavaScript 来控制绘制图形、处理图像、制作图表或进行复杂的动画处理。canvas 组件常见于 H5 页面、小程序、App-Vue 等环境，允许用户直接绘制和更新内容。

使用场景

• 图表绘制：使用 canvas 绘制各种类型的图表，如柱状图、折线图、饼图等。
• 图片处理：处理图片的合成、裁剪、滤镜等操作。
• 动画渲染：实现帧动画、粒子特效等复杂的动画效果。
• 自由绘制：用户可通过触摸屏或鼠标进行自由绘图操作，如画板类应用。

2. canvas 组件的常用属性

canvas 组件提供了丰富的属性和事件，用于控制绘图行为和响应用户操作。以下是常用属性的详细说明及使用示例：

属性名	类型	默认值	说明	平台差异说明
type	String		指定 canvas 类型，支持 2d 和 webgl	微信小程序 2.7.0+，抖音小程序1.78.0+
canvas-id	String		canvas 组件的唯一标识符
disable-scroll	Boolean	false	当在 canvas 中移动时且有绑定手势事件时，禁止屏幕滚动及下拉刷新	抖音小程序与飞书小程序不支持
hidpi	Boolean	true	是否启用高清处理，优化绘图清晰度	H5 (HBuilder X 3.4.0+)、App-vue (HBuilder X 3.4.0+)
@touchstart	EventHandle		手指触摸动作开始	抖音小程序1.78.0+
@touchmove	EventHandle		手指触摸后移动	抖音小程序1.78.0+
@touchend	EventHandle		手指触摸动作结束	抖音小程序1.78.0+
@touchcancel	EventHandle		手指触摸动作被打断，如来电提醒，弹窗	抖音小程序1.78.0+
@longtap	EventHandle		手指长按 500ms 后触发，触发了长按事件后进行移动不会触发屏幕的滚动	抖音小程序与飞书小程序不支持
@error	EventHandle		当发生错误时触发 error 事件，detail = {errMsg: 'something wrong'}	抖音小程序与飞书小程序不支持

2.1 指定 canvas 类型

• 说明：通过 type 属性指定 canvas 的类型，支持 2d 和 webgl 渲染。
• 类型：String
• 默认值：无

<template>
  <!-- 2D canvas 类型 -->
  <canvas canvas-id="2dCanvas" type="2d" style="width: 300px; height: 200px;"></canvas>

  <!-- WebGL canvas 类型 -->
  <canvas canvas-id="webglCanvas" type="webgl" style="width: 300px; height: 200px;"></canvas>
</template>

2.2 禁止滚动 disable-scroll

• 说明：通过 disable-scroll 属性可以在 canvas 中绑定手势事件时禁止屏幕滚动或下拉刷新。
• 类型：Boolean
• 默认值：false

<template>
  <canvas canvas-id="noScrollCanvas" disable-scroll="true" style="width: 300px; height: 200px;"></canvas>
</template>

2.3 高清处理 hidpi

• 说明：是否启用高清处理，主要在 H5 和 App-Vue 中使用，用于优化 canvas 的清晰度。
• 类型：Boolean
• 默认值：true

<template>
  <canvas canvas-id="hdCanvas" hidpi="true" style="width: 300px; height: 200px;"></canvas>
</template>

3. 绘制图形与响应事件

以下案例展示了如何使用 canvas 绘制基本图形，并处理用户的触摸事件。

3.1 基本图形绘制

通过 JavaScript 代码绘制简单的矩形和圆形，演示 canvas 的基本绘图功能。

<template>
  <view>
    <!-- 2D Canvas 画布 -->
    <canvas canvas-id="basicCanvas" style="width: 300px; height: 200px;"></canvas>
  </view>
</template>

<script>
import { onMounted } from 'vue'

export default {
  setup() {
    onMounted(() => {
      // 创建 canvas 上下文
      const context = uni.createCanvasContext('basicCanvas')
      
      // 绘制矩形
      context.setFillStyle('#00ff00')
      context.fillRect(0, 0, 150, 100)
      
      // 绘制圆形
      context.setFillStyle('#ff0000')
      context.arc(75, 75, 50, 0, Math.PI * 2, true)
      context.fill()
      
      // 完成绘制
      context.draw()
    })
  }
}
</script>

3.2 错误处理事件

通过 @error 事件捕捉 canvas 组件发生的错误，并打印详细的错误信息。

<template>
  <view>
    <canvas canvas-id="errorCanvas" style="width: 300px; height: 200px;" @error="handleCanvasError"></canvas>
  </view>
</template>

<script>
import { ref } from 'vue'

export default {
  setup() {
    const handleCanvasError = (e) => {
      console.error('Canvas 错误:', e.detail.errMsg)
    }
    
    return {
      handleCanvasError
    }
  }
}
</script>