用 drawink 给业务页面加一层画板:从网页批注到无限板书

0 阅读9分钟

一份 Canvas 2D 核心,三种框架接入。把圈画、几何示意、保存与导出接进自己的产品。

image.png

网页保留内容,画板记录思路。

开发业务系统时,经常会碰到这样的需求:在题目旁边画一条辅助线,给课件圈出重点,或者在讨论过程中临时画一张几何示意图。

这些功能看起来只是“加个 Canvas”,真正落地却要处理输入坐标、对象移动、撤销重做、页面滚动、数据恢复和图片导出。接进 Vue 或 React 后,还要处理组件卸载与受控数据同步。

drawink 把这些能力整理成一个可以嵌入网页的画板库。 它面向网页板书、教学几何与内容批注,核心使用原生 Canvas 2D,没有运行时依赖;Vue 和 React 通过各自的适配包接入同一个核心。

01 从真实页面上的批注开始

文档批注模式适合已有内容的页面。标题、文字和图片继续由宿主 DOM 渲染,drawink 在独立的透明绘图层上叠加笔迹。这样,业务内容与批注可以分别管理,原文仍然保持自己的结构。

image.png

文档模式:在原有文字和公式上直接标记。

默认工具栏已经提供画笔、移动、对象擦除、形状、撤销、重做、背景和 PNG 导出。遇到长课件,可以设置 contentHeight,通过滚动工具或滚轮查看后续内容。

这套方式依赖固定的文档坐标。接入时要保持逻辑尺寸、内容高度与 DOM 布局一致;文字换行、图片加载或原文重排后,库不会自动寻找新的文字锚点。对课件、题目卡片、固定布局文档,它的使用方式更容易控制。

02 自由书写与教学几何都准备好了

再次点击已选中的画笔,就能修改颜色、粗细和透明度。细线用于辅助线,粗一些的半透明笔迹适合强调重点。设置只作用于之后绘制的对象,已有笔迹保留自身样式。

image.png

画笔设置通过默认面板或 setBrush API 调整。

平面图形包括直线、矩形、圆、椭圆、三角形、菱形、梯形和平行四边形;立体示意包括长方体、圆柱和圆锥。选择工具后拖动即可绘制,立体图形的隐藏辅助边以虚线呈现。

image.png

长方体、圆柱、圆锥是内置工具,适合教学中的空间关系示意。

对象操作也有明确语义:移动工具按包围盒选中最上层对象并整体拖动;擦除工具拖出一个矩形,删除包围盒与区域相交的整个对象。它不是像素橡皮擦,也没有对象旋转、尺寸控制点和多对象编组。

笔迹提交、对象移动、擦除和清空都可以进入历史记录。撤销后继续绘制,会产生新的历史分支,旧的重做路径随之截断。

03 文档批注之外,还有无限画板

当内容需要不断向外延伸时,可以选择 infinite 模式。它支持平移、滚轮缩放、双指平移和缩放,并提供“显示全部”“重置缩放”“回到原点”等视野操作。

image.png

无限模式:相机控制视野,图形保留世界坐标。

绘制、移动或擦除时,把指针保持在边缘,默认开启的 autoPan 会继续推进视野。缩放范围为 0.001%—800%。视野变化不修改图形端点,也不进入笔迹撤销历史。

背景支持透明或十六进制底色,以及纯色、点阵、网格三种样式。纹理颜色与间距可调;无限模式缩得很小时,会采用更疏的纹理层级,以保持背景可见。

选择模式时,可以先问业务需要什么:保留原有网页阅读布局,用文档模式;让绘图空间持续延伸,用无限模式。普通 DOM 不会自动跟随无限相机移动,网页元素的位置仍由接入方管理。

04 几行代码接进现有项目

三个包分别对应原生 JavaScript / TypeScript、Vue 3.3+ 和 React / React DOM 18+。它们共享数据格式、工具名称与核心配置。

# 按项目框架选择其中一个
npm install @drawink/core
npm install @drawink/vue
npm install @drawink/react

原生接入先准备一个有明确高度的容器:

<div id="lesson" style="height:560px;position:relative">
  <h2>圆柱的体积</h2>
  <p>V = πr²h</p>
</div>
import { Drawboard } from '@drawink/core'

const board = new Drawboard(
  document.querySelector('#lesson'),
  {
    mode: 'document',
    color: '#176b52',
    lineWidth: 3,
    onChange(data) {
      // 交给业务状态层;持久化建议防抖。
      console.log(data)
    },
  },
)

board.setTool('cylinder')
// 页面退出时执行:board.destroy()

工具栏样式由库自动注入,不需要另外导入 CSS。一个容器只能拥有一个存活的核心实例;销毁时会清理本实例创建的节点、监听器与观察器,保留宿主原有内容。

Vue 适配器提供 v-model:data、change、ready 和组件 ref:

<script setup lang="ts">
import { ref } from 'vue'
import { Drawboard, type DrawingData } from '@drawink/vue'

const data = ref<DrawingData>()
const options = { mode: 'infinite' as const }
</script>

<template>
  <Drawboard v-model:data="data" :options="options"
    style="height:560px" />
</template>

