cnchar-trad

cnchar

theajack

好用小巧、功能全面的汉字拼音笔画js库

api详细文档地址

---

[TOC]

---

1.功能

1. 获取 汉字拼音 ，支持首字母、大小写、数组分割、备选 多音字 等功能
2. 支持 多音词
3. 支持 拼音音调
4. 获取汉字 笔画数 、支持数组分割
5. 获取汉字 笔画顺序 、笔画详细名称等
6. 支持 简体字 、 繁体字 、 火星文 互转
7. 支持 繁体字 拼音、笔画数，实现和简体字一样的功能
8. 体积小，最小压缩版本仅 42 kb
9. 多端可用，可用于 原生浏览器环境、webpack环境、nodejs环境...，几乎支持所有js能运行的环境
10. 丰富的配置，按需取用

2.概览

考虑到不同的需求，cnchar的功能被拆分到以下四个库中：

名称	描述	功能
cnchar	主js库，其他三个库依赖于这个库	含有简体字拼音、多音字、音调、笔画数等功能
cnchar-poly	多音词库	含有识别多音词功能
cnchar-order	笔画顺序库	含有识别笔画顺序、笔画名称、笔画形状等功能
cnchar-trad	繁体字库	支持繁体、火星、简体互转，支持繁体拼音笔画多音字全功能

3 安装

3.1 使用 npm 安装

安装四个库：

npm i cnchar cnchar-poly cnchar-order cnchar-trad

当然您也可以按需安装其中的几个，但是 cnchar 这个基础库是必须安装的

3.2 使用 script 引入

<script src="https://www.theajack.com/cnchar/dist/cnchar.2.0.0.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.poly.2.0.0.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.order.2.0.0.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.trad.2.0.0.min.js"></script>

4 使用

4.1 webpack、babel 等浏览器环境

npm 安装好几个库之后：

// 请保证最先引入 cnchar 基础库，其他几个库顺序无所谓
import cnchar from 'cnchar';
import 'cnchar-poly';
import 'cnchar-order';
import 'cnchar-trad';

console.log('汉字'.spell());// prototype 方式调用
console.log(cnchar.spell('汉字'));// cnchar api 调用

浏览器环境下会在 window 对象上定义 cnchar 对象

4.2 nodejs 等非浏览器环境

非浏览器环境下需要使用 cnchar.use() 方法加载功能库：

// 请保证最先引入 cnchar 基础库，其他几个库顺序无所谓
var cnchar = require('cnchar');
var poly = require('cnchar-poly');
var order = require('cnchar-order');
var trad = require('cnchar-trad');
cnchar.use(poly, order, trad);

console.log('汉字'.spell());// prototype 方式调用
console.log(cnchar.spell('汉字'));// cnchar api 调用

其他使用方式与浏览器环境一致

4.3 原生浏览器环境

原生浏览器环境就需要使用 script 标签引入js文件：

<script src="https://www.theajack.com/cnchar/dist/cnchar.2.0.0.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.poly.2.0.0.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.order.2.0.0.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.trad.2.0.0.min.js"></script>
<script>
    console.log('汉字'.spell());// prototype 方式调用
    console.log(cnchar.spell('汉字'));// cnchar api 调用
</script>

5 API

5.1 拼音笔画基础 API

为了尽可能使api使用简单，该库仅设计了两个主要的非常简洁 api，并保证调用参数一致：

// 获取汉字的拼音、多音词、音调等都集成在以下方法上
cnchar.spell(string[,...args]); 
// 或
string.spell([...args])

// 获取汉字的笔画、笔画顺序等都集成在以下方法上
cnchar.stroke(string[,...args]);
// 或
string.stroke([...args])

该 api 设计一致，string 表示要处理的汉字字符串

关键在于可选参数的配置，参数配置将在下一章单独介绍

5.2 繁体、简体、火星文互转

当引入 cnchar-trad 之后，cnchar 就具备了繁体、简体、火星文互转功能，使用 cnchar.convert 方法，你就可以使用这个功能：

cnchar.convert(string,to[,from]); // cnchar api 调用
//或
string.convert(to[,from]) // prototype 方式调用

string 必选 表示要处理的汉字字符串

to 必选 表示转到的目标文字类型

from 可选 当前的文字类型，如果不传入cnchar会自动识别，传入的话js执行效率会快一些

to和from的可选值有：simple,trad,spark

除了 convert 方法以外，cnchar 还提供了一些衍生的方法可供使用：

string.convert(to[,from]);
string.convertSimpleToTrad();
string.convertSimpleToSpark();
string.convertTradToSimple();
string.convertTradToSpark();
string.convertSparkToSimple();
string.convertSparkToTrad();
string.convertToTrad();
string.convertToSimple();
string.convertToSpark();

