cnchar

cnchar is a comprehensive Chinese character processing library. Core capabilities include:

• Pinyin: Get pinyin, support for initials, case sensitivity, and tone marks.
• Strokes: Get stroke counts and stroke order; derive characters from stroke sequences.
• Conversions: Convert between Simplified Chinese, Traditional Chinese, and 'Mars Text' (火星文).
• Character Info: Access idioms, Xiehouyu, character explanations, and radical/component information.
• Audio: Speech synthesis (voice) and recognition (v3.1.0+).

Starting from version 3.2.0, Chinese name generation features are provided via the cnchar-name library. This library can run independently of the main cnchar core. It supports generating names, checking if a string is a surname, and checking if a string is a full name.

To use these features, you must install the cnchar-name package.

Plugins are independent modules that can be injected into cnchar. A plugin must have a pluginName property. The install method is called by cnchar.use(), receiving the cnchar instance as a callback, allowing the plugin to access core methods and other plugins.

TypeScript Implementation

For TypeScript support, it is recommended to install cnchar-types to get proper declarations.

import ICnChar, {IPlugin} from 'cnchar-types';

const plugin: IPlugin = {
    pluginName: 'custom',
    install (cnchar: ICnChar) {
        console.log(cnchar);
    },
    version: '0.0.1',
    log: () => console.log('hello cnchar-plugin!'),
};

declare module 'cnchar-types/main/index' {
    interface ICnChar {
        custom: {
            pluginName: 'custom';
            version: string;
            log: () => void;
        };
    }
}

export default plugin;

To enable random generation of Pinyin, Chinese characters, idioms, etc., you must install cnchar-random. This library can run independently of the main cnchar library.

If you are using cnchar as the host, you use cnchar.use(random, plugin). If you are using cnchar-random standalone, you must use random.use(plugin) to register the necessary dictionary plugins.

// Option 1: Using with cnchar
import cnchar from 'cnchar';
import random from 'cnchar-random';
import idiom from 'cnchar-idiom';

cnchar.use(random, idiom);
cnchar.random.idiom({number: 10});

// Option 2: Using cnchar-random standalone
import random from 'cnchar-random';
import idiom from 'cnchar-idiom';

random.use(idiom);
random.idiom({number: 10});

You can install cnchar via npm or include it directly in your HTML using a script tag.

npm installation:

npm i cnchar

Usage in JavaScript/TypeScript:

import cnchar from 'cnchar';
// do something

Usage via script tag:

<script src="https://fastly.jsdelivr.net/gh/theajack/cnchar/dist/cnchar.latest.min.js"></script>
<script>
    // do something
</script>

In non-browser environments (like Node.js), you must explicitly enable plugins using the .use() method. In browser environments, simply importing the plugin is sufficient.

Node.js Usage:

var cnchar = require('cnchar');
var xxx = require('cnchar-xxx');
cnchar.use(xxx);

To use the plugin in a JavaScript environment, import both cnchar and cnchar-trad, then register the plugin using cnchar.use(trad). Note that cnchar.use is optional in browser environments where the script is loaded via CDN.

import cnchar from 'cnchar';
import trad from 'cnchar-trad';
cnchar.use(trad);

In non-browser environments (like Node.js), you must explicitly enable plugins using the cnchar.use() method. Ensure the core cnchar library is imported first, followed by the desired plugin libraries.

In browser environments, you do not need to call .use(); simply importing the plugin (e.g., import 'cnchar-xxx') after cnchar is sufficient.

// Node.js environment
var cnchar = require('cnchar');
var xxx = require('cnchar-xxx');
cnchar.use(xxx);