更新记录

2.0.0（2026-08-14）

新增

• lime-hanzi-writer 组件，适配 uni-app / uni-app x（uvue + vue 双端）
• 笔顺书写动画：播放、逐笔动画、循环播放、暂停 / 继续
• 田字格背景（showGrid / gridColor）
• 逐笔高亮（highlightStroke）
• 笔顺测验（quiz）：支持测验提示、跳过笔画、错误回调等
• 自定义颜色（笔画 / 部首 / 高亮 / 轮廓 / 田字格）与尺寸（size / width / height）
• 本地汉字数据（charDataMap / setLocalCharData）与动态切换（setCharacter）
• 插件根 index.ts 统一导出公开静态 API（setLocalCharData / setCharDataVersion 等）

使用网络加载汉字数据时，组件会请求 https://cdn.jsdelivr.net/npm/hanzi-writer-data@{version}/{character}.json，小程序平台需在小程序后台配置该域名白名单；如需无网络请求，请使用本地数据。

平台兼容性

uni-app(4.44)

uni-app x(5.23)

name: lime-hanzi-writer 汉字笔顺动画组件 description: 汉字笔顺动画与测验组件，支持笔画书写动画、田字格、笔顺测验，可用于汉字教学、笔顺练习等场景 tags:

• hanzi-writer
• 汉字
• 笔顺
• 动画
• 书写
• canvas componentTag: l-hanzi-writer plugin: lime-hanzi-writer category: 业务组件 dependencies:

• lime-shared

lime-hanzi-writer 汉字笔顺动画组件

汉字笔顺动画与测验组件，支持笔画书写动画、田字格背景、笔顺测验等功能，可用于汉字教学、笔顺练习等场景。

插件依赖：lime-shared

安装方法

1. 在 uni-app 插件市场中搜索并导入 lime-hanzi-writer
2. 导入后可能需要重新编译项目
3. 在页面中使用 l-hanzi-writer 组件

代码演示

基础用法

显示一个汉字，带笔画书写动画。

<l-hanzi-writer character="永" :size="200" />

播放笔顺动画

通过 ref 调用 animateCharacter 方法，播放从第一笔到最后一笔的书写动画。

<l-hanzi-writer ref="writerRef" character="永" :size="200" />
<button @click="playAnimation">播放动画</button>

const playAnimation = () => {
  writerRef.value?.animateCharacter()
}

显示田字格

通过 showGrid 属性显示田字格背景辅助线。

<l-hanzi-writer character="永" :size="200" :showGrid="true" />

自定义颜色

<l-hanzi-writer
  character="永"
  :size="200"
  strokeColor="#333"
  highlightColor="#54b4d3"
  outlineColor="#ccc"
/>

使用本地字符数据

通过 charDataMap 传入本地字符数据，避免网络请求。数据格式参考 hanzi-writer-data。

<l-hanzi-writer character="永" :size="200" :charDataMap="dataMap" />

import yongData from '@/static/hanzi-data/永.json'

const dataMap = { '永': yongData }

笔顺测验

通过 quiz 方法进入测验模式，用户按正确笔顺书写。

<l-hanzi-writer ref="writerRef" character="永" :size="200" />
<button @click="startQuiz">开始测验</button>

const startQuiz = () => {
  writerRef.value?.quiz({
    onComplete: (summary) => {
      console.log('测验完成，总错误数:', summary.totalMistakes)
    }
  })
}

测验时同一笔画连续写错达到 showHintAfterMisses 次后会高亮提示正确写法，默认 3 次。可通过 prop 调整：

<!-- 第一次写错就提示 -->
<l-hanzi-writer character="永" :size="200" :show-hint-after-misses="1" />

循环播放动画

<l-hanzi-writer ref="writerRef" character="永" :size="200" />
<button @click="loopAnimation">循环播放</button>

const loopAnimation = () => {
  writerRef.value?.loopCharacterAnimation()
}

动态切换汉字

<l-hanzi-writer ref="writerRef" character="永" :size="200" />
<button @click="switchChar">切换</button>

const switchChar = () => {
  writerRef.value?.setCharacter('学')
}

网络请求与域名白名单

组件加载汉字笔顺数据时，若未通过 charDataMap 或 setLocalCharData 提供本地数据，会自动发起网络请求获取汉字数据：

https://cdn.jsdelivr.net/npm/hanzi-writer-data@{version}/{character}.json

• {version} 为内置 CDN 版本号（默认 2.0.1，可通过 setCharDataVersion 修改）
• {character} 为当前汉字，例如 永 的请求地址为 https://cdn.jsdelivr.net/npm/hanzi-writer-data@2.0.1/永.json

⚠️ 小程序必须配置合法域名白名单

微信小程序、支付宝小程序等平台对 wx.request / uni.request 有域名校验限制。使用网络加载（未配置本地数据）时，需要在各平台后台「服务器域名 → request 合法域名」中添加：

https://cdn.jsdelivr.net

若你通过 setCharDataVersion 切换了其他 CDN 源（如 unpkg.com），请对应添加该域名。

如不希望任何网络请求，请务必使用 使用本地字符数据 或调用 setLocalCharData 提供全量离线数据。

API 文档

Props

基础配置

动画配置

颜色配置

显示控制

数据配置

样式定制

Methods

通过 ref 调用组件方法。

上述方法通过组件 ref 调用。以下全局方法通过模块导入调用（设置内置数据加载器的行为）：

import { setLocalCharData, setCharDataVersion } from '@/uni_modules/lime-hanzi-writer'

// 全量离线：所有用到的汉字都需提前放入 map
setLocalCharData({ '永': yongData, '汉': hanData })

// 使用其它 CDN 版本（别忘了同步配置对应域名白名单）
setCharDataVersion('3.0.0')

Events

AnimationOptions

QuizOptions

StrokeData

updateColor 的 colorName 合法取值：strokeColor / radicalColor / highlightColor / outlineColor / drawingColor / highlightCompleteColor

Vue2 使用说明

插件使用了 composition-api，如需在 Vue2 项目中使用，请按照官方教程配置。

关键配置代码（在 main.js 中添加）：

// vue2
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
Vue.use(VueCompositionAPI)

快速预览

导入插件后，可以直接使用以下标签查看演示效果：

<!-- 代码位于 uni_modules/lime-hanzi-writer/components/lime-hanzi-writer -->
<lime-hanzi-writer />

插件标签说明

平台已知问题

uni-app x App 端