Thank you for your support for cnchar. Since the cnchar lexicon comes from the Internet, although it has been modified and expanded by myself, it is still inevitable that there are errors and gaps. I hope you can [feedback](https://github.com/theajack/cnchar/issues/new) the errors and gaps found in use I (or amend and submit it by myself, and it will be merged into cnchar after reviewing without error)
[I want to report errors or omissions](https://github.com/theajack/cnchar/issues/new)
<ahref="#66-usage-examples"> More detailed usage examples </a> | <ahref="#6-spell-stroke-parameters"> Detailed introduction of parameters </a>
### 1. Features
1. Obtain**Chinese Pinyin**, support the first letter, uppercase and lowercase, array split, alternative**multi-syllable characters**and other functions
2. Support**Polyphones**
3. Support**Pinyin tone**
4. Get Chinese characters**stroke number**, support array split
5. Obtain Chinese characters**stroke order**, detailed stroke name
6. Support visualization**Drawing Chinese character strokes**, multiple drawing modes are optional
7. Support**Simplified Chinese characters**,**Traditional Chinese characters**,**Martian script**
8. Support**Find**all**Chinese characters**of a certain pinyin, traditional characters, and polyphonic characters
9. Support**Find**all the specified number of strokes**Chinese characters**, traditional characters
10. Support**Query by stroke order**Chinese characters
11. Support**Query pinyin information**, including initials, finals, tones, tone positions, etc.
12. Support**Traditional Chinese Characters**Pinyin, Stroke Count and all above functions to achieve the same functions as Simplified Chinese Characters
17.**Small size**, min version is only 46 kb, zip version is 34 kb(contains a large number of Chinese Pinyin dictionaries)
18.**Multi-end available**, can be used in**browser, nodejs, applet / mini-game, ReactNative / Weex / Uniapp / Electron, webpack**..., supports all environments where js can run
Taking into account different needs, the functions of cnchar have been split into the following seven libraries to facilitate developers to access them as needed:
cnchar|The main js library, the other three libraries depend on this library|Contains simplified Chinese pinyin, polyphonic characters, tone, stroke number and other functions | -- |
| cnchar-poly|Polysyllabic dictionary|Contains the function of identifying polysyllabic words | -- |
| cnchar-order|Stroke order library|Contains functions for identifying stroke order, stroke name, stroke shape, etc. | -- |
| cnchar-trad|Traditional Chinese Character Library|Support Traditional Chinese, Mars, Simplified Chinese, Simplified Chinese Pinyin Stroke and Multi-phone Characters | -- |
| cnchar-draw|Drawing stroke library|Point out the visual drawing of Chinese characters, there are four modes of normal, animation, stroke, test optional, the library is only available in the browser environment | 2.1+ |
| cnchar-idiom | idiom library | support idiom query and other functions | 2.2+ |
| cnchar-xhy | Xiehou language library | Support Xiehouyu query and other functions | 2.2+ |
Of course, you can also install a few of them on demand, but the basic library `cnchar` must be installed (draw, idiom, xhy, radical four libraries can be used independently)
In order to make the API use as simple as possible, the library has designed two main and very simple APIs, and to ensure that the calling method is consistent:
```js
// Pinyin, polyphonic words, tones, etc. of Chinese characters are integrated in the following methods
cnchar.spell(string [,...args]);
// or
string.spell([... args])
// Get the strokes and stroke order of Chinese characters are integrated in the following methods
cnchar.stroke(string [,...args]);
// or
string.stroke([... args])
```
The API design is consistent, `string` represents the Chinese character string to be processed
The key lies in the configuration of optional parameters, which will be introduced separately in <ahref="#user-content-6-spell-stroke-parameters"> Chapter 6 </a>
#### 5.2 Draw Chinese characters visually: draw
Type declaration: [cnchar.draw.d.ts](https://github.com/theajack/cnchar/blob/master/src/plugin/draw/index.d.ts)
The `cnchar-draw` library is used to support the visual drawing of Chinese characters in a browser environment, so this library is only available in a browser environment. There are four drawing modes: normal, animation, stroke, and test.
The following are all optional parameters and descriptions of options, please refer to [online documentation](https://cnchar.js.org) for usage details:
strokeColor?: string; //:'# 555', // Hexadecimal character, default'# 555'. Draw the color of each stroke.
radicalColor?: string; //: null, // Hexadecimal character, default null. If there is radical data, the color of the radical is drawn in the stroke. If not set, the laser will draw the same color as other strokes.
strokeFadeDuration?: number; // 400
},
line?: {// background 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, // value, default 1. The speed of drawing each stroke must be greater than 0. Increasing this number can draw strokes faster, and decreasing strokes draws more slowly.
delayBetweenStrokes?: number; //: 1000, // value, default 1000. The interval time(in milliseconds) between each stroke in the animation.
delayBetweenLoops?: number; //: 200, // value, default 2000. The time(in milliseconds) between each animation loop when looping animations.
autoAnimate?: boolean; //: true,
animateComplete?: Function; //:() => {},
stepByStep?: boolean; //: true,
loopAnimate?: boolean; //: false,
},
test?: {
strokeHighlightSpeed ?: number; //: 20, // Numeric value, default 20. The speed of highlighting each stroke must be greater than 0 when giving hints in the quiz. Increase this number to highlight faster, and decrease to highlight slower.
highlightColor?: number; //:'#aaf', // Hexadecimal characters, default'#AAF'. The color used to highlight in the quiz.
drawingColor?: number; //:'# 333', // Hexadecimal characters, default'# 333'. The color of the lines drawn during the quiz.
drawingWidth?: number; //: 4, // numeric value, default 4. The width of the line drawn during the test.
showHintAfterMisses?: number; //: 3, // Integer, default 3 The number of misses before the stroke highlighting prompt is given to the user. Set to false to disable. You can also set this when creating a quiz.
highlightOnComplete?: number; //: true, // Boolean, default true. Controls whether the quiz will highlight the character briefly when the user finishes drawing the entire character. You can also set this when creating a quiz.
highlightCompleteColor?: number; //: null, // Hexadecimal character, default null. The color used when highlighting characters in the quiz. If not set, highlightColor will be used. Only relevant if highlightOnComplete is true.
The library is driven by HanziWriter, and currently only supports use in the web environment. If you need to use WeChat Mini Programs, please refer to [HanziWriter API](https://hanziwriter.org/docs.html#wechat-miniprograms)
#### 5.3 Traditional, Simplified and Martian conversion: convert
After the introduction of `cnchar-trad`, cnchar has the traditional, simplified, and Martian text conversion function. You can use this function by using the method on the` cnchar.convert` object.
Since v2.0.4, cnchar reserves the following methods for use:
```js
cnchar.convert.simpleToTrad(string); // Simplified => Traditional
cnchar.convert.sparkToTrad(string); // Martian => Traditional
string.convertSimpleToTrad();
string.convertSimpleToSpark();
string.convertTradToSimple();
string.convertTradToSpark();
string.convertSparkToSimple();
string.convertSparkToTrad();
```
#### 5.4 Stroke sequence launches original Chinese characters: orderToWord
After the introduction of the `cnchar-order` function library(version 2.0.2 and above), cnchar supports the function of launching original Chinese characters according to the sequence of stroke names. The usage is as follows:
```js
cnchar.orderToWord(orderNames [,...args]);
```
`orderNames` is a sequence of stroke names
`args` is the parameter list, and the optional values are` ['match','matchorder','contain','start','array','simple'] `, use` cnchar.type.orderToWord` to view Choose value. For detailed usage of parameters, please refer to <ahref="#63-ordertoword-parameters"> Chapter 6 orderToWord Parameters </a>
`orderNames` can be space-separated stroke name string or stroke name array, available stroke names can be viewed through the following api
```js
var dict = cnchar.orderToWord.orders; // dict is a json data containing detailed information about the number of strokes
```
The stroke details are as follows, orderNames only need to pass in the stroke name, which is the key value of the following json data
If the entered stroke is not in `cnchar.orderToWord.orders`, the method will print an error indicating which stroke is wrong, and return an empty array.
#### 5.5 Query original Chinese characters by pinyin: spellToWord
The `spellToWord` method is used to query the Chinese characters that meet the requirements based on pinyin. The usage is as follows:
cnchar added the idiom function in 2.2.0. To enable this function, you need to install the `cnchar-idiom` function library, which can run independently of the main cnchar library.
cnchar added the Xiehouyu function in 2.2.0. To enable this function, you need to install the `cnchar-xhy` function library, which can be run independently of the main cnchar library.
When using cdn references, the `CncharXHY` object will be exposed upwards in the window
#### 5.9 Radical radical function
Cnchar added the radical radical function in 2.2.5. To enable this function, you need to install the `cnchar-radical` function library, which can run independently of the cnchar main library
cnchar organizes and exposes some methods of operating pinyin and Chinese characters used inside the library, which is convenient for developers to operate pinyin and Chinese characters conveniently and efficiently
isTrans: boolean; // Whether it is converted such as lv2 -> lǘ
}
*/
```
tone is an optional parameter, indicating whether the return value spell needs to bring a tone, the default is false
type is an optional parameter, indicating that the return value spell sets the case, the default is'low'
The transformTone spell parameter supports the use of v instead of ü, and the use of numbers at the end to represent the tone, for example, `lv is equivalent to lü`shang4 is equivalent to shàng`
The `compareStroke` method is used to compare the size of Chinese characters according to the number of strokes. It can be used to sort the first Chinese character strokes according to the name. For sorting, please refer to the `sortStroke` method
The `sortSpell` method is used to sort Chinese characters or Pinyin according to Pinyin, supports input arrays or strings, supports sorting by tone, and supports reverse order
When it is an array, the array elements can be Chinese characters or Pinyin, and the returned array is
When it is a string, the string must be all Chinese characters, and the returned string
There are two optional parameters for this method,'tone' means sorting by tone, and'desc' means reverse order, by default, no distinction is made between tone and ascending order. Please see some examples
##### 5.10.9 Convert digital tones to pinyin tones: shapeSpell
`shapeSpell` converts tones represented by numbers to pinyin tones
For example, `lv2` will be converted to `lǘ`, and `ta1` will be converted to `tā` for user input
```ts
cnchar.shapeSpell(spell: string): string;
```
#### 5.11 Custom data
Since the cnchar data comes from the Internet, although it has undergone a lot of modifications, it is still inevitable that there will be errors and omissions
So cnchar provides an api to modify the default data to facilitate developers to modify and add data
The stroke order added must be a letter, please refer to the corresponding relationship for details [stroke-table](https://github.com/theajack/cnchar/blob/master/src/cnchar/plugin/order/dict/stroke-table.json)
The type object user gets the currently available `spell`,` stroke`, `orderToWord`,` spellToWord`, `strokeToWord`, `idiom`, `xhy`, `radical` parameter types:
This value is a Boolean type, used to control whether to enable parameter verification, the default value is true
Parameter verification can check the incoming parameters of `spell` and` stroke` and display the parameters of `invalid`,` ignore` and `redundant` on the console
simple|Whether to disable pinyin of traditional characters|No|cnchar-trad|After using cnchar-trad, the traditional pinyin is converted by default. This parameter is used to disable traditional pinyin |
#### 6.2 stroke parameters
The parameters are called as follows, all arg parameters are optional
| array|return array|No |--| This parameter is ignored after using cnchar-order and the order parameter is enabled |
order|Enable stroke order|No|cnchar-order |--|
letter|Use stroke order alphabet sequence|Yes|cnchar-order|When order is enabled, this value is the default value |
detail|Use stroke order details as the return value, each Chinese character corresponds to a json|No|cnchar-order|Priority is less than letter |
shape|Use stroke shape as return value|No|cnchar-order|Priority is less than detail |
| name|Use stroke name as return value|No|cnchar-order|Priority is less than shape |
| count|Use the number of strokes as the return value|No|cnchar-poly|Priority is less than name |
simple|Whether to disable the stroke function of traditional characters|No|cnchar-trad|After using cnchar-trad, the stroke function is enabled for traditional characters by default.
#### 6.3 orderToWord parameters
The parameters are called as follows, all arg parameters are optional
| simple|Only match simplified Chinese characters|No |--|--|
| trad|Only match traditional characters|No|cnchar-trad|This parameter is only valid after the introduction of `cnchar-trad` |
| poly|Only match polyphones|No |--|--|
| alltone|Chinese characters that match all the tones of the pinyin|No |--| Pinyin without tones means soft |
| array|Returns an array that meets the conditions, the default is to return a string|No |--|--|
Note: If both `simple` and` trad` parameters do not exist, then when"cnchar-trad"is introduced, it will match both Simplified and Simplified Chinese; when"cnchar-trad"is not introduced, it will only match Simplified
#### 6.5 strokeToWord parameters
The parameters are called as follows, count represents the number of strokes, all arg parameters are optional
| simple|Only match simplified Chinese characters|No |--|--|
| trad|Only match traditional characters|No|cnchar-trad|This parameter is only valid after the introduction of `cnchar-trad` |
| array|Returns an array that meets the conditions, the default is to return a string|No |--|--|
Note: If both `simple` and` trad` parameters do not exist, then when"cnchar-trad"is introduced, it will match both Simplified and Simplified Chinese; when"cnchar-trad"is not introduced, it will only match Simplified
| char | query idioms based on Chinese characters | yes | - | default value without calling |
| stroke | query idioms based on the number of strokes | No | - | priority over char |
| spell | Query idioms based on Pinyin | No | - | Priority over stroke |
| tone | Enable Pinyin tone query | No | - | Only effective in spell mode |
Note: Priority `spell`> `stroke`> `char`
#### 6.7 xhy parameters
The parameters are called as follows. value represents the query object of Xiehouyu, which can be the first sentence or the second sentence of Xiehouyu. All arg parameters are optional
This library is used to support the conversion of traditional Chinese characters to Mars and provide traditional Chinese characters for basic functions such as pinyin
cnchar provides some Chinese character tool methods to facilitate developers to operate pinyin and Chinese characters more conveniently and efficiently
// Used to set or modify the default pronunciation of polyphonic characters in cnchar
cnchar.setSpellDefault('长', 'zhǎng');
cnchar.setSpellDefault({ // Multiple Chinese characters
'长': 'zhǎng',
'中': 'zhòng'
});
```
###### 6.9.8.12 setStrokeCount
```js
// Used to add Chinese characters that are not included in cnchar or modify incorrect Chinese characters in cnchar
cnchar.setStrokeCount('大', 3);
cnchar.setStrokeCount({ // Multiple Chinese characters
'大': 3,
'子': 3
});
```
###### 6.9.8.13 setOrder
Depend on `cnchar-order`
The stroke order added must be a letter, please refer to the corresponding relationship for details [stroke-table](https://github.com/theajack/cnchar/blob/master/src/plugin/order/stroke-table.json)
```js
// Used to add Chinese characters that are not included in cnchar or modify incorrect Chinese characters in cnchar
cnchar.setOrder('大', 'jsl');
cnchar.setOrder({ // Multiple Chinese characters
'大': 'jsl',
'子': 'egj'
});
```
###### 6.9.8.14 setPolyPhrase
Pinyin supports tonal digital mode (lv2=>lǘ)
Depend on `cnchar-poly`
```js
// Used to add phrases that are not contained in cnchar or modify incorrect phrases in cnchar
cnchar.setPolyPhrase('测试', 'cè shi4');
cnchar.setPolyPhrase({ // Multiple Chinese characters
'测试': 'cè shì',
'体验': 'tǐ yàn'
});
```
###### 6.9.8.14 setRadical
Depend on `cnchar-radical`
```js
// Used to add Chinese characters that are not included in cnchar or modify incorrect Chinese characters in cnchar
cnchar.radical.setRadical('x', 'x');
cnchar.radical.setRadical({ // Multiple Chinese characters
