> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/theajack/cnchar) · [上游 README](https://github.com/theajack/cnchar/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
🚀 功能齐全、支持多端的汉语拼音笔画 JS 库
**[中文](https://github.com/theajack/cnchar) | [在线试用 / 文档](https://theajack.github.io/cnchar) | [更新日志](https://theajack.github.io/cnchar/guide/version.html) | [反馈错误 / 遗漏](https://github.com/theajack/cnchar/issues/new) | [Gitee](https://gitee.com/theajack/cnchar) | QQ 群：958278438 | [留言板](https://theajack.github.io/message-board/?app=cnchar)**
### 应用示例
在开始阅读文档之前，我们先来看一些使用案例，了解 cnchar 能做什么
[汉字打字游戏](https://theajack.github.io/type/) | [打字弹钢琴](https://theajack.github.io/piano/) | [成语接龙](https://theajack.github.io/jsbox/?github=theajack.cnchar@master.helper/jsbox/idiom.js) | [通讯录排序](https://theajack.github.io/jsbox/?github=theajack.cnchar@master.helper/jsbox/sort.js) | [姓名](https://theajack.github.io/jsbox/?github=theajack.cnchar@master.helper/jsbox/name.js) | [输入法](https://theajack.github.io/jsbox/?github=theajack.cnchar@master.helper/jsbox/input.js) | [歇后语](https://theajack.github.io/jsbox/?github=theajack.cnchar@master.helper/jsbox/xhy.js) | [语音识别与合成](https://theajack.github.io/jsbox/?github=theajack.cnchar@master.helper/jsbox/voice.js) | [简繁转换](https://theajack.github.io/jsbox/?github=theajack.cnchar@master.helper/jsbox/trad.js)
---
### 前言
感谢您对 cnchar 的支持。由于 cnchar 词库来源于网络，尽管由我进行了修改和扩充，但仍难免存在错误与遗漏。希望您能够 [反馈](https://github.com/theajack/cnchar/issues/new) 使用过程中发现的错误与遗漏（您也可以自行修改并提交，经审核无误后将合并入 cnchar）
[我要报告错误或遗漏](https://github.com/theajack/cnchar/issues/new)
### 快速使用
使用 npm 安装：
```
npm i cnchar
```
```js
import cnchar from 'cnchar';
'汉字'.spell();
'汉字'.stroke();
```
使用 script 标签引入：
```html
```
### 1. 功能特性
1. 获取**汉语拼音**，支持首字母、大小写、数组分割，可选**多音字**等功能
2. 支持**多音词**、**拼音声调**
3. 获取汉字**笔画数**、**笔顺**及详细笔画名称
4. 支持可视化**绘制汉字笔画**，多种绘制模式可选
5. 支持**语音合成**与**语音识别**
6. 支持**汉字组词**与**汉字释义**
7. 支持**简体字**、**繁体字**、**火星文**互相转换
8. 支持**查找**某一拼音的所有**汉字**、繁体字、多音字
9. 支持**查找**指定笔画数的所有**汉字**、繁体字
10. 支持**按笔顺搜索**汉字
11. 支持**搜索拼音信息**，包括声母、韵母、声调、声调位置等
12. 支持**繁体字**拼音、笔画数及上述全部功能，实现与简体字相同的功能
13. 支持**成语**查询，可按汉字、拼音（带声调）、笔画数查询成语
14. 支持**歇后语**查询，支持模糊查询
15. 支持**部首**查询
16. 支持**随机生成**拼音、汉字、词语、成语、歇后语、中文姓名
17. 支持**汉字编码查询**、**汉字信息查询**
18. 支持**拼音输入法**、**五笔输入法**，支持联想输入
19. 支持**自定义插件**，独立且简单的接入方式，可充分使用 cnchar 的全部功能
20. 支持**自定义**拼音、笔画等数据，使用更灵活
21. 对部分大型词典，支持**离线使用**、**自定义部署**
22. 提供汉字工具，方便开发者更便捷、高效地操作拼音与汉字
23. **体积小**，min 版本仅 75 kb，zip 版本 50 kb（内含大量汉语拼音词典）
24. **多端可用**，可用于**浏览器、nodejs、小程序/小游戏、ReactNative/Weex/Uniapp/Electron、webpack**……，支持所有可运行 JS 的环境
25. **typescript**，主库及全部插件库均使用 typescript 开发
26. 配置丰富，按功能拆分为插件，可按需使用
27. 支持 **IE9** 及以上
### 2. 功能与插件概览
考虑到不同需求，cnchar 的功能拆分为以下多个插件库，方便开发者按需使用：
| 名称 | 描述 | 功能 | 支持版本 | Node 支持 | 小程序 |
| :------------: | :--------------------------------------------: | :--------------------: | :--------------------------------: | :--------------------: | :--------------------------------: |
| cnchar | 主 JS 库，其余三个库依赖于此库 | 包含简体汉语拼音、多音字、声调、笔画数等功能 | -- | 是 | 是 |
| cnchar-poly | 多音词词库 | 包含识别多音词的功能 | -- | 是 | 是 |
| cnchar-order | 笔顺库 | 包含识别笔顺、笔画名称、笔画形状等功能 | -- | 是 | 是 |
| cnchar-trad | 繁体字库 | 支持繁体、火星文、简体互转，支持繁体拼音、笔画及多音字等完整功能 | -- | 是 | 是 |
| cnchar-draw | 笔画绘制库 | 支持可视化绘制汉字，可不依赖 cnchar 单独使用，此库仅可在浏览器环境中使用 | 2.1+ | 否 | 部分支持 |
| cnchar-idiom | 成语库 | 支持成语查询等功能 | 2.2+ | 是 | 是 |
| cnchar-xhy | 歇后语库 | 支持歇后语查询等功能 | 2.2+ | 是 | 是 |
| cnchar-radical | 部首库 | 支持查询汉字部首 | 2.2.5+ | 是 | 是 |
| cnchar-words | 汉字组词词库 | 支持根据单个或多个汉字查询词语 | 3.1.0+ | 是 | 是 |
| cnchar-explain | 汉字释义库 | 支持查询汉字含义 | 3.1.0+ | 是 | 是 |
| cnchar-voice | 语音识别与语音合成 | 支持中文发音与合成 | 3.1.0+ | 否 | 部分支持 |
| cnchar-data | 离线词典库 | 支持部分插件库的离线使用与自定义部署 | 3.1.0+ | 是 | 是 || cnchar-random | 随机生成库 | 随机生成拼音、汉字、词语、成语、歇后语 | 3.2.0+ | 是 | 是 |
| cnchar-input | 输入法支持 | 支持拼音与五笔输入法结果 | 3.2.0+ | 是 | 是 |
| cnchar-code | 汉字编码库 | 汉字编码查询 | 3.2.0+ | 是 | 是 |
| cnchar-info | 汉字信息查询 | 用于查询汉字信息 | 3.2.0+ | 是 | 是 |
| cnchar-name | 中文姓名信息 | 用于随机生成姓名 | 3.2.0+ | 是 | 是 |
**自 v3.2.4 起，本 readme 不再维护详细 API 文档，请前往 [在线文档](https://theajack.github.io/cnchar/)**
### 3. 安装
#### 3.1 使用 npm 安装
安装基础库：
```
npm i cnchar
```
安装额外的功能库：
```
npm i cnchar-poly cnchar-order cnchar-trad cnchar-draw cnchar-idiom cnchar-xhy cnchar-radical cnchar-words cnchar-explain cnchar-voice cnchar-random cnchar-code cnchar-input cnchar-info cnchar-name
```
当然，你也可以按需安装其中若干个；插件库也可以独立于 cnchar 安装和使用，但部分库功能强依赖 cnchar，例如 cnchar-poly cnchar-order cnchar-trad
或者，你可以通过安装 `cnchar-all` 来使用完整功能，该库引用了上述所有插件库
```
npm i cnchar-all
```
#### 3.2 使用 CDN 引入
**如果 jsdelivr 不可用，可以使用 unpkg（https://unpkg.com/cnchar/cnchar.min.js)**
```html
```
或使用以下 CDN，其中包含上述十一个库
```html
```
### 4. 使用
#### 4.1 webpack 浏览器环境（含 window 对象）
通过 npm 安装若干库之后：
```js
// Please ensure that the cnchar base library is introduced first, and the order of the other libraries does not matter
import cnchar from 'cnchar';
import 'cnchar-poly';
// ... For other plugins, please refer to Chapter 2 2. Overview of functions and plugins
// Please use the plugin as needed
console.log('汉字'.spell()); // Called by prototype
console.log(cnchar.spell('汉字')); // cnchar api call
```
在浏览器环境中，window 对象上会定义一个 cnchar 对象
#### 4.2 Node.js 及其他非浏览器环境
在非浏览器环境中，你需要使用 `cnchar.use()` 方法来加载功能库：
```js
// Please ensure that the cnchar base library is introduced first, and the order of the other libraries does not matter
var cnchar = require('cnchar');
var poly = require('cnchar-poly');
// ... For other plugins, please refer to Chapter 2 2. Overview of functions and plugins
// Please use the plugin as needed
// Note: cnchar-draw, cnchar-voice are not available in non-browser environments
cnchar.use(poly);
console.log('汉字'.spell()); // Called by prototype
console.log(cnchar.spell('汉字')); // cnchar api call
```
其他用法与浏览器环境一致
#### 4.3 原生浏览器环境
原生浏览器环境需要使用 script 标签引入 js 文件：
```html
```
**致谢**
`cnchar-draw` 库的函数基于 [hanzi-writer](https://github.com/chanind/hanzi-writer),，非常感谢！
**贡献者**
[](https://github.com/theajack/cnchar/graphs/contributors)
