更新记录

1.0.0（2026-05-23）

初始化版本发布。

平台兼容性

uni-app(5.0)

uni-app x(5.0)

zf-hanziWriter

zf-hanziWriter 是一个 uni-app x 前端组件插件，面向 Web、Android、iOS、Harmony 四端复刻 Hanzi Writer 的核心能力：

• 离线汉字渲染
• 笔顺动画
• 单笔高亮
• 循环动画
• 描红测验

插件不加载 CDN，不内置网络请求，不采集任何数据。汉字数据优先级如下：

1. charData
2. charDataMap
3. 插件内置离线字库

使用前提

Web

Web 端无需额外配置，可以直接使用。

Harmony

Harmony 端当前无需额外启用原生模块，可以直接使用。

Android

Android App 端必须启用 uni-canvas，否则 <canvas> 无法正常渲染。

请在项目根目录 manifest.json 中确认存在下面配置：

{
  "app-android": {
    "distribute": {
      "modules": {
        "uni-canvas": {}
      }
    }
  }
}

如果你是通过 HBuilderX 可视化界面配置：

1. 打开项目根目录 manifest.json
2. 切换到 Android App 模块配置
3. 勾选 uni-canvas
4. 保存后重新运行到设备或模拟器

iOS

iOS App 端同样必须启用 uni-canvas。

请在项目根目录 manifest.json 中确认存在下面配置：

{
  "app-ios": {
    "distribute": {
      "modules": {
        "uni-canvas": {}
      }
    }
  }
}

如果运行时控制台提示：

未找到 "canvas" 组件，已自动当做 "view" 组件处理

说明当前使用的 iOS 基座没有打进 uni-canvas。这种情况下，仅修改 manifest.json 还不够，还需要：

1. 重新制作包含 uni-canvas 的自定义基座
2. 用新的自定义基座重新运行项目

基础用法

<template>
  <zf-hanziWriter
    ref="writerRef"
    character="张"
    :width="320"
    :height="320"
    :padding="20"
    :show-character="true"
    :show-outline="true"
    :show-grid="true"
    stroke-color="#555"
    radical-color="#168F16"
    outline-color="#DDD"
    highlight-color="#AAF"
    drawing-color="#333"
    :drawing-width="8"
    @ready="onReady"
    @error="onError"
    @quiz-correct-stroke="onQuizCorrectStroke"
    @quiz-complete="onQuizComplete"
  />
</template>

<script setup lang="uts">
const writerRef = ref<ComponentPublicInstance | null>(null)

function onReady(event : any) {
  console.log('ready', JSON.stringify(event))
}

function onError(event : any) {
  console.log('error', JSON.stringify(event))
}

function onQuizCorrectStroke(event : any) {
  console.log('quiz-correct-stroke', JSON.stringify(event))
}

function onQuizComplete(event : any) {
  console.log('quiz-complete', JSON.stringify(event))
}
</script>

调用方法

当前插件作为前端组件插件发布，组件方法通过 ref 配合 $callMethod 调用。

// 播放整字笔顺动画
writerRef.value?.$callMethod('animateCharacter')

// 播放第 0 笔
writerRef.value?.$callMethod('animateStroke', 0)

// 高亮第 1 笔
writerRef.value?.$callMethod('highlightStroke', 1)

// 循环播放
writerRef.value?.$callMethod('loopCharacterAnimation')

// 进入描红
writerRef.value?.$callMethod('quiz', {
  quizStartStrokeNum: 0,
  leniency: 1
} as UTSJSONObject)

// 取消描红
writerRef.value?.$callMethod('cancelQuiz')

// 切换汉字
writerRef.value?.$callMethod('setCharacter', '我')

// 更新颜色
writerRef.value?.$callMethod('updateColor', 'strokeColor', '#2563eb')

// 更新尺寸
writerRef.value?.$callMethod('updateDimensions', {
  width: 360,
  height: 360,
  padding: 20
} as UTSJSONObject)

// 重置
writerRef.value?.$callMethod('reset')

主要属性

支持 Hanzi Writer 常用配置项：

• character
• charData
• charDataMap
• width
• height
• padding
• showOutline
• showCharacter
• showGrid
• strokeAnimationSpeed
• strokeHighlightSpeed
• strokeFadeDuration
• strokeHighlightDuration
• delayBetweenStrokes
• delayBetweenLoops
• strokeColor
• radicalColor
• highlightColor
• outlineColor
• drawingColor
• drawingWidth
• showHintAfterMisses
• markStrokeCorrectAfterMisses
• quizStartStrokeNum
• acceptBackwardsStrokes
• leniency
• highlightOnComplete
• highlightCompleteColor

组件方法

对外暴露的方法如下：

• showCharacter
• hideCharacter
• showOutline
• hideOutline
• updateDimensions
• updateColor
• animateCharacter
• animateStroke
• highlightStroke
• loopCharacterAnimation
• pauseAnimation
• resumeAnimation
• setCharacter
• quiz
• cancelQuiz
• loadCharacterData
• getScalingTransform
• getCurrentCharData
• startAnimation
• startQuiz
• reset

事件

支持以下事件：

• ready
• error
• load-char-data-success
• load-char-data-error
• animate-start
• animate-complete
• quiz-start
• quiz-mistake
• quiz-correct-stroke
• quiz-complete
• update-color
• update-dimensions

汉字数据

插件内置 hanzi-writer-data@2.0.1 的部分离线数据：

• 一
• 我
• 张
• 爽
• 草
• 国
• 激
• 轮
• 很
• 测
• 码
• 六
• 是
• 人
• 酷

如果你需要全量离线字库（简体和繁体），可以直接使用下面两个官方来源：

Hanzi Writer 官方兼容全量数据包

适合直接给 Hanzi Writer 或 zf-hanziWriter 做离线按字加载，数据格式与 Hanzi Writer 兼容，按“每个汉字一个 JSON 文件”组织，可用于简体和繁体汉字的全量离线加载方案。

• GitHub 仓库： https://github.com/chanind/hanzi-writer-data
• npm 包下载地址： https://registry.npmjs.org/hanzi-writer-data/-/hanzi-writer-data-2.0.1.tgz

Make Me a Hanzi 全量原始字库

这是 Hanzi Writer 数据的上游来源，官方说明覆盖 9000+ 常见简体和繁体汉字。需要自己做一次格式转换或预处理时，可以直接下载原始数据：

• 字典数据 dictionary.txt： https://raw.githubusercontent.com/skishore/makemeahanzi/master/dictionary.txt
• 笔画图形数据 graphics.txt： https://raw.githubusercontent.com/skishore/makemeahanzi/master/graphics.txt

如果你需要更多汉字，可以通过 charData 或 charDataMap 传入自定义数据。数据结构需与 Hanzi Writer 数据格式保持一致，至少包含：

• strokes
• medians
• radStrokes 可选

示例：

const customCharData = {
  strokes: [
    'M 0 0 L 100 100'
  ],
  medians: [
    [[0, 0], [100, 100]]
  ],
  radStrokes: []
} as UTSJSONObject

单字：

<zf-hanziWriter
  character="字"
  :char-data="customCharData"
/>

多字：

const customMap = {
  '字': customCharData
} as UTSJSONObject

<zf-hanziWriter
  :character="currentCharacter"
  :char-data-map="customMap"
/>