GitHub

开始文档之前，先通过一些应用案例看看cnchar能够做些什么

关于该文档

由于文档较长，做一下简介，请按照需要阅读

使用npm安装：

npmicncharimportcncharfrom'cnchar';'汉字'.spell();'汉字'.stroke();使用script标签使用：

npmicnchar安装附加功能库：

npmicnchar-polycnchar-ordercnchar-tradcnchar-drawcnchar-idiomcnchar-xhycnchar-radicalcnchar-wordscnchar-explaincnchar-voicecnchar-randomcnchar-codecnchar-inputcnchar-infocnchar-name当然您也可以按需安装其中的几个，插件库也都可以脱离cnchar独立安装使用，不过部分仓库功能强依赖于cnchar，如cnchar-polycnchar-ordercnchar-trad

或者您可以通过安装cnchar-all来使用完整功能，这个库引用了上面的所有插件库

//请保证最先引入cnchar基础库，其他几个库顺序无所谓importcncharfrom'cnchar';import'cnchar-poly';//...其他插件请参考第二章2.功能及插件概览//插件请按需取用console.log('汉字'.spell());//prototype方式调用console.log(cnchar.spell('汉字'));//cncharapi调用浏览器环境下会在window对象上定义cnchar对象

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

//请保证最先引入cnchar基础库，其他几个库顺序无所谓varcnchar=require('cnchar');varpoly=require('cnchar-poly');//...其他插件请参考第二章2.功能及插件概览//插件请按需取用//注：cnchar-draw，cnchar-voice在非浏览器环境下不可使用cnchar.use(poly);console.log('汉字'.spell());//prototype方式调用console.log(cnchar.spell('汉字'));//cncharapi调用其他使用方式与浏览器环境一致

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

注：该章节仅介绍API用法，更多使用实例请参考第六章

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

//获取汉字的拼音、多音词、音调等都集成在以下方法上cnchar.spell(string[,...args]);//或string.spell([...args])//获取汉字的笔画、笔画顺序等都集成在以下方法上cnchar.stroke(string[,...args]);//或string.stroke([...args])该api设计一致，string表示要处理的汉字字符串

cnchar-draw库用于支持在浏览器环境下可视化绘制汉字，所以该库仅在浏览器环境下可用。绘制模式有normal,animation,stroke,test四种模式可选。

使用方式如下：

cnchar.draw('你好',options);//options为可选参数，在5.2.2种会详细介绍运行结果如下：

该库支持脱离cnchar独立使用

importdrawfrom'cnchar-draw';draw('你好')使用cdn引用时，会在window对向上暴露CncharDraw对象

draw的参数比较繁多，首先需要理解的是，draw分为四种绘制模式：

declareinterfaceIWriter{option:IDrawOption;el:HTMLElement;type:TDrawType;text:Array;writers:Array;startAnimation():boolean;pauseAnimation():void;resumeAnimation():void;drawNextStroke(onComplete:()=>void):boolean;}当drawType=animation时，以下几个api可以用户控制动画

绘制模式分为连续绘制和单笔画绘制，默认为连续绘制模式

单笔划绘制模式需要option.animation.autoAnimate=false且调用drawNextStroke方法

当option.animation.autoAnimate=false时，调用该api可以开始绘制，且开启动连续绘制模式

首先需要使用参数option.animation.autoAnimate=false

自从v2.0.4以后，cnchar保留以下方法可供使用：

cnchar.orderToWord(orderNames[,...args]);orderNames是笔画名称序列

orderNames可以是空格分隔的笔画名称字符串或笔画名称数组，可用的笔画名称可以通过以下api查看

vardict=cnchar.orderToWord.orders;//dict是一个包含所有笔画数的详细信息的json数据笔画详细信息的如下，orderNames只需要传入笔画名称即可，也就是下面json数据的key值

以下是一个例子：

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.idiom(text:string|number|Array):Array;看一个具体例子