cnchar.convert.simpleToTrad(string);
cnchar.convert.simpleToSpark(string);
cnchar.convert.tradToSimple(string);
cnchar.convert.tradToSpark(string);
cnchar.convert.sparkToSimple(string);
cnchar.convert.sparkToTrad(string);
cnchar.convert.toTrad(string);
cnchar.convert.toSpark(string);
cnchar.convert.toSimple(string);

5.3 其他api

5.3.1 .use()

这个api的功能是显式启用 poly、order、trad 三个功能库

cnchar.use(...libs);

这个启用在非浏览器环境（比如nodejs等）中是必须的，使用如下：

// 请保证最先引入 cnchar 基础库，其他几个库顺序无所谓
var cnchar = require('cnchar');
var poly = require('cnchar-poly');
var order = require('cnchar-order');
var trad = require('cnchar-trad');
cnchar.use(poly, order, trad); // 参数顺序无关，三个参数可以任意选择

在浏览器环境中则无需调用：

// 请保证最先引入 cnchar 基础库，其他几个库顺序无所谓
import cnchar from 'cnchar';
import 'cnchar-poly';
import 'cnchar-order';
import 'cnchar-trad';

5.3.3 .type

type对象用户获取当前可用的 spell 和 stroke 参数类型：

var spellArg = cnchar.type.spell;
var strokeArg = cnchar.type.stroke;

spellArg 最多可用值： ["array", "low", "up", "first", "poly", "tone", "simple", "origin"]

strokeArg 最多可用值：["letter", "shape", "count", "name", "detail", "array", "order", "simple"]

具体用法第六章讲到

5.3.4 .check

该值是一个 布尔类型，用于控制是否开启参数校验，默认值为true

参数校验能够对 spell 和 stroke 传入的参数进行检查，在控制台显示 无效·，忽略和冗余的参数

cnchar.check = false; // 关闭参数校验

5.3.5 .version

获取当前版本：

var version = cnchar.version; // string 类型

5.3.5 .plugins

当前使用的功能库列表，最多的情况为 ["order", "trad", "poly"]

var plugins = cnchar.plugins; // array 类型

6 spell stroke 参数

6.1 spell 参数

参数调用如下，所有arg参数都是可选的

cnchar.spell(string,arg1,arg2,...); 
string.spell(arg1,arg2,...)

arg 参数信息如下：

参数	作用	是否默认	依赖库	备注
array	返回数组	否	--	--
first	返回拼音首字母	否	--	--
up	将结果全部大写	否	--	--
low	将结果全部小写	否	--	会被up参数覆盖
poly	使用候选多音字	否	--	使用cnchar-poly 且 使用了origin参数之后该参数会被忽略
tone	启用音调	否	--	--
origin	是否关闭多音词功能	否	cnchar-poly	使用cnchar-poly之后，默认会使用多音词进行转换，该参数用于禁用多音词
simple	是否繁体字的拼音功能	否	cnchar-trad	使用cnchar-trad之后，默认对繁体字拼音进行转换，该参数用于禁用繁体字拼音

6.2 stroke 参数

参数调用如下，所有arg参数都是可选的

cnchar.stroke(string,arg1,arg2,...); 
string.stroke(arg1,arg2,...)

arg 参数信息如下：

参数	作用	是否默认	依赖库	备注
array	返回数组	否	--	使用cnchar-order 且启用 order参数后该参数被忽略
order	启用笔画顺序	否	cnchar-order	--
letter	使用笔画顺序字母序列	是	cnchar-order	当启用order后，该值是默认值
detail	使用笔画顺序详情作为返回值，每个汉字对应一个json	否	cnchar-order	优先级小于letter
shape	使用笔画形状作为返回值	否	cnchar-order	优先级小于detail
name	使用笔画名称作为返回值	否	cnchar-order	优先级小于shape
count	使用笔画数作为返回值	否	cnchar-poly	优先级小于name
simple	是否繁体字的笔画功能	否	cnchar-trad	使用cnchar-trad之后，默认对繁体字启用笔画功能，该参数用于禁用繁体字笔画功能

6.3 使用实例大全：

6.3.1 cnchar 基础库功能

//spell 功能
"测试".spell() // 返回 'CeShi'
"测试".spell("up") // 返回 'CESHI'
"测试".spell("low") // 返回 'ceshi'
"测试".spell("first") // 返回 'CS'
"测试".spell("first","low") // 返回 'cs'
"测试".spell("array") // 返回 ['Ce','Shi']
"测试".spell("array","first","low") // 返回 ['c','s']
"测试".spell('tone') // 返回 'CèShì'
"长大了".spell('poly') // 返回 '(Zhang|Chang)(Da|Dai)(Le|Liao)'

