cnchar-types
Advanced tools
English | 在线试用/文档 | 备用文档地址 | 更新日志 | 应用:打字游戏、打字钢琴 | 反馈错误/缺漏 | Gitee | QQ Group: 958278438
感谢同学们对于 cnchar 的支持，由于 cnchar 词库来源于网络，虽然经过了本人的修改和扩充，但是还是难免有错误与缺漏之处，希望大家可以将使用中发现的错误与缺漏之处 反馈 给我（或自行修改提交，经过审查无误过后会合到 cnchar 中）
关于该文档
由于文档较长，做一下简介，请按照需要阅读
使用 npm 安装：
npm i cnchar
import cnchar from 'cnchar';
'汉字'.spell();
'汉字'.stroke();
使用 script 标签使用：
<script src="https://cdn.jsdelivr.net/npm/cnchar/cnchar.min.js"></script>
<script>
'汉字'.spell();
'汉字'.stroke();
</script>
考虑到不同的需求，cnchar 的功能被拆分到以下七个库中，方便开发者按需取用：
| 名称 | 描述 | 功能 | 支持版本 |
|---|---|---|---|
| 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+ |
安装基础库：
npm i cnchar
安装附加功能库：
npm i cnchar-poly cnchar-order cnchar-trad cnchar-draw cnchar-idiom cnchar-xhy cnchar-radical
当然您也可以按需安装其中的几个，但是 cnchar 这个基础库是必须安装的（draw、idiom、xhy、radical四个库可以独立使用）
或者您可以通过安装cnchar-all来使用完整功能，这个库引用了上面的所有插件库
npm i cnchar-all
<script src="https://cdn.jsdelivr.net/npm/cnchar/cnchar.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-poly/cnchar.poly.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-order/cnchar.order.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-trad/cnchar.trad.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-idiom/cnchar.idiom.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-xhy/cnchar.xhy.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-radical/cnchar.radical.min.js"></script>
或使用以下cdn，包含了以上七个库
<script src="https://cdn.jsdelivr.net/npm/cnchar-all/cnchar.all.min.js"></script>
npm 安装好几个库之后：
// 请保证最先引入 cnchar 基础库，其他几个库顺序无所谓
import cnchar from 'cnchar';
import 'cnchar-poly';
import 'cnchar-order';
import 'cnchar-trad';
import 'cnchar-draw';
import 'cnchar-idiom';
import 'cnchar-xhy';
import 'cnchar-radical';
// 插件请按需取用
console.log('汉字'.spell()); // prototype 方式调用
console.log(cnchar.spell('汉字')); // cnchar api 调用
浏览器环境下会在 window 对象上定义 cnchar 对象
非浏览器环境下需要使用 cnchar.use() 方法加载功能库：
// 请保证最先引入 cnchar 基础库，其他几个库顺序无所谓
var cnchar = require('cnchar');
var poly = require('cnchar-poly');
var order = require('cnchar-order');
var trad = require('cnchar-trad');
var idiom = require('cnchar-idiom');
var xhy = require('cnchar-xhy');
var radical = require('cnchar-radical');
// 插件请按需取用
// 注：cnchar-draw 在非浏览器环境下不可使用
cnchar.use(poly, order, trad, idiom, xhy, radical);
console.log('汉字'.spell()); // prototype 方式调用
console.log(cnchar.spell('汉字')); // cnchar api 调用
其他使用方式与浏览器环境一致
原生浏览器环境就需要使用 script 标签引入 js 文件：
<script src="https://cdn.jsdelivr.net/npm/cnchar/cnchar.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-poly/cnchar.poly.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-order/cnchar.order.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-trad/cnchar.trad.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-draw/cnchar.draw.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-idiom/cnchar.idiom.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-xhy/cnchar.xhy.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/cnchar-radical/cnchar.radical.min.js"></script>
<script>
console.log('汉字'.spell()); // prototype 方式调用
console.log(cnchar.spell('汉字')); // cnchar api 调用
</script>
类型声明：cnchar.d.ts | cnchar-order.d.ts | cnchar-trad.d.ts
注：该章节仅介绍API用法，更多使用实例请参考第六章
为了尽可能使 api 使用简单，该库设计了两个主要的非常简洁的 api，并保证调用方式一致：
// 获取汉字的拼音、多音词、音调等都集成在以下方法上
cnchar.spell(string[,...args]);
// 或
string.spell([...args])
// 获取汉字的笔画、笔画顺序等都集成在以下方法上
cnchar.stroke(string[,...args]);
// 或
string.stroke([...args])
该 api 设计一致，string 表示要处理的汉字字符串
关键在于可选参数的配置，参数配置将在第六章单独介绍
类型声明：cnchar.draw.d.ts
cnchar-draw 库用于支持在浏览器环境下可视化绘制汉字，所以该库仅在浏览器环境下可用。绘制模式有 normal,animation,stroke,test 四种模式可选。
使用方式如下：
cnchar.draw('你好', options); // options 为可选参数， 在5.2.2 种会详细介绍
运行结果如下：
该库支持脱离cnchar 独立使用
import draw from 'cnchar-draw';
draw('你好')
使用cdn引用时，会在window对向上暴露 CncharDraw 对象
draw 的参数比较繁多，首先需要理解的是，draw 分为四种绘制模式：
以下是 options 的所有可选参数及描述，使用详情请参考在线文档：
declare interface DrawOption {
el?: string | HTMLElement; // 绘制的容器，支持选择器或dom，若是不填，会在body后append一个dom作为容器
type?: DrawType; // 绘制模式，默认为normal
clear?: boolean; // 绘制前是否清空容器 默认为true
style?: { // 样式类
backgroundColor?: string, // 默认为#fff
showOutline?: boolean;//: true,
showCharacter?: boolean;//: true,
currentColor?: string;//: '#b44', // 仅在stroke模式下有效
length?: number;//: 60,
padding?: number;//: 5, // 数值, 默认 20。 画布的汉字和边缘之间的填充
outlineColor?: string;//: '#ddd', // 十六进制字符, 默认 '#DDD'。
strokeColor?: string;//: '#555', // 十六进制字符, 默认 '#555'。绘制每个笔划的颜色。
radicalColor?: string;//: null, // 十六进制字符, 默认 null。 如果存在偏旁部首数据，则在笔划中绘制偏旁部首的颜色。 如果没有设置，激光将绘制与其他笔划相同的颜色。
strokeFadeDuration?: number; //400
},
line?: { // 背景线条类
lineStraight?: boolean;// : true,
lineCross?: boolean;// : true,
lineWidth?: number;// : 1,
lineColor?: string;// : '#ddd',
lineDash?: boolean;// : true,
border?: boolean;// : true,
borderWidth?: number;// : 1,
borderColor?: string;// : '#ccc',
borderDash?: boolean;// : false,
},
animation?: {
strokeAnimationSpeed?: number;// : 1, // 数值, 默认 1。 绘制每个笔划的速度必须大于0。增加此数字可以更快地绘制笔划，减少绘制笔划的速度更慢。
delayBetweenStrokes?: number;// : 1000, // 数值, 默认 1000。 动画进行中每个笔画之间的间隔时间（以毫秒为单位）。
delayBetweenLoops?: number;// : 200, // 数值, 默认 2000。 循环动画时每个动画循环之间的时间（以毫秒为单位）。
autoAnimate?: boolean;// : true,
animateComplete?: Function;// : () => {},
stepByStep?: boolean;// : true,
loopAnimate?: boolean;// : false,
},
test?: {
strokeHighlightSpeed?: number;// : 20, // 数值, 默认 20。 在测验中给出提示时突出显示每个笔划的速度必须大于0。增加此数字以突出显示更快，减少以突出显示更慢。
highlightColor?: number;// : '#aaf', // 十六进制字符, 默认 '#AAF'。 用于在测验中突出显示的颜色。
drawingColor?: number;// : '#333', // 十六进制字符, 默认 '#333'。 测验期间绘制的线条颜色。
drawingWidth?: number;// : 4, // 数值, 默认 4。 进行测验时绘制的线条宽度。
showHintAfterMisses?: number;// : 3, // 整数, 默认 3 中风高亮提示之前的未命中数被给予用户。 设置为 false 以禁用。 创建测验时也可以设置此项。
highlightOnComplete?: number;// : true, // 布尔值, 默认 true。 控制当用户完成绘制整个字符时，测验是否会短暂突出显示字符。 创建测验时也可以设置此项。
highlightCompleteColor?: number;// : null, // 十六进制字符, 默认 null。 在测验中突出显示字符时使用的颜色。 如果未设置，则将使用highlightColor。 仅当highlightOnComplete为true时才相关。
onTestStatus?(args: TestStatus):void;// : null, // ({index, status, data})=>{}
}
};
cnchar.draw 方法会返回一个 writer 对象
declare interface IWriter {
option: IDrawOption;
el: HTMLElement;
type: TDrawType;
text: Array<string>;
writers: Array<HanziWriter>;
startAnimation(): boolean;
pauseAnimation(): void;
resumeAnimation(): void;
drawNextStroke(onComplete?: ()=>void): boolean;
}
当 drawType = animation 时，以下几个api可以用户控制动画
绘制模式分为连续绘制 和 单笔画绘制，默认为连续绘制模式
单笔划绘制模式需要 option.animation.autoAnimate = false 且调用 drawNextStroke 方法
当 option.animation.autoAnimate = false 时，调用该api可以开始绘制，且开启动连续绘制模式
const writer = cnchar.draw('你好', {
type: cnchar.draw.TYPE.ANIMATION,
animation: {
autoAnimate: false,
}
});
writer.startAnimation();
当处于 连续绘制模式 时，调用这两个api可以暂停绘制和恢复绘制
const writer = cnchar.draw('你好', {
type: cnchar.draw.TYPE.ANIMATION
});
writer.pauseAnimation();
writer.resumeAnimation();
该 api 用于开启 单笔绘制模式
首先需要使用参数 option.animation.autoAnimate = false
const writer = cnchar.draw('你好', {
type: cnchar.draw.TYPE.ANIMATION,
animation: {
autoAnimate: false,
}
});
writer.drawNextStroke(()=>{
// 当前笔画绘制完成的回调
});
该库由 HanziWriter 驱动，目前仅支持在web环境下使用，如需微信小程序使用请参考 HanziWriter API
当引入 cnchar-trad 之后，cnchar 就具备了繁体、简体、火星文互转功能，使用 cnchar.convert 对象上的方法，你就可以使用这个功能
自从 v2.0.4 以后，cnchar 保留以下方法可供使用：
cnchar.convert.simpleToTrad(string); // 简体 => 繁体
cnchar.convert.simpleToSpark(string); // 简体 => 火星文
cnchar.convert.tradToSimple(string); // 繁体 => 简体
cnchar.convert.tradToSpark(string); // 繁体 => 火星文
cnchar.convert.sparkToSimple(string); // 火星文 => 简体
cnchar.convert.sparkToTrad(string); // 火星文 => 繁体
string.convertSimpleToTrad();
string.convertSimpleToSpark();
string.convertTradToSimple();
string.convertTradToSpark();
string.convertSparkToSimple();
string.convertSparkToTrad();
当引入 cnchar-order 功能库(版本 2.0.2 及以上)之后，cnchar 就支持了根据笔画名称序列推出原汉字的功能，使用方式如下：
cnchar.orderToWord(orderNames[,...args]);
orderNames 是笔画名称序列
args 是参数列表，可选值有 ['match','matchorder','contain','start','array','simple'], 使用 cnchar.type.orderToWord 可以查看可选值。 参数详细使用方法请参见第六章 orderToWord 参数
orderNames 可以是空格分隔的笔画名称字符串或笔画名称数组，可用的笔画名称可以通过以下 api 查看
var dict = cnchar.orderToWord.orders; // dict 是一个包含所有笔画数的详细信息的json数据
笔画详细信息的如下，orderNames 只需要传入笔画名称即可，也就是下面 json 数据的 key 值
{
卧钩: {shape: "㇃", letter: "y", sameLetterTo: "斜钩"}
弯钩: {shape: "㇁", letter: "t"}
捺: {shape: "㇏", letter: "l"}
提: {shape: "㇀", letter: "i"}
撇: {shape: "丿", letter: "s"}
撇折: {shape: "𠃋", letter: "n"}
撇点: {shape: "𡿨", letter: "m"}
斜钩: {shape: "㇂", letter: "y", sameLetterTo: "卧钩"}
横: {shape: "一", letter: "j"}
横折: {shape: "𠃍", letter: "c"}
横折弯: {shape: "㇍", letter: "v", sameLetterTo: "横折折"}
横折折: {shape: "㇅", letter: "v", sameLetterTo: "横折弯"}
横折折折: {shape: "㇎", letter: "q"}
横折折折钩: {shape: "𠄎", letter: "w", sameLetterTo: "横撇弯钩"}
横折折撇: {shape: "㇋", letter: "a"}
横折提: {shape: "㇊", letter: "p"}
横折钩: {shape: "𠃌", letter: "r"}
横撇: {shape: "㇇", letter: "e", sameLetterTo: "横钩"}
横撇弯钩: {shape: "㇌", letter: "w", sameLetterTo: "横折折折钩"}
横斜钩: {shape: "⺄", letter: "o"}
横钩: {shape: "乛", letter: "e", sameLetterTo: "横撇"}
点: {shape: "丶", letter: "k"}
点2: {shape: "㇀", letter: "d"}
竖: {shape: "丨", letter: "f"}
竖弯: {shape: "㇄", letter: "b"}
竖弯钩: {shape: "乚", letter: "u"}
竖折折: {shape: "𠃑", letter: "x", sameLetterTo: "竖折撇"}
竖折折钩: {shape: "㇉", letter: "z"}
竖折撇: {shape: "ㄣ", letter: "x", sameLetterTo: "竖折折"}
竖提: {shape: "𠄌", letter: "h"}
竖钩: {shape: "亅", letter: "g"}
}
| 名称 | 定义 | 形状 |
|---|---|---|
| 横折折撇 | a | ㇋ |
| 竖弯 | b | ㇄ |
| 横折 | c | 𠃍 |
| 点2 | d | ㇀ |
| 横斜钩 | o | ⺄ |
| 横 | j | 一 |
| 捺 | l | ㇏ |
| 横折钩 | r | 𠃌 |
| 竖 | f | 丨 |
| 竖钩 | g | 亅 |
| 点 | k | 丶 |
| 撇 | s | 丿 |
| 撇折 | n | 𠃋 |
| 竖折撇/竖折折 | x | ㄣ |
| 横折折折钩/横撇弯钩 | w | 𠄎 |
| 竖折折钩 | z | ㇉ |
| 提 | i | ㇀ |
| 弯钩 | t | ㇁ |
| 斜钩/卧钩 | y | ㇂ |
| 横折折/横折弯 | v | ㇅ |
| 横撇/横钩 | e | ㇇ |
| 横折提 | p | ㇊ |
| 横折折折 | q | ㇎ |
| 竖提 | h | 𠄌 |
| 撇点 | m | 𡿨 |
| 竖弯钩 | u | 乚 |
注：其中以下五对笔画没有进行区分，使用的是同样的字母表示： 卧钩 = 斜钩、横折弯 = 横折折、横折折折钩 = 横撇弯钩、横撇 = 横钩、竖折折 = 竖折撇
以下是一个例子：
cnchar.orderToWord(['横', '撇', '捺']);
// 等价于
cnchar.orderToWord('横 撇 捺');
// 返回 "丈大"
cnchar.orderToWord(['横', '撇', '捺'], 'array');
// 返回 ["丈","大"]
cnchar.orderToWord(['横', '撇', '捺'], 'start');
// 返回 "丈大太*夯夸夺夼奁奄奈奋奔态奎耷套奢瓠鹩奪奮遼"
cnchar.orderToWord(['横', '撇', '捺'], 'start', 'simple');
// 返回 "丈大太*夯夸夺夼奁奄奈奋奔态奎耷套奢瓠鹩"
如果输入的笔画不在 cnchar.orderToWord.orders 内，则该方法会打印一个错误提示哪些笔画有误，并返回一个空数组。
spellToWord 方法用于根据拼音查询符合要求的汉字，用法如下：
cnchar.spellToWord(spell[,...args]);
例子：
cnchar.spellToWord('shàng'); // 返回 '上尚绱鞝'
cnchar.spellToWord('shàng', 'alltone'); // 返回 '上伤汤尚垧殇晌商绱觞赏墒熵裳傷湯殤鞝觴賞'
cnchar.spellToWord('shang4', 'alltone', 'trad'); // 返回 '傷湯殤鞝觴賞'
cnchar.spellToWord('lv2', 'simple'); // 返回 '驴闾榈'
注：
spell 表示拼音，可以使用音调字母或音调数标方式：
例：shàng 等价于 shang4
ü 可以使用 v 表示，例：lü 等价于 lv
strokeToWord 方法用于根据笔画数查询符合要求的汉字，用法如下：
cnchar.strokeToWord(strokeCount[,...args]);
例子：
cnchar.strokeToWord(25); // 返回 '鬣馕囔戆攮纛饞躥顱籮蠻廳灣鑲鑰'
cnchar.strokeToWord(25, 'simple'); // 返回 '鬣馕囔戆攮纛'
cnchar.strokeToWord(1, 'array'); // 返回 ['一', '乙']
cnchar在2.2.0加入了成语功能，启用该功能需要安装 cnchar-idiom 功能库，该库可以独立于cnchar主库运行
使用方式如下：
cnchar.idiom(text:string, ...idiomArgs: Array<idiomArg>):Array<string>;
看一个具体例子
// 根据汉字查询成语，末尾的空格可以省略
cnchar.idiom(['五', '', '十', '']); // ['五风十雨', '五光十色']
// 根据笔画数查询成语，0表示匹配任意笔画，末尾的0可以省略
cnchar.idiom([4, 6, 2, 0], 'stroke'); // ["不当人子", ... ]
// 根据拼音查询成语
cnchar.idiom('shang', 'spell'); // ["伤风败化", "伤风败俗", ...]
// 带音调
cnchar.idiom('shang4', 'spell', 'tone'); // ["上兵伐谋", "上不着天，下不着地", ... ]
使用cdn引用时，会在window对向上暴露 CncharIdiom 对象
cnchar在2.2.0加入了歇后语功能，启用该功能需要安装 cnchar-xhy 功能库，该库可以独立于cnchar主库运行
使用方式如下：
cnchar.xhy(text:string, ...xhyArgs: Array<xhyArg>):Array<string>;
看一个具体例子
// 精确查询
cnchar.xhy('大水冲了龙王庙'); // ['大水冲了龙王庙-自家人不识自家人', '大水冲了龙王庙-一家人不认一家人'],
// 模糊查询
cnchar.xhy('大水', 'fuzzy'); // ['江河里长大水-泥沙俱下', '江河发大水-后浪推前浪', ... ]
// 只返回答案结果
cnchar.xhy('大水', 'fuzzy', 'answer'); // ['泥沙俱下', '后浪推前浪', ... ]
// 根据歇后语后一句查询
cnchar.xhy('上晃下摇', 'fuzzy', 'answer', 'second'); // ['醉汉过铁索桥', '扶着醉汉过破桥']
使用cdn引用时，会在window对向上暴露 CncharXHY 对象
cnchar在 2.2.5 加入了偏旁部首功能，启用该功能需要安装 cnchar-radical 功能库，该库可以独立于cnchar主库运行
感谢 kewell-tsao 提供的 pr
使用方式如下：
cnchar.radical(text:string | Array<string>, ...radicalArgs: Array<radicalArg>): string | Array<string>;
看一个具体例子
cnchar.radical('你'); // "亻",
cnchar.radical('你好呀'); // "亻女口"
// 返回数组
cnchar.radical('你好呀', 'array'); // ["亻", "女", "口"]
// 传入数组会默认返回数组
cnchar.radical(["你", "好", "呀"]); // ["亻", "女", "口"]
使用cdn引用时，会在window对向上暴露 CncharRadical 对象
cnchar 将库内部使用的一些操作拼音和汉字的方法整理暴露出来，方便开发者便捷高效的操作拼音和汉字
spellInfo 方法用于查询拼音的详细信息，用法如下：
cnchar.spellInfo(spell);
例子：
cnchar.spellInfo('Shàng');
/*
// 返回值与含义如下
{
spell: 'shang', // 无音调拼音
initial: 'sh', // 声母
final: 'ang', // 韵母
tone: 4, // 音调
index: 3 // 音调位置
},
*/
除此之外，spellInfo 上含有 initials 和 tones 两个属性，分别表示，所有可用的声母和音调：
cnchar.spellInfo.initials;
// ['b', 'p', 'm', 'f', 'd', 't', 'n', 'l', 'g', 'k', 'h', 'j', 'q', 'x', 'zh', 'ch', 'sh', 'r', 'z', 'c', 's', 'y', 'w']
cnchar.spellInfo.tones;
// ['ā', 'á', 'ǎ', 'à', 'ō', 'ó', 'ǒ', 'ò', 'ē', 'é', 'ě', 'è', 'ī', 'í', 'ǐ', 'ì', 'ū', 'ú', 'ǔ', 'ù', 'ǖ', 'ǘ', 'ǚ', 'ǜ', '*', 'ń', 'ň', 'ǹ']
// n 的一声使用 * 代替
transformTone 方法用于将有音调拼音转换为无音调拼音，且可以获取音调位置和声调
使用方式如下：
cnchar.transformTone(spell: string, tone?: boolean, type?: 'low' | 'up');
/* 返回值
{
spell: string; // 转换后的拼音
tone: toneType; // 声调
index: number; // 音调位置
isTrans: boolean; // 是否是经过转换的比如 lv2 -> lǘ
}
*/
tone 为可选参数，表示返回值spell是否需要带上声调，默认为 false
type 为可选参数，表示返回值spell设置大小写，默认为 'low'
transformTone spell参数 支持使用 v 代替 ü，支持使用末尾带数字表示声调，比如 lv 等价于 lü shang4 等价于 shàng
isCnChar 方法用于判断一个字符是否是汉字
cnchar.isCnChar(word: string): boolean;
isPolyWord 方法用于判断一个字符是否是汉字
cnchar.isPolyWord(word: string): boolean;
compareSpell 方法用于按照拼音比较拼音或汉字的大小，可用于通讯录姓名拼音排序等场景
该方法支持按照拼音和声调比较，如需排序可以参考 sortSpell 方法
cnchar.compareSpell(spell1: string, spell2: string, tone?: boolean);
tone参数表示是否需要按照音调比较，默认为false
该方法返回一个字符串，'more', 'less', 'even' 分别表示 spell1 大于、小于、等于 spell2
例
cnchar.compareSpell('ao', 'ai') // 返回 'more' 因为 o 排在 i 之后
cnchar.compareSpell('奥', 'ai') // 返回 'more'
compareStroke 方法用于按照笔画数比较汉字大小，可用于按照姓名首个汉字笔画排序等场景，排序可以参考 sortStroke 方法
cnchar.compareStroke(stroke1: string, stroke2: string);
该方法支持输入汉字或数字，汉字可以输入多个
该方法返回一个字符串，'more', 'less', 'even' 分别表示 stroke1 大于、小于、等于 stroke2
例子：
cnchar.compareStroke('你', '好') // 返回 'more'
cnchar.compareStroke(20, '好') // 返回 'more'
cnchar.compareStroke('一个', '好') // 返回 'less'
sortSpell 方法用于按照拼音排序汉字或拼音，支持输入数组或字符串，支持按照声调排序、支持倒序
cnchar.sortSpell(spells:Array<string> | string, ...args?: Array<'tone'|'desc'>): Array<string> | string;
spells参数可以是数组或字符串
当为数组时，数组元素可以时汉字或拼音，返回的是数组
当为字符串时，字符串必须全部是汉字，返回的是字符串
该方法可选参数有两个，'tone' 表示按照音调排序，'desc' 表示倒序，默认不区分声调且升序。请看一些例子
cnchar.sortSpell(['你', '好', '吗']) // ['好', '吗', '你']
cnchar.sortSpell('你好吗') // '好吗你'
cnchar.sortSpell('拼品频爱', 'tone', 'desc') // '品频拼爱'
sortStroke 方法用于按照笔画数排序汉字
cnchar.sortStroke(strokes:Array<string|number> | string, desc?: 'desc'): Array<string> | string;
strokes参数可以是数组或字符串
当为数组时，数组元素可以时汉字或数字，返回的是数组
当为字符串时，字符串必须全部是汉字，返回的是字符串
该方法有一个可选参数，'desc' 表示倒序，默认升序。请看一些例子
cnchar.sortStroke(['一', '三', '二']) // ['一', '二', '三']
cnchar.sortStroke(['一', '三', 2]) // ['一', 2, '三'],
cnchar.sortStroke('一三二', 'desc') // '三二一'
shapeSpell 将数字表示的声调转为拼音声调
如 lv2 会被转换成 lǘ，ta1 会被转换成 tā， 方便用户输入
cnchar.shapeSpell(spell: string): string;
由于 cnchar 数据来源于网络，虽然经过了大量修改，但是还是难免会有错漏
所以 cnchar 提供了修改默认数据的api，方便开发者修改与添加数据
设置拼音数据
cnchar.setSpell(word: string, spell: string): void;
cnchar.setSpell(json: {[key: string]: string}): void;
设置多音字的默认读音
cnchar.setSpellDefault(word: string, spell: string): void;
cnchar.setSpellDefault(json: {[key: string]: string}): void;
设置汉字笔画数
cnchar.setStrokeCount(word: string, count: number): void;
cnchar.setStrokeCount(json: {[key: string]: number}): void;
设置多音词的读音， 依赖 cnchar-poly 库
cnchar.setPolyPhrase(word: string, spell: string): void;
cnchar.setPolyPhrase(json: {[key: string]: string}): void;
设置汉字笔顺， 依赖 cnchar-order 库
添加的笔顺必须是字母，详情对应关系参见 stroke-table
cnchar.setOrder(word: string, order: string): void;
cnchar.setOrder(json: {[key: string]: string}): void;
设置汉字偏旁部首， 依赖 cnchar-radical 库
cnchar.radical.setRadical(word: string, radical: string): void;
cnchar.radical.setRadical(json: {[key: string]: string}): void;
添加歇后语， 依赖 cnchar-xhy 库
cnchar.xhy.addXhy(args: Array<Array<string> | string>): void;
cnchar.xhy.addXhy(xhyHead: string, xhyTail: string): void;
这个 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';
type 对象用户获取当前可用的 spell 、 stroke 、 orderToWord 、spellToWord、strokeToWord、idiom、 xhy、radical 参数类型：
var spellArg = cnchar.type.spell;
var strokeArg = cnchar.type.stroke;
var orderToWordArg = cnchar.type.orderToWord;
var spellToWordArg = cnchar.type.spellToWord;
var strokeToWordArg = cnchar.type.strokeToWord;
var idiomArg = cnchar.type.idiom;
var xhyArg = cnchar.type.xhy;
var radicalArg = cnchar.type.radical;
spellArg 最多可用值： ['array', 'low', 'up', 'first', 'poly', 'tone', 'simple']
strokeArg 最多可用值：['letter', 'shape', 'count', 'name', 'detail', 'array', 'order', 'simple']
orderToWordArg 最多可用值： ['match','matchorder','contain','start','array','simple']
spellToWordArg 最多可用值： ['simple','trad','poly','alltone','array']
strokeToWordArg 最多可用值： ['simple','trad','array']
idiomArg 最多可用值： ['char','stroke','spell','tone']
xhyArg 最多可用值： ['fuzzy','answer','second']
radicalArg 最多可用值： ['array']
以上值皆为 json
具体用法第六章讲到
该值是一个 布尔类型，用于控制是否开启参数校验，默认值为 true
参数校验能够对 spell 和 stroke 传入的参数进行检查，在控制台显示 无效·，忽略和冗余的参数
cnchar.check = false; // 关闭参数校验
获取当前版本：
var version = cnchar.version; // string 类型
当前使用的功能库列表，最多的情况为 ["order", "trad", "poly"]
var plugins = cnchar.plugins; // array 类型
参数调用如下，所有 arg 参数都是可选的
cnchar.spell(string,arg1,arg2,...);
string.spell(arg1,arg2,...)
arg 参数信息如下：
| 参数 | 作用 | 是否默认 | 依赖库 | 备注 |
|---|---|---|---|---|
| array | 返回数组 | 否 | -- | -- |
| first | 返回拼音首字母 | 否 | -- | -- |
| up | 将结果全部大写 | 否 | -- | -- |
| low | 将结果全部小写 | 否 | -- | 会被 up 参数覆盖 |
| poly | 使用候选多音字 | 否 | -- | -- |
| tone | 启用音调 | 否 | -- | -- |
| simple | 是否禁用繁体字的拼音功能 | 否 | cnchar-trad | 使用 cnchar-trad 之后，默认对繁体字拼音进行转换，该参数用于禁用繁体字拼音 |
参数调用如下，所有 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 之后，默认对繁体字启用笔画功能，该参数用于禁用繁体字笔画功能 |
参数调用如下，所有 arg 参数都是可选的
cnchar.orderToWord(orders,arg1,arg2,...);
arg 参数信息如下：
| 参数 | 作用 | 是否默认 | 依赖库 | 备注 |
|---|---|---|---|---|
| match | 匹配含有笔序中所有笔画的汉字 | 否 | -- | -- |
| matchorder | 匹配含有笔序中所有笔画的汉字前先后顺序一致 | 否 | -- | -- |
| contain | 匹配含有该笔序的汉字 | 否 | -- | -- |
| start | 匹配所有以该笔序开头的汉字 | 否 | -- | -- |
| array | 返回符合条件的数组，默认返回的是字符串 | 否 | -- | -- |
| simple | 禁用繁体字 | 否 | cnchar-trad | 该参数仅在引入了 cnchar-trad 后有效 |
关于匹配参数，优先级为 match > matchorder > contain > start > 默认
不含有匹配参数时表示使用全匹配，即汉字笔画数与传入的 orders 完全一致
参数调用如下，所有 arg 参数都是可选的
cnchar.spellToWord(spell,arg1,arg2,...);
spell 表示拼音，可以使用音调字母或音调数标方式：
例：shàng 等价于 shang4
ü 可以使用 v 表示，例：lü 等价于 lv
arg 参数信息如下：
| 参数 | 作用 | 是否默认 | 依赖库 | 备注 |
|---|---|---|---|---|
| simple | 仅匹配简体字 | 否 | -- | -- |
| trad | 仅匹配繁体字 | 否 | cnchar-trad | 该参数仅在引入了 cnchar-trad 后有效 |
| poly | 仅匹配多音字 | 否 | -- | -- |
| alltone | 匹配该拼音所有音调的汉字 | 否 | -- | 没有音调的拼音表示轻声 |
| array | 返回符合条件的数组，默认返回的是字符串 | 否 | -- | -- |
注：simple与trad参数若是都不存在，则当引入cnchar-trad时会同时匹配繁简体，没有引入cnchar-trad时则只匹配简体
参数调用如下，count表示笔画数，所有 arg 参数都是可选的
cnchar.strokeToWord(count,arg1,arg2,...);
| 参数 | 作用 | 是否默认 | 依赖库 | 备注 |
|---|---|---|---|---|
| simple | 仅匹配简体字 | 否 | -- | -- |
| trad | 仅匹配繁体字 | 否 | cnchar-trad | 该参数仅在引入了 cnchar-trad 后有效 |
| array | 返回符合条件的数组，默认返回的是字符串 | 否 | -- | -- |
注：simple与trad参数若是都不存在，则当引入cnchar-trad时会同时匹配繁简体，没有引入cnchar-trad时则只匹配简体
参数调用如下，value表示查询对象，可以试拼音汉字笔画数，所有 arg 参数都是可选的
cnchar.idiom(value,arg1,arg2,...);
| 参数 | 作用 | 是否默认 | 依赖库 | 备注 |
|---|---|---|---|---|
| char | 根据汉字查询成语 | 是 | -- | 默认值无需调用 |
| stroke | 根据笔画数查询成语 | 否 | -- | 优先级高于char |
| spell | 根据拼音查询成语 | 否 | -- | 优先级高于stroke |
| tone | 启用拼音音调查询 | 否 | -- | 仅在spell模式下生效 |
注：优先级 spell > stroke > char
参数调用如下，value表示歇后语查询对象，可以是歇后语的第一句或第二句，所有 arg 参数都是可选的
cnchar.xhy(value,arg1,arg2,...);
| 参数 | 作用 | 是否默认 | 依赖库 | 备注 |
|---|---|---|---|---|
| fuzzy | 是否支持模糊查询 | 否 | -- | 是否包含输入的字符串 |
| answer | 是否只输出答案 | 否 | -- | 默认是输出整句歇后语 |
| second | 是否是根据歇后语后一句查询 | 否 | -- | -- |
参数调用如下，value表示需要查询偏旁的汉字，可以是字符串或数组
cnchar.radical(value,arg1,arg2,...);
| 参数 | 作用 | 是否默认 | 依赖库 | 备注 |
|---|---|---|---|---|
| array | 是否返回数组 | 否 | -- | 当传入为数组时默认返回数组 |
npm 方式
npm i cnchar
import cnchar from 'cnchar';
// do something
script 标签引用 方式
<script src="https://cdn.jsdelivr.net/gh/theajack/cnchar/dist/cnchar.latest.min.js"></script>
<script>
// do something
</script>
//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]
//spellToWord 功能
cnchar.spellToWord('shàng'); // 返回 "上尚绱"
cnchar.spellToWord('lv2'); // 返回 "驴闾榈"
//strokeToWord 功能
cnchar.strokeToWord(2); // 返回 "丁七乃乜九了二人亻儿入八冂几凵刀刁力勹"
备注：
cnchar.spell(string,...args)cnchar.stroke(string,...args)该库用于准确识别多音词，同样支持 6.3.1 中的其他参数功能
'长大了'.spell(); // 返回 'ZhangDaLe'
'长大了'.spell('array'); // 返回 ["Zhang", "Da", "Le"]
'长大了'.spell('poly'); // 返回 '(Zhang|Chang)(Da|Dai)(Le|Liao)'
该库用于查询汉字笔画顺序、笔画名称等，返回值为 数组
'一个'.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]
根据笔画名称序列推出原汉字
var orders = cnchar.orderToWord.orders; //查看支持的笔画名称
cnchar.orderToWord(['横', '撇', '捺']);
// 返回 "丈大"
cnchar.orderToWord(['横', '撇', '捺'], 'array');
// 返回 ["丈","大"]
cnchar.orderToWord(['横', '撇', '捺'], 'start');
// 返回 "丈大太*夯夸夺夼奁奄奈奋奔态奎耷套奢瓠鹩奪奮遼"
cnchar.orderToWord(['横', '撇', '捺'], 'start', 'simple');
// 返回 "丈大太*夯夸夺夼奁奄奈奋奔态奎耷套奢瓠鹩"
cnchar.orderToWord(['横', '撇', '捺'], 'match');
// 返回 "丈大仄兮友天太夫夭尺攵文木犬长丛仗仝叭..." // 省略后面的
cnchar.orderToWord(['横', '撇', '捺'], 'matchorder');
// 返回 "丈大仄友天太夫夭尺攵文木犬仗叭史央夯失..." // 省略后面的
cnchar.orderToWord(['横', '撇', '捺'], 'contain');
// 返回 "丈大天太夫夭尺攵文犬仗叭史央夯失疋矢乔..." // 省略后面的
该库用于支持繁体字火星文转换及为拼音笔画数等基本功能提供繁体字支持
'一个人'.convertSimpleToTrad(); // 返回 "壹個人" 等价于 cnchar.convert.simpleToTrad
cnchar.convert.simpleToTrad('一个人');
'一个人'.convertSimpleToSpark(); // 返回 "①个亾" 等价于 cnchar.convert.simpleToSpark
cnchar.convert.simpleToSpark('一个人');
'壹個人'.convertTradToSimple(); // 返回 "一个人" 等价于 cnchar.convert.tradToSimple
cnchar.convert.tradToSimple('壹個人');
'壹個人'.convertTradToSpark(); // 返回 "①个亾" 等价于 cnchar.convert.tradToSpark
cnchar.convert.tradToSpark('壹個人');
'①个亾'.convertSparkToSimple(); // 返回 "一个人" 等价于 cnchar.convert.sparkToSimple
cnchar.convert.sparkToSimple('①个亾');
'①个亾'.convertSparkToTrad(); // 返回 "壹個人" 等价于 cnchar.convert.sparkToTrad
cnchar.convert.sparkToTrad('①个亾');
该库增加了对于繁体字的拼音笔画功能扩展，其他基础用法与 基础库一致：
//spell 功能
'長大'.spell(); // 返回 'ZhangDa'
'長大'.spell('simple'); // 返回 '長Da' // 禁用繁体字拼音功能
//stroke 功能
'長大'.stroke('array'); // 返回 [8, 3]
'長大'.stroke('array', 'simple'); // 返回 [0, 3] // 禁用繁体字笔画功能
'長大'.stroke('order', 'shape'); // 返回 [["㇐","㇑","㇐","㇐","㇐","㇙","㇓","㇏"],["㇐","㇓","㇏"]]
'長大'.stroke('order', 'shape', 'simple'); // 返回 [undefined, ["㇐","㇓","㇏"]]
该库为cnchar扩展了成语功能
cnchar.idiom(['五', '', '十', '']) // ['五风十雨', '五光十色']
cnchar.idiom([4, 6, 2, 6], 'stroke') // ['五光十色']
cnchar.idiom('shang', 'spell') // ['伤风败化', '伤风败俗', ... ]
cnchar.idiom('shang4', 'spell', 'tone') // ['伤风败化', '伤风败俗', ... ]
该库为cnchar扩展了歇后语功能
cnchar.xhy('大水冲了龙王庙') // ['大水冲了龙王庙-自家人不识自家人', '大水冲了龙王庙-一家人不认一家人']
cnchar.xhy('大水', 'fuzzy') // ['江河里长大水-泥沙俱下', '江河发大水-后浪推前浪', ... ]
cnchar.xhy('大水', 'fuzzy', 'answer') // ['泥沙俱下', '后浪推前浪', ... ]
cnchar.xhy('上晃下摇', 'fuzzy', 'answer', 'second') // ['醉汉过铁索桥', '扶着醉汉过破桥']
该库为cnchar扩展了偏旁部首功能
cnchar.radical('你'); // "亻",
cnchar.radical('你好呀'); // "亻女口"
cnchar.radical('你好呀', 'array'); // ["亻", "女", "口"]
cnchar.radical(["你", "好", "呀"]); // ["亻", "女", "口"]
cnchar提供了一些汉字工具方法，方便开发者更便捷高效地操作拼音和汉字
cnchar.spellInfo('shàng');
// 返回 {spell: "shang", tone: 4, index: 3, initial: "sh", final: "ang"}
cnchar.isCnChar('a') // false
cnchar.isCnChar('1') // false
cnchar.isCnChar('？') // false
cnchar.isCnChar('国') // true
cnchar.isCnChar('國') // true
cnchar.transformTone('lv2') // {spell: 'lü', tone: 2, index: 2, isTrans: true}
cnchar.transformTone('lv2', true) // {spell: 'lǘ', tone: 2, index: 2, isTrans: true}
cnchar.transformTone('lv2', true, 'up') // {spell: 'LǗ', tone: 2, index: 2, isTrans: true}
cnchar.transformTone('lǘ') // {spell: 'lü', tone: 2, index: 2, isTrans: false}
cnchar.compareSpell('ao', 'ai') // 'more'
cnchar.compareSpell('ai', 'ai') // 'even'
cnchar.compareSpell('pín', 'pǐn', true) // 'less'
cnchar.compareSpell('pin2', 'pǐn', true) // 'less'
cnchar.compareSpell('频', 'pǐn', true) // 'less'
cnchar.compareSpell('品', '频', true) // 'more'
cnchar.compareSpell('贫', '频', true) // 'even'
cnchar.compareStroke('你', '好') // 'more'
cnchar.compareStroke('你', '苏') // 'even'
cnchar.compareStroke('好', '苏') // 'less'
cnchar.compareStroke('一个', '好') // 'less'
cnchar.compareStroke('你', 14) // 'less'
拼音支持声调数字模式（lv2=>lǘ）
cnchar.sortSpell(['你', '好', '吗']) // ['好', '吗', '你']
cnchar.sortSpell('你好吗') // '好吗你'
cnchar.sortSpell(['拼', '品', '频', '爱'], 'tone') // ['爱', '拼', '频', '品']
cnchar.sortSpell(['拼', '品', 'pin2', 'ai'], 'tone') // ['ai', '拼', 'pin2', '品']
cnchar.sortSpell(['拼', '品', '频', '爱'], 'tone', 'desc') // ['品', '频', '拼', '爱']
cnchar.sortSpell('拼品频爱', 'tone', 'desc') // '品频拼爱'
cnchar.sortStroke(['一', '三', '二']) // ['一', '二', '三']
cnchar.sortStroke('一三二') // '一二三'
cnchar.sortStroke(['一', '三', 2]) // ['一', 2, '三']
cnchar.sortStroke(['一', '三', '二'], 'desc') // ['三', '二', '一']
cnchar.isPolyWord('中') // true
cnchar.isPolyWord('国') // false
cnchar.shapeSpell('lv2') // lǘ
cnchar.shapeSpell('shang4') // shàng
拼音支持声调数字模式（lv2=>lǘ）
// 用于添加cnchar中不包含的汉字 或修改 cnchar中有误的汉字
cnchar.setSpell('x', 'x');
cnchar.setSpell('x', ['x1', 'x2']); // 多个读音
cnchar.setSpell({ // 多个汉字
'x': 'x',
'y': ['y1', 'y2']
});
拼音支持声调数字模式（lv2=>lǘ）
// 用于设置或修改 cnchar 中多音字的默认读音
cnchar.setSpellDefault('长', 'zhǎng');
cnchar.setSpellDefault({ // 多个汉字
'长': 'zhǎng',
'中': 'zhòng'
});
// 用于添加cnchar中不包含的汉字 或修改 cnchar中有误的汉字
cnchar.setStrokeCount('大', 3);
cnchar.setStrokeCount({ // 多个
'大': 3,
'子': 3
});
依赖 cnchar-order
添加的笔顺必须是字母，详情对应关系参见 stroke-table
// 用于添加cnchar中不包含的汉字 或修改 cnchar中有误的汉字
cnchar.setOrder('大', 'jsl');
cnchar.setOrder({ // 多个
'大': 'jsl',
'子': 'egj'
});
拼音支持声调数字模式（lv2=>lǘ）
依赖 cnchar-poly
// 用于添加cnchar中不包含的词组 或修改 cnchar中有误的词组
cnchar.setPolyPhrase('测试', 'cè shi4');
cnchar.setPolyPhrase({ // 多个
'测试': 'cè shì',
'体验': 'tǐ yàn'
});
依赖 cnchar-radical
// 用于添加cnchar中不包含的汉字 或修改 cnchar中有误的汉字
cnchar.radical.setRadical('x', 'x');
cnchar.radical.setRadical({ // 多个
'x': 'x',
'y': 'y'
});
依赖 cnchar-xhy
cnchar.xhy.addXhy('歇后语第一句', '歇后语第二句');
cnchar.xhy.addXhy([ // 多条
['歇后语第一句', '歇后语第二句'],
['歇后语第一句2', '歇后语第二句2'],
]);
致谢
cnchar-draw 库功能基于 hanzi-writer, 特此表示感谢！
FAQs
功能全面、多端支持的汉字拼音笔画 js 库
The npm package cnchar-types receives a total of 492 weekly downloads. As such, cnchar-types popularity was classified as not popular.
We found that cnchar-types demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.