//根据汉字查询成语，末尾的空格可以省略cnchar.idiom(['五','','十','']);//['五风十雨','五光十色']//根据笔画数查询成语，0表示匹配任意笔画，末尾的0可以省略cnchar.idiom([4,6,2,0]);//["不当人子",...]//根据拼音查询成语cnchar.idiom('shang');//["伤风败化","伤风败俗",...]//带音调cnchar.idiom('shang4');//["上兵伐谋","上不着天，下不着地",...]使用cdn引用时，会在window对向上暴露CncharIdiom对象

cnchar在2.2.0加入了歇后语功能，启用该功能需要安装cnchar-xhy功能库，该库可以独立于cnchar主库运行

cnchar.xhy(text:string,...xhyArgs:Array):Array;看一个具体例子

//精确查询cnchar.xhy('大水冲了龙王庙');//['大水冲了龙王庙-自家人不识自家人','大水冲了龙王庙-一家人不认一家人'],//模糊查询cnchar.xhy('大水','fuzzy');//['江河里长大水-泥沙俱下','江河发大水-后浪推前浪',...]//只返回答案结果cnchar.xhy('大水','fuzzy','answer');//['泥沙俱下','后浪推前浪',...]//根据歇后语后一句查询cnchar.xhy('上晃下摇','fuzzy','answer','second');//['醉汉过铁索桥','扶着醉汉过破桥']使用cdn引用时，会在window对向上暴露CncharXHY对象

cnchar在2.2.5加入了偏旁部首功能，启用该功能需要安装cnchar-radical功能库，该库可以独立于cnchar主库运行

且于3.2.0版本进行了升级，支持了查询汉字结构和偏旁笔画数

感谢kewell-tsao提供的pr

cnchar.radical(text:string|Array):Array<{radical:string;struct:TStruct;radicalCount:number;}>使用cdn引用时，会在window对向上暴露CncharRadical对象

cnchar在3.1.0加入了组词功能，需要安装cnchar-words,具体使用如下

args传入trad可以查询繁体字，但是依赖于安装了cnchar-trad

cnchar.words(words:string,...args:string[]):string[];看一个具体例子

cnchar在3.1.0加入了查询解释功能，需要安装cnchar-explain,具体使用如下

cnchar.explain(words:string,...args:string[]):string[];看一个具体例子

cnchar在3.1.0加入了发音、语音合成和语音识别功能,需要安装cnchar-voice,

voiceapi用于发音单个和多个汉字发音，对于句子发音连续效果不佳，但是兼容性好，支持小程序使用

cnchar将库内部使用的一些操作拼音和汉字的方法整理暴露出来，方便开发者便捷高效的操作拼音和汉字

spellInfo方法用于查询拼音的详细信息，用法如下：

cnchar.spellInfo(spell);例子：

cnchar.spellInfo('Shàng');/*//返回值与含义如下{spell:'shang',//无音调拼音initial:'sh',//声母final:'ang',//韵母tone:4,//音调index:3//音调位置},*/除此之外，spellInfo上含有initials和tones两个属性，分别表示，所有可用的声母和音调：

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'

transformTonespell参数支持使用v代替ü，支持使用末尾带数字表示声调，比如lv等价于lüshang4等价于shàng

isCnChar方法用于判断字符串是否全部是汉字

该方法支持按照拼音和声调比较，如需排序可以参考sortSpell方法

cnchar.compareSpell(spell1:string,spell2:string,tone:boolean);tone参数表示是否需要按照音调比较，默认为false

该方法返回一个字符串，'more','less','even'分别表示spell1大于、小于、等于spell2

例

cnchar.compareStroke(stroke1:string,stroke2:string);该方法支持输入汉字或数字，汉字可以输入多个

该方法返回一个字符串，'more','less','even'分别表示stroke1大于、小于、等于stroke2

例子：

cnchar.sortSpell(spells:Array|string,...args:Array<'tone'|'desc'>):Array|string;spells参数可以是数组或字符串

当为数组时，数组元素可以时汉字或拼音，返回的是数组

当为字符串时，字符串必须全部是汉字，返回的是字符串

该方法可选参数有两个，'tone'表示按照音调排序，'desc'表示倒序，默认不区分声调且升序。请看一些例子

