pīnyīn (v3)

pinyin, The convert tool of chinese pinyin.

Web Site: 简体中文 | English | 한국어

README: 简体中文 | English | 한국어

Convert Han to pinyin. useful for phonetic notation, sorting, and searching.

Note: This module both support Node and Web browser.

Python version see mozillazg/python-pinyin

Feature

Segmentation for heteronym words.
Support Traditional and Simplified Chinese.
Support multiple pinyin style.

Install

via npm:

npm install pinyin --save

Usage

for developer:

import pinyin from "pinyin";

console.log(pinyin("中心"));    // [ [ 'zhōng' ], [ 'xīn' ] ]

console.log(pinyin("中心", {
  heteronym: true                // Enable heteronym mode.
}));                            // [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ]

console.log(pinyin("中心", {
  heteronym: true,              // Enable heteronym mode.
  segment: true                 // Enable Chinese words segmentation, fix most heteronym problem.
}));                            // [ [ 'zhōng' ], [ 'xīn' ] ]

console.log(pinyin("我喜欢你", {
  segment: true,                // Enable segmentation. Needed for grouping.
  group: true                   // Group pinyin segments
}));                            // [ [ 'wǒ' ], [ 'xǐhuān' ], [ 'nǐ' ] ]

console.log(pinyin("中心", {
  style: pinyin.STYLE_INITIALS, // Setting pinyin style.
  heteronym: true
}));                            // [ [ 'zh' ], [ 'x' ] ]

console.log(pinyin("华夫人", {
  mode: "surname",              // 姓名模式。
}));                            // [ ['huà'], ['fū'], ['rén'] ]

for cli:

$ pinyin 中心
zhōng xīn
$ pinyin -h

Types

IPinyinOptions

The types for the second argument of pinyin method.

export interface IPinyinOptions {
  style?: IPinyinStyle; // output style of pinyin.
  mode?: IPinyinMode, // mode of pinyin.
  segment?: IPinyinSegment | boolean;
  heteronym?: boolean;
  group?: boolean;
  compact?: boolean;
}

IPinyinStyle

The output style of pinyin.

export type IPinyinStyle =
  "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | // Suggest.
  "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" |
  0        | 1      | 2       | 5       | 3          | 4;               // compatibility.

IPinyinMode

The mode of pinyin.

// - NORMAL: Default mode is normal mode.
// - SURNAME: surname mode, for chinese surname.
export type IPinyinMode =
  "normal" | "surname" |
  "NORMAL" | "SURNAME";

IPinyinSegment

The segment method.

Default is disable segment: false，
If set true, use "Intl.Segmenter" module default for segment on Web and Node.
Also specify follow string for segment (bug just "Intl.Segmenter", "segmentit" is support on web):

export type IPinyinSegment = "Intl.Segmenter" | "nodejieba" | "segmentit" | "@node-rs/jieba";

API

`<Array> pinyin(words[, options])`

Convert Han （汉字） to pinyin.

options argument is optional, for sepcify heteronym mode and pinyin styles.

Return a Array<Array<String>>. If one of Han is heteronym word, it would be have multiple pinyin.

`Number pinyin.compare(a, b)`

Default compare implementation for pinyin.

Options

`<Boolean> options.segment`

Enable Chinese word segmentation. Segmentation is helpful for fix heteronym problem, but performance will be more slow, and need more CPU and memory.

Default is false.

`<Boolean> options.heteronym`

Enable or disable heteronym mode. default is disabled, false.

`<Boolean> options.group`

Group pinyin by phrases. for example:

我喜欢你
wǒ xǐhuān nǐ

`<Object> options.style`

Specify pinyin style. please use static properties like STYLE_*. default is .STYLE_TONE. see Static Property for more.

`options.mode`

pinyin mode, default is pinyin.MODE_NORMAL. If you cleared in surname scene, use pinyin.MODE_SURNAME maybe better.

Static Property

`.STYLE_NORMAL`

Normal mode.

Example: pin yin

`.STYLE_TONE`

Tone style, this is default.

Example: pīn yīn

`.STYLE_TONE2`

tone style by postfix number [0-4].

Example: pin1 yin1

`.STYLE_TO3NE`

tone style by number [0-4] after phonetic notation character.

Example: pin1 yin1

`.STYLE_INITIALS`

Initial consonant (of a Chinese syllable).

Example: pinyin of 中国 is zh g

Note: when a Han （汉字） without initial consonant, will convert to empty string.

`.STYLE_FIRST_LETTER`

First letter style.

Example: p y

`pinyin.MODE_NORMAL`

Normal mode. This is the default mode.

`pinyin.MODE_SURNAME`

Surname mode. If chinese word is surname, The pinyin of surname is prioritized.

Test

npm test

Q&A

How to sort by pinyin?

This module provide default compare implementation:

const pinyin = require('pinyin');

const data = '我要排序'.split('');
const sortedData = data.sort(pinyin.compare);

But if you need different implementation, do it like:

const pinyin = require('pinyin');

const data = '我要排序'.split('');

// Suggest you to store pinyin result by data persistence.
const pinyinData = data.map(han => ({
  han: han,
  pinyin: pinyin(han)[0][0], // Choose you options and styles.
}));
const sortedData = pinyinData.sort((a, b) => {
  return a.pinyin.localeCompare(b.pinyin);
}).map(d => d.han);

Donate

If this module is helpful for you, please Star this repository.

And you have chioce donate to me via Aliapy or WeChat:

Alipay:hotoo.cn@gmail.com, WeChat:hotoome

License

MIT

Current Tags

3.0.0-alpha.4 ... alpha (4 years ago)
4.0.0-alpha.2 ... latest (2 years ago)

49 Versions

4.0.0-alpha.2 ... 2 years ago
4.0.0-alpha.1 ... 2 years ago
4.0.0-alpha.0 ... 2 years ago
3.1.0 ... 2 years ago
3.0.0-alpha.7 ... 2 years ago
3.0.0-alpha.6 ... 2 years ago
3.0.0-alpha.5 ... 4 years ago
2.11.2 ... 4 years ago
3.0.0-alpha.4 ... 4 years ago
3.0.0-alpha.3 ... 4 years ago
3.0.0-alpha.2 ... 4 years ago
3.0.0-alpha.1 ... 4 years ago
3.0.0-alpha.0 ... 4 years ago
2.11.1 ... 4 years ago
2.11.0 ... 4 years ago
2.10.2 ... 5 years ago
2.10.1 ... 5 years ago
2.10.0 ... 5 years ago
2.9.1 ... 6 years ago
2.9.0 ... 7 years ago
2.8.3 ... 9 years ago
2.8.2 ... 9 years ago
2.8.0 ... 10 years ago
2.7.4 ... 10 years ago
2.7.3 ... 10 years ago
2.7.2 ... 10 years ago
2.7.1 ... 10 years ago
2.7.0 ... 10 years ago
2.6.2 ... 11 years ago
2.6.1 ... 11 years ago
2.6.0 ... 11 years ago
2.5.1 ... 11 years ago
2.5.0 ... 11 years ago
2.4.4 ... 11 years ago
2.4.3 ... 11 years ago
2.4.2 ... 11 years ago
2.4.1 ... 11 years ago
2.4.0 ... 11 years ago
2.3.3 ... 12 years ago
2.3.2 ... 12 years ago
2.2.1 ... 12 years ago
2.2.0 ... 12 years ago
2.1.3 ... 12 years ago
2.1.2 ... 12 years ago
2.1.1 ... 12 years ago
2.1.0 ... 12 years ago
2.0.2 ... 12 years ago
2.0.0 ... 12 years ago
0.0.1 ... 14 years ago