React 使用 data 与 onChange 组成受控用法,也可以不传 data,由内部实例管理绘图:

import { useState } from 'react'
import { Drawboard, type DrawingData } from '@drawink/react'

const options = { mode: 'infinite' as const }

export function LessonBoard() {
  const [data, setData] = useState<DrawingData>()
  return <Drawboard data={data} onChange={setData}
    options={options} style={{ height: 560 }} />
}

两个适配器都会在卸载时销毁核心,组件 ref 暴露共享操作方法。它们可以在 SSR 环境导入,服务端只渲染容器及其内容,实际画布在客户端挂载后创建。

05 保存可编辑数据,导出可分享图片

绘图内容通过版本化 JSON 保存。业务系统可以给它关联文档 ID、课件 ID 或工单 ID;保存到哪里,由接入方决定。

const json = JSON.stringify(board.getData())
localStorage.setItem('lesson-drawing', json)

const saved = localStorage.getItem('lesson-drawing')
if (saved) board.loadData(saved)

const png = await board.exportBlob({
  fit: true,
  includeBackground: true,
})

getData() 返回独立快照。loadData() 会先校验完整文档,校验失败时保留现有内容,成功后把新文档作为历史起点。加载不会触发 onChange,以避免受控数据回流。JSON 保存图形、背景和无限视野,不保存撤销历史、网页 DOM 或自定义绘图函数。

image.png

JSON 用于恢复编辑;PNG 用于分享批注结果。

图片 API 提供 exportImage() 和 exportBlob(),分别返回 PNG Data URL 与 PNG Blob 的 Promise。工具栏默认使用自动适配,包含离屏与负坐标图形,将每条图片边控制在 4096px 以内;通过 API 导出大画板时,也建议传 fit: true。

导出的 PNG 只包含已提交批注,以及可选的画板背景,不包含网页文字、图片或 iframe 截图。 如果业务需要“原文+批注”的完整图片,需要额外完成截图与合成。

06 从源码看三个关键设计

image.png

适配器处理框架生命周期,核心维护交互与数据,Canvas 负责绘制。

第一,对象数据驱动绘制。 model.ts 负责文档校验、快照、包围盒与历史;renderer.ts 根据 Shape 渲染图形。画笔保存点序列,普通几何图形保存两个端点及样式。移动、擦除、恢复和导出因此可以围绕同一份数据工作。

第二,世界坐标与屏幕坐标分离。 无限模式通过视野平移和缩放映射坐标。输入先换算回世界坐标,再更新对象;渲染时应用相机变换。视野变化无需重写原始图形,交互位图也保持可见区域大小。

无限视图中的笔宽按屏幕 CSS 像素显示,最低为 1.5px,以减少缩小时线条变淡;JSON 中的原始笔宽仍然保持不变。交互画布还限制最多 2 倍设备像素比,并按像素预算控制位图尺寸。

第三,适配器负责框架边界。 Vue 使用挂载与卸载钩子管理核心,React 在 effect 中创建和销毁实例,并处理 StrictMode 的挂载清理。数据回流前进行相等判断,把组件状态与核心绘图同步起来。

这些设计也有规模成本:当前渲染会遍历图形,历史以序列化状态快照保存。historyLimit 限制的是状态数量,并非内存字节数。海量笔迹、移动 WebView 和实际数位笔,需要用真实负载验证,不能仅凭演示推断性能。

07 接进公司业务,还能怎么扩展

默认工具栏支持六种预设位置,也支持 { x, y } 坐标。图标可使用图片、SVG、fonticon、文字或 DOM 工厂;设置 toolbar: false 后,可以完全自建工具栏。

toolbarItems 用于增加业务按钮。回调收到共享 Handle,可以读取数据或导出图片。演示里的“保存 JSON”按钮就是接入方扩展,网络请求与文件处理由应用完成。

image.png

星形是演示注册的自定义形状,也可替换成自己的业务标记。

自定义形状通过 registerShape() 或构造配置注册,定义只属于当前实例。JSON 仅保存形状 ID,因此恢复前要先注册同 ID 的绘图定义。绘制内容应限制在端点定义的矩形内,确保选择、移动、擦除与导出边界一致。

权限和输入也应按场景配置:readOnly 禁止图形编辑与历史操作,保留浏览和导出;disabled 让画布不接收指针,以便操作底层 DOM;penOnly 忽略手指绘图,仍允许鼠标、笔与无限模式双指导航。它不等于硬件级掌压识别,自定义按钮也要自行同步业务权限。

drawink 不包含账号、云存储、多人协作服务或课堂同步协议。落地时,建议把文档标识、布局版本、权限、保存失败反馈与持久化接口放在业务层管理。

从一个真实业务页面开始

如果需求是网页圈画、题目讲解或轻量板书,可以先选一个真实页面,跑通“绘制 → 保存 → 恢复 → 导出”的闭环,再决定是否扩展形状、替换工具栏或接入服务端。

项目提供 JavaScript、Vue 和 React 演示,采用 MIT 许可证。使用与分发时,请保留许可证要求的版权声明和许可文本。

在线演示:jacky010.github.io/drawink/
源码:github.com/Jacky010/dr…
npm:@drawink/core · @drawink/vue · @drawink/react