好用小巧、功能全面的汉字拼音笔画js库
在线试用
[TOC]
0.快速使用
import cnchar from 'cnchar';
'汉字'.spell();
'汉字'.stroke();
<script src="https://www.theajack.com/cnchar/dist/cnchar.2.0.1.min.js"></script>
<script>
'汉字'.spell();
'汉字'.stroke();
</script>
1.功能
- 获取 汉字拼音 ,支持首字母、大小写、数组分割、备选 多音字 等功能
- 支持 多音词
- 支持 拼音音调
- 获取汉字 笔画数 、支持数组分割
- 获取汉字 笔画顺序 、笔画详细名称等
- 支持 简体字 、 繁体字 、 火星文 互转
- 支持 繁体字 拼音、笔画数,实现和简体字一样的功能
- 体积小,最小压缩版本仅 42 kb
- 多端可用,可用于 原生浏览器环境、webpack环境、nodejs环境...,几乎支持所有js能运行的环境
- 丰富的配置,按需取用
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.1.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.poly.2.0.1.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.order.2.0.1.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.trad.2.0.1.min.js"></script>
4 使用
4.1 webpack、babel 等浏览器环境
npm 安装好几个库之后:
import cnchar from 'cnchar';
import 'cnchar-poly';
import 'cnchar-order';
import 'cnchar-trad';
console.log('汉字'.spell());
console.log(cnchar.spell('汉字'));
浏览器环境下会在 window
对象上定义 cnchar
对象
4.2 nodejs 等非浏览器环境
非浏览器环境下需要使用 cnchar.use()
方法加载功能库:
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());
console.log(cnchar.spell('汉字'));
其他使用方式与浏览器环境一致
4.3 原生浏览器环境
原生浏览器环境就需要使用 script 标签引入js文件:
<script src="https://www.theajack.com/cnchar/dist/cnchar.2.0.1.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.poly.2.0.1.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.order.2.0.1.min.js"></script>
<script src="https://www.theajack.com/cnchar/dist/cnchar.trad.2.0.1.min.js"></script>
<script>
console.log('汉字'.spell());
console.log(cnchar.spell('汉字'));
</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]);
string.convert(to[,from])
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等)中是必须的,使用如下:
var cnchar = require('cnchar');
var poly = require('cnchar-poly');
var order = require('cnchar-order');
var trad = require('cnchar-trad');
cnchar.use(poly, order, trad);
在浏览器环境中则无需调用:
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;
5.3.5 .plugins
当前使用的功能库列表,最多的情况为 ["order", "trad", "poly"]
var plugins = cnchar.plugins;
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("up")
"测试".spell("low")
"测试".spell("first")
"测试".spell("first","low")
"测试".spell("array")
"测试".spell("array","first","low")
"测试".spell('tone')
"长大了".spell('poly')
"测".stroke()
"测试".stroke()
"测试".stroke('array')
备注:
- string.spell(..arg)方法等价于
cnchar.spell(string,...args)
- string.stroke(..arg)方法等价于
cnchar.stroke(string,...args)
- spell 方法 非中文字符会返回原字符
- stroke 方法 非中文字符会笔画数会计为 0
- stroke 方法 order模式 非中文字符会返回 undefined
6.3.2 cnchar-poly 库功能
该库用于准确识别多音词,同样支持 6.3.1中的其他参数功能
"长大了".spell()
"长大了".spell('array')
"长大了".spell('poly')
"长大了".spell('poly','origin')
6.3.3 cnchar-order 库功能
该库用于查询汉字笔画顺序、笔画名称等,返回值为 数组
"一个".stroke('order')
"一个".stroke('order','detail')
"一个".stroke('order','shape')
"一个".stroke('order','name')
"一个".stroke('order','count')
6.3.4 cnchar-trad 库功能
该库用于支持繁体字火星文转换及其拼音笔画数功能
6.3.4.1 conver 方法
"一个人".convert('trad')
"一个人".convert('spark')
"一个人".convert('trad','simple')
"壹個人".convert('simple')
"壹個人".convert('spark')
"一个人".convertSimpleToTrad();
"一个人".convertSimpleToSpark();
"壹個人".convertTradToSimple();
"壹個人".convertTradToSpark();
"①個亾".convertSparkToSimple();
"①個亾".convertSparkToTrad();
"一个人".convertToTrad();
"壹個人".convertToSimple();
"一个人".convertToSpark();
6.3.4.1 spell 和 stroke 方法
该库增加了对于繁体字的拼音笔画功能扩展,其他基础用法与 基础库一致:
"長大".spell()
"長大".spell('simple')
"長大".stroke('array')
"長大".stroke('array','simple')
"長大".stroke('order','shape')
"長大".stroke('order','shape','simple')
7 应用例子
汉字打字游戏