更新记录

1.0.0（2026-10-31） 下载此版本

• 首个版本，按 uni_modules 规范发布：uni_modules/czh-canvas，支持插件市场一键导入与从市场更新
• 透明覆盖批注画板：页面内容上手写，多色画笔 / 粗细 / 撤销 / 清空，画笔设置本地持久化
• 保存管线：内容快照 → 铺底色 → 合成笔迹 → 再次快照存相册；快照失败降级为 toDataURL + FileSystemManager 落临时文件
• 不依赖任何第三方插件：撤销了对 lime-file-utils 的依赖，鸿蒙端改用 uni 内置 FileSystemManager.writeFile（HBuilderX 4.61+ 支持）写 base64
• 导航栏四个图标随插件分发（uni_modules/czh-canvas/static），导入后无需再往项目 static 里拷图
• 颜色面板按可用宽度现算色块尺寸（每行固定 10 个，18~32px），窄屏不再出现最后一个色块换行错位

平台兼容性

uni-app x(4.71)

其他

czh-canvas 批注画板组件（uni-app x）

透明全屏手写画板覆盖组件，叠在页面内容上方直接批注，支持多色画笔、粗细调节、撤销、清空， 保存时把页面内容截图与笔迹合成后存入相册。适用于在页面内容上直接批注、手写的场景。

组件为 uni-app x（uvue + UTS + Vue3 组合式 API）实现，easycom 直接使用，无需注册。

本示例工程 pages/index/index.uvue 演示了组件的完整接入方式：自绘导航栏、画板开关、窗口变化重排、保存回调。

安装

组件已按 uni_modules 规范发布，二选一：

• 插件市场：插件详情页点「使用 HBuilderX 导入插件」，选择目标项目，导入后自动落在 uni_modules/czh-canvas；
• 手动：把 uni_modules/czh-canvas 整个目录复制到项目根目录的 uni_modules 下。

uni_modules/czh-canvas/
├─ package.json
├─ readme.md
├─ changelog.md
├─ components/czh-canvas/czh-canvas.uvue
└─ static/icon-cross.png · icon-download.png · icon-revoke.png · icon-clear.png

组件位于 uni_modules/*/components/组件名/组件名.uvue，符合 easycom 自动扫描规则：页面里直接写 <czh-canvas>，不需要 import，也不需要注册。

仅支持 uni-app x（uvue），不支持 uni-app（vue2/vue3）。

使用方式

<!-- 页面需 custom 导航并自绘同规格头部：画板覆盖层按 statusBarHeight + 44 定位 -->
<czh-canvas :visible="showCanvas" :scroll-height="scrollHeight" bg-color="#ffffff"
    content-element-id="demo-content" @close="onCanvasClose" @save="onCanvasSave"></czh-canvas>

// 页面  时需广播窗口变化，组件监听后重排画布并按比例缩放已有笔迹
(() => {
    calcHeight()
    uni.$emit('appWindowResize')
})

API

Props

Events

关键机制

• 透明覆盖批注：覆盖层 top = statusBarHeight + 44，画布 background-color: transparent 透出下方页面内容， 在内容上直接手写；安卓端 canvas 的 rgba 透明度会被忽略渲染成浅灰，所以必须用 transparent 关键字；
• 笔迹数据结构：每笔为一组线段（DrawLine：起点/终点/颜色/粗细），笔划（DrawStroke）入历史栈； 撤销 = pop 后整帧重绘，清空 = 清栈 + clearRect；
• 高清屏：按 pixelRatio 放大画布物理像素后 ctx.scale(dpr, dpr)，线条不发虚；
• 横竖屏 / 窗口变化：监听 appWindowResize（页面 广播）重算尺寸，已有笔迹按新旧画布比例缩放坐标后重绘，不丢笔迹；
• 保存管线：内容元素 takeSnapshot → 铺 bgColor 底 → drawImage 合成内容 → 重绘笔迹 → 再次 takeSnapshot 存相册； 任一环节失败逐级降级：canvas toDataURL + FileSystemManager 落临时文件（三端同一套代码）；
• 画笔设置持久化：颜色（storage key canvas_stroke_style）与粗细（canvas_line_width）写入本地缓存，下次打开保持。
• 颜色面板自适应：每行固定 10 个色块，宽高按 canvasw - 左右 padding - 选中边框 反算（18~32px 之间）， 360dp 窄屏也不会把最后一个色块挤到下一行；窗口变化时重算。

依赖

• 无第三方插件依赖；保存流程只用 uni 内置 API（FileSystemManager 的 writeFile 需 HBuilderX 4.61+）；
• 页面侧约定： 时 uni.$emit('appWindowResize')。

图标

导航栏四个图标为 PNG（颜色 #969799），随插件一起分发：

四个图标随插件分发，组件内用相对路径（../../static/icon-xxx.png）引用，导入后无需再往项目 static 里拷图。 「更多」按钮为纯 CSS 圆点，未使用图片。示例页的画笔入口图标为项目自己的 /static/edit-note.png。