//stroke 功能
"测".stroke() // 返回 9
"测试".stroke() // 返回 17
"测试".stroke('array') // 返回 [9,8]

备注：

1. string.spell(..arg)方法等价于 cnchar.spell(string,...args)
2. string.stroke(..arg)方法等价于 cnchar.stroke(string,...args)
3. spell 方法 非中文字符会返回原字符
4. stroke 方法 非中文字符会笔画数会计为 0
5. stroke 方法 order模式 非中文字符会返回 undefined

6.3.2 cnchar-poly 库功能

该库用于准确识别多音词，同样支持 6.3.1中的其他参数功能

"长大了".spell() // 返回 'ZhangDaLe'
"长大了".spell('array') // 返回 ["Zhang", "Da", "Le"]
"长大了".spell('poly') // 返回 'ZhangDaLe' poly参数失效
"长大了".spell('poly','origin') // 返回 "(Zhang|Chang)(Da|Dai)(Le|Liao)" origin参数用于启用原始的候选多音字功能

6.3.3 cnchar-order 库功能

该库用于查询汉字笔画顺序、笔画名称等，返回值为 数组

"一个".stroke('order') // 返回 ["j","slf"] 需要显式使用 order 参数 默认返回笔画数字母序列
"一个".stroke('order','detail') //
/* 返回详细笔画信息：
[
    [{
        "shape": "㇐", 
        "type": "平笔", 
        "foldCount": "0", 
        "name": "横"
    }],[{
        "shape": "㇓", 
        "type": "平笔", 
        "foldCount": "0", 
        "name": "撇"
    },{
        "shape": "㇏", 
        "type": "平笔", 
        "foldCount": "0", 
        "name": "捺"
    },{
        "shape": "㇑", 
        "type": "平笔", 
        "foldCount": "0", 
        "name": "竖"
    }]
]*/
"一个".stroke('order','shape') // 返回 [["横"],["撇", "捺", "竖"]]
"一个".stroke('order','name') // 返回 [["㇐"],["㇓","㇏","㇑"]]
"一个".stroke('order','count') // 返回 [1, 3]

6.3.4 cnchar-trad 库功能

该库用于支持繁体字火星文转换及其拼音笔画数功能

6.3.4.1 conver 方法

"一个人".convert('trad') // 返回 "壹個人"
"一个人".convert('spark') // 返回 "①個亾"
"一个人".convert('trad','simple') // 返回 "壹個人" 指定从简体转换为繁体
"壹個人".convert('simple') // 返回 "一个人"
"壹個人".convert('spark') // 返回 "①個亾"
// 其他api
"一个人".convertSimpleToTrad(); // 返回 "壹個人" 等价于 cnchar.convert.simpleToTrad
"一个人".convertSimpleToSpark(); // 返回 "①個亾" 等价于 cnchar.convert.simpleToSpark
"壹個人".convertTradToSimple(); // 返回 "一个人" 等价于 cnchar.convert.tradToSimple
"壹個人".convertTradToSpark(); // 返回 "①個亾" 等价于 cnchar.convert.tradToSpark
"①個亾".convertSparkToSimple(); // 返回 "一个人" 等价于 cnchar.convert.sparkToSimple
"①個亾".convertSparkToTrad(); // 返回 "壹個人" 等价于 cnchar.convert.sparkToTrad
"一个人".convertToTrad(); // 返回 "壹個人" 等价于 cnchar.convert.toTrad
"壹個人".convertToSimple(); // 返回 "一个人" 等价于 cnchar.convert.toSpark
"一个人".convertToSpark(); // 返回 "①個亾" 等价于 cnchar.convert.toSimple

6.3.4.1 spell 和 stroke 方法

该库增加了对于繁体字的拼音笔画功能扩展，其他基础用法与 基础库一致：

//spell 功能
"長大".spell() // 返回 'ZhangDa'
"長大".spell('simple') // 返回 '長Da' // 禁用繁体字拼音功能 

//stroke 功能
"長大".stroke('array')  // 返回 [8, 3]
"長大".stroke('array','simple') // 返回 [0, 3] // 禁用繁体字笔画功能
"長大".stroke('order','shape')  // 返回 [["㇐","㇑","㇐","㇐","㇐","㇙","㇓","㇏"],["㇐","㇓","㇏"]]
"長大".stroke('order','shape','simple') // 返回 [undefined, ["㇐","㇓","㇏"]]

7 应用例子

汉字打字游戏