theajack/cnchar 项目中的汉字绘制功能详解

theajack/cnchar 项目中的汉字绘制功能详解

cnchar 🇨🇳 功能全面的汉字工具库 (拼音 笔画 偏旁 成语 语音 可视化等) (Chinese character util) 项目地址: https://gitcode.com/gh_mirrors/cn/cnchar

一、cnchar-draw 库概述

cnchar-draw 是 theajack/cnchar 项目中的一个重要插件，专注于汉字可视化绘制功能。该库基于 hanzi-writer 实现，提供了多种汉字绘制模式，能够满足不同场景下的汉字展示需求。

核心特点

1. 多模式支持：提供 normal、animation、stroke、test 四种绘制模式
2. 独立使用：既可以作为 cnchar 插件使用，也能独立运行
3. 繁体支持：原生支持繁体字绘制，无需额外依赖
4. 丰富配置：提供大量可配置参数，满足个性化需求
5. 交互功能：支持测试模式，可检测用户绘制是否正确

二、安装与基础使用

安装方式

npm 安装（推荐）

npm i cnchar-draw

CDN 引入

<script src="https://fastly.jsdelivr.net/npm/cnchar-draw/cnchar.draw.min.js"></script>

基础使用示例

作为 cnchar 插件使用

import cnchar from 'cnchar';
import draw from 'cnchar-draw';
cnchar.use(draw); // 在浏览器环境中 use 非必须

独立使用

import draw from 'cnchar-draw';
draw('你好');

三、绘制模式详解

cnchar-draw 提供四种绘制模式，每种模式适用于不同场景：

1. 常规模式 (normal)

默认模式，直接显示完整的汉字。

cnchar.draw('汉字', {type: 'normal'});

2. 笔顺模式 (stroke)

按汉字笔顺单步绘制，适合教学场景。

cnchar.draw('汉字', {type: 'stroke'});

3. 动画模式 (animation)

带有绘制动画，支持多种动画效果。

cnchar.draw('汉字', {
    type: 'animation',
    animation: {
        strokeAnimationSpeed: 2, // 笔画绘制速度
        delayBetweenStrokes: 800 // 笔画间隔时间
    }
});

4. 测试模式 (test)

用户可以在容器内绘制汉字，系统会检测绘制是否正确。

cnchar.draw('汉字', {
    type: 'test',
    test: {
        showHintAfterMisses: 3 // 3次错误后显示提示
    }
});

四、配置参数详解

cnchar-draw 提供了丰富的配置选项，主要分为以下几类：

1. 基础配置

• el: 绘制容器（ID 或 DOM 元素）
• type: 绘制模式
• clear: 绘制前是否清空容器
• onComplete: 绘制完成回调

2. 样式配置

style: {
    showOutline: true, // 显示轮廓
    showCharacter: true, // 显示字符
    currentColor: '#b44', // 当前笔画颜色（仅stroke模式）
    length: 60, // 大小
    padding: 5, // 内边距
    outlineColor: '#ddd', // 轮廓颜色
    strokeColor: '#555', // 笔画颜色
    radicalColor: null, // 偏旁颜色
    strokeFadeDuration: 400 // 笔画淡出时间
}

3. 背景线条配置

line: {
    lineStraight: true, // 显示直线
    lineCross: true, // 显示交叉线
    lineWidth: 1, // 线宽
    lineColor: '#ddd', // 线条颜色
    lineDash: true, // 虚线
    border: true, // 显示边框
    borderWidth: 1, // 边框宽度
    borderColor: '#ccc', // 边框颜色
    borderDash: false // 边框虚线
}

4. 动画配置

animation: {
    strokeAnimationSpeed: 1, // 笔画动画速度
    delayBetweenStrokes: 1000, // 笔画间隔
    delayBetweenLoops: 200, // 循环间隔
    autoAnimate: true, // 自动动画
    animateComplete: () => {}, // 动画完成回调
    stepByStep: true, // 逐步动画
    loopAnimate: false // 循环动画
}

5. 测试模式配置

test: {
    strokeHighlightSpeed: 20, // 提示高亮速度
    highlightColor: '#aaf', // 高亮颜色
    drawingColor: '#333', // 绘制线条颜色
    drawingWidth: 4, // 绘制线条宽度
    showHintAfterMisses: 3, // 错误次数后提示
    highlightOnComplete: true, // 完成时高亮
    highlightCompleteColor: null, // 完成高亮颜色
    onTestStatus: ({index, status, data}) => {} // 测试状态回调
}

五、动画控制 API

当使用动画模式时，可以通过返回的 writer 对象控制动画：

const writer = cnchar.draw('汉字', {type: 'animation'});

// 开始动画（当autoAnimate=false时）
writer.startAnimation();

// 暂停动画
writer.pauseAnimation();

// 恢复动画
writer.resumeAnimation();

// 重新开始动画
writer.restartAnimation();

// 绘制下一笔（单步模式）
writer.drawNextStroke(() => {
    console.log('当前笔画绘制完成');
});

六、特殊场景处理

汉字不存在回调

cnchar.draw.onWordNotFound(word => {
    console.log('未找到汉字:', word);
});

微信小程序使用说明

目前 cnchar-draw 主要支持 Web 环境，如需在微信小程序中使用，建议参考 hanzi-writer 的小程序适配方案。

七、最佳实践建议

1. 教学场景：使用 stroke 模式展示笔顺，或 test 模式让学生练习
2. 展示场景：使用 animation 模式增加视觉效果
3. 性能优化：对于复杂汉字，适当调整 strokeAnimationSpeed 参数
4. 响应式设计：监听容器尺寸变化，重新绘制以适应不同屏幕

通过合理配置 cnchar-draw 的参数，开发者可以轻松实现各种汉字可视化需求，从简单的展示到复杂的交互教学功能都能胜任。

cnchar 🇨🇳 功能全面的汉字工具库 (拼音 笔画 偏旁 成语 语音 可视化等) (Chinese character util) 项目地址: https://gitcode.com/gh_mirrors/cn/cnchar