cnchar.sortStroke(strokes:Array|string,desc:'desc'):Array|string;strokes参数可以是数组或字符串

当为数组时，数组元素可以时汉字或数字，返回的是数组

该方法有一个可选参数，'desc'表示倒序，默认升序。请看一些例子

如lv2会被转换成lǘ，ta1会被转换成tā，方便用户输入

reverse参数表示开启反向转换lǘ=>lv2

所以cnchar提供了修改默认数据的api，方便开发者修改与添加数据

设置拼音数据

cnchar.use(...libs);这个启用在非浏览器环境（比如nodejs等）中是必须的，使用如下：

//请保证最先引入cnchar基础库，其他插件库顺序无所谓varcnchar=require('cnchar');varxxx=require('cnchar-xxx');cnchar.use(xxx);在浏览器环境中则无需调用：

varspellArg=cnchar.type.spell;varstrokeArg=cnchar.type.stroke;varorderToWordArg=cnchar.type.orderToWord;varspellToWordArg=cnchar.type.spellToWord;varstrokeToWordArg=cnchar.type.strokeToWord;varxhyArg=cnchar.type.xhy;varradicalArg=cnchar.type.radical;varwordsArg=cnchar.type.words;varexplainArg=cnchar.type.explain;spellArg最多可用值：['array','low','up','first','poly','tone','simple','flat']

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']

xhyArg最多可用值：['fuzzy','answer','second']

radicalArg最多可用值：['array','trad']

wordsArg最多可用值：['trad']

explainArg最多可用值：['trad']

以上值皆为json

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

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

varplugins=cnchar.plugins;//array类型可以使用hasPluginapi来判断是否引入了某插件

所以没有跟随npm包一起下载到本地，而是使用cdn方式动态加载

另外voice,draw,explain三个仓库也支持独立setResourceBase

cnchar采用的是独立的插件形式，定义一个cnchar插件非常简单且不依赖任何第三方包，并且通过cnchar注入，可以访问到任何cnchar和其他插件的方法

一个cnchar插件只有一个必选属性pluginName

表示插件名称，cnchar.use插件之后，会注入到cnchar.plugins中，且插件对象会被挂载到cnchar上

cnchar所有现有插件都会携带有dict属性用来暴露内部的字典，以方便其他插件可以直接使用

install是一个方法，cnchar.use插件之后，cnchar对象会调用install方法，并将cnchar对象作为回调带入插件中，可以通过cnchar对象访问cnchar和其他插件方法

插件被安装成功之后，会注入一个getCnChar到插件上，可以获取到cnchar对象

推荐使用cnchar-types,首先需要安装cnchar-types

npmicnchar-typesimportICnChar,{IPlugin}from'cnchar-types';constplugin:IPlugin={pluginName:'custom',install(cnchar:ICnChar){console.log(cnchar);},version:'0.0.1',log:()=>console.log('hellocnchar-plugin!');};declaremodule'cnchar-types/main/index'{interfaceICnChar{custom:{pluginName:'custom';version:string;log:()=>void;};}}exportdefaultplugin;不使用cnchar-types

cnchar.spell(string,arg1,arg2,...);string.spell(arg1,arg2,...)arg参数信息如下：

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

cnchar.stroke(string,arg1,arg2,...);string.stroke(arg1,arg2,...);arg参数信息如下：

cnchar.orderToWord(orders,arg1,arg2,...);arg参数信息如下：

关于匹配参数，优先级为match>matchorder>contain>start>默认

不含有匹配参数时表示使用全匹配，即汉字笔画数与传入的orders完全一致

cnchar.spellToWord(spell,arg1,arg2,...);spell表示拼音，可以使用音调字母或音调数标方式：例：shàng等价于shang4

arg参数信息如下：

注：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表示查询对象，可以试拼音汉字笔画数

如果引用了cnchar-trad,则会自动识别繁体字

npmicncharimportcncharfrom'cnchar';//dosomethingscript标签引用方式

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

'一个'.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]根据笔画名称序列推出原汉字

依赖cnchar-poly

致谢

功能全面的汉字工具库(拼音笔画偏旁成语语音可视化等)(Chinesecharacterutil)