Pinyin Pro

https://github.com/zh-lx/pinyin-pro
Admin
Pinyin Pro is a professional and accurate JavaScript library for converting Chinese characters to...
Tokens:28,579
Snippets:211
Trust Score:9.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Installation

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.0.x.md

Instructions for installing the pinyin-pro library using npm or yarn.

```APIDOC
## Installation

### npm
```bash
npm install pinyin-pro
```

### yarn
```bash
yarn add pinyin-pro
```
```

--------------------------------

### Get Pinyin

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.6.x.md

Examples of how to get Pinyin with different tone types and output formats.

```APIDOC
## Get Pinyin

### Basic Usage
```javascript
import { pinyin } from 'pinyin-pro';

// Get Pinyin with tone marks
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'

// Get Pinyin without tone marks
pinyin('汉语拼音', { toneType: 'none' }); // 'han yu pin yin'

// Get Pinyin with tone numbers
pinyin('汉语拼音', { toneType: 'num' }); // 'han4 yu3 pin1 yin1'

// Get Pinyin as an array with tone marks
pinyin('汉语拼音', { type: 'array' }); // ["hàn", "yǔ", "pīn", "yīn"]

// Get Pinyin as an array without tone marks
pinyin('汉语拼音', { toneType: 'none', type: 'array' }); // ["han", "yu", "pin", "yin"]

// Get Pinyin as an array with tone numbers
pinyin('汉语拼音', { toneType: 'num', type: 'array' }); // ['han4', 'yu3', 'pin1', 'yin1']
```
```

--------------------------------

### Get Initials

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.6.x.md

Examples for extracting the initial consonant sound of Pinyin.

```APIDOC
## Get Initials

### Basic Usage
```javascript
import { pinyin } from 'pinyin-pro';

// Get initials
pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'

// Get initials as an array
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```
```

--------------------------------

### Usage Examples

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.0.x.md

Provides practical examples of using the `pinyin` function to obtain Pinyin, initials, finals, tone numbers, first letters, and handle polyphonic characters with different options.

```APIDOC
## Usage Examples

### Get Pinyin

```javascript
import { pinyin } from 'pinyin-pro';

// Get Pinyin with tone marks
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
// Get Pinyin without tone marks
pinyin('汉语拼音', { toneType: 'none' }); // 'han yu pin yin'
// Get Pinyin with tone numbers
pinyin('汉语拼音', { toneType: 'num' }); // 'han4 yu3 pin1 yin1'
// Get Pinyin as an array with tone marks
pinyin('汉语拼音', { type: 'array' }); // ["hàn", "yǔ", "pīn", "yīn"]
// Get Pinyin as an array without tone marks
pinyin('汉语拼音', { toneType: 'none', type: 'array' }); // ["han", "yu", "pin", "yin"]
// Get Pinyin as an array with tone numbers
pinyin('汉语拼音', { toneType: 'num', type: 'array' }); // ['han4', 'yu3', 'pin1', 'yin1']
```

### Get Initials

```javascript
import { pinyin } from 'pinyin-pro';

// Get initials
pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'
// Get initials as an array
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```

### Get Finals

```javascript
import { pinyin } from 'pinyin-pro';

// Get finals with tone marks
pinyin('汉语拼音', { pattern: 'final' }); // 'àn ǔ īn īn'
// Get finals without tone marks
pinyin('汉语拼音', { pattern: 'final', toneType: 'none' }); // 'an u in in'
// Get finals with tone numbers
pinyin('汉语拼音', { pattern: 'final', toneType: 'num' }); // 'an4 u3 in1 in1'
// Get finals as an array with tone marks
pinyin('汉语拼音', { pattern: 'final', type: 'array' }); // ["àn", "ǔ", "īn", "īn"]
// Get finals as an array without tone marks
pinyin('汉语拼音', { pattern: 'final', toneType: 'none', type: 'array' }); // ["an", "u", "in", "in"]
// Get finals as an array with tone numbers
pinyin('汉语拼音', { pattern: 'final', toneType: 'num', type: 'array' }); // ['an4', 'u3', 'in1', 'in1']
```

### Get Tone Numbers

```javascript
import { pinyin } from 'pinyin-pro';

// Get tone numbers
pinyin('汉语拼音', { pattern: 'num' }); // '4 3 1 1'
// Get tone numbers as an array
pinyin('汉语拼音', { pattern: 'num', type: 'array' }); // ["4", "3", "1", "1"]
```

### Get First Letters

```javascript
import { pinyin } from 'pinyin-pro';

// Get first letters
pinyin('赵钱孙李额', { pattern: 'first' }); // 'z q s l é'
// Get first letters without tone marks
pinyin('赵钱孙李额', { pattern: 'first', toneType: 'none' }); // 'z q s l e'
// Get first letters as an array
pinyin('赵钱孙李额', { pattern: 'first', type: 'array' }); // ['z', 'q', 's', 'l', 'é']
// Get first letters as an array without tone marks
pinyin('赵钱孙李额', { pattern: 'first', toneType: 'none', type: 'array' }); // ['z', 'q', 's', 'l', 'e']
```

### Get Polyphonic Characters

Only single characters can get polyphonic mode; words and sentences are invalid. You can also get array or final formats by configuring the options.

```javascript
import { pinyin } from 'pinyin-pro';

// Get polyphonic Pinyin
pinyin('好', { multiple: true }); // 'hǎo hào'
// Get polyphonic Pinyin as an array
pinyin('好', { multiple: true, type: 'array' }); // ["hǎo", "hào"]
```
```

--------------------------------

### Install pinyin-pro via npm

Source: https://github.com/zh-lx/pinyin-pro/blob/main/README.md

Use this command to install the pinyin-pro library in your Node.js project.

```html
npm install pinyin-pro
```

--------------------------------

### Get Tones

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.6.x.md

Examples for extracting only the tone numbers.

```APIDOC
## Get Tones

### Basic Usage
```javascript
import { pinyin } from 'pinyin-pro';

// Get tone numbers
pinyin('汉语拼音', { pattern: 'num' }); // '4 3 1 1'

// Get tone numbers as an array
pinyin('汉语拼音', { pattern: 'num', type: 'array' }); // ["4", "3", "1", "1"]
```
```

--------------------------------

### Get First Letters

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.6.x.md

Examples for extracting the first letter of each Pinyin syllable.

```APIDOC
## Get First Letters

### Basic Usage
```javascript
import { pinyin } from 'pinyin-pro';

// Get first letters
pinyin('汉语拼音', { pattern: 'first' }); // 'h y p y'

// Get first letters as an array
pinyin('汉语拼音', { pattern: 'first', type: 'array' }); // ["h", "y", "p", "y"]
```
```

--------------------------------

### Getting Initials (声母)

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.4.x.md

Demonstrates how to extract only the initial consonant sound from Chinese Pinyin.

```APIDOC
## Get Initials

### Get initials with spaces
```js
import { pinyin } from 'pinyin-pro';
pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'
```

### Get initials as an array
```js
import { pinyin } from 'pinyin-pro';
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```
```

--------------------------------

### Get Pinyin Strings and Arrays

Source: https://github.com/zh-lx/pinyin-pro/blob/main/README.md

Demonstrates how to get pinyin in string or array format, with options for tone types.

```javascript
import { pinyin } from "pinyin-pro";

// 获取字符串格式拼音
pinyin("汉语拼音"); // 'hàn yǔ pīn yīn'

// 获取数组格式拼音
pinyin("汉语拼音", { type: "array" }); // ["hàn", "yǔ", "pīn", "yīn"]

// 获取不带音调格式拼音
pinyin("汉语拼音", { toneType: "none" }); // "han yu pin yin"

// 获取不带音调数组格式拼音
pinyin("汉语拼音", { toneType: "none", type: "array" }); // ["han", "yu", "pin", "yin"]

// 音调以数字形式显示
pinyin("汉语拼音", { toneType: "num" }); // "han4 yu3 pin1 yin1"

// 自动识别多音字
pinyin("睡着了"); // "shuì zháo le"
```

--------------------------------

### Handle Multiple Pinyin for a Character

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.6.x.md

Demonstrates how to get all possible Pinyin pronunciations for a multi-tone character.

```APIDOC
## Handle Multiple Pinyin for a Character

### Basic Usage
```javascript
import { pinyin } from 'pinyin-pro';

// Get all Pinyin for a multi-tone character
pinyin('重', { multiple: true }); // ['zhòng', 'chóng']

// Get all Pinyin as an array
pinyin('重', { multiple: true, type: 'array' }); // ['zhòng', 'chóng']
```
```

--------------------------------

### Getting Tone Numbers (音调)

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.4.x.md

Demonstrates how to extract only the tone number for each syllable.

```APIDOC
## Get Tone Numbers

### Get tone numbers with spaces
```js
import { pinyin } from 'pinyin-pro';
pinyin('汉语拼音', { pattern: 'num' }); // '4 3 1 1'
```

### Get tone numbers as an array
```js
import { pinyin } from 'pinyin-pro';
pinyin('汉语拼音', { pattern: 'num', type: 'array' }); // ["4", "3", "1", "1"]
```
```

--------------------------------

### Get Finals

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.6.x.md

Examples for extracting the final vowel sound of Pinyin, with options for tone marks and output format.

```APIDOC
## Get Finals

### Basic Usage
```javascript
import { pinyin } from 'pinyin-pro';

// Get finals with tone marks
pinyin('汉语拼音', { pattern: 'final' }); // 'àn ǔ īn īn'

// Get finals without tone marks
pinyin('汉语拼音', { pattern: 'final', toneType: 'none' }); // 'an u in in'

// Get finals with tone numbers
pinyin('汉语拼音', { pattern: 'final', toneType: 'num' }); // 'an4 u3 in1 in1'

// Get finals as an array with tone marks
pinyin('汉语拼音', { pattern: 'final', type: 'array' }); // ["àn", "ǔ", "īn", "īn"]

// Get finals as an array without tone marks
pinyin('汉语拼音', { pattern: 'final', toneType: 'none', type: 'array' }); // ["an", "u", "in", "in"]

// Get finals as an array with tone numbers
pinyin('汉语拼音', { pattern: 'final', toneType: 'num', type: 'array' }); // ['an4', 'u3', 'in1', 'in1']
```
```

--------------------------------

### Get Pinyin as an array

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.5.x.md

Shows how to obtain Pinyin in an array format instead of a string. This can be useful for further processing.

```javascript
import { pinyin } from 'pinyin-pro';

// 获取数组形式带音调拼音
pinyin('汉语拼音', { type: 'array' }); // ["hàn", "yǔ", "pīn", "yīn"]
// 获取数组形式不带声调的拼音
pinyin('汉语拼音', { toneType: 'none', type: 'array' }); // ["han", "yu", "pin", "yin"]
// 获取数组形式声调转换为数字后缀的拼音
pinyin('汉语拼音', { toneType: 'num', type: 'array' }); // ["han4", "yu3", "pin1", "yin1"]
```

--------------------------------

### Surname Mode

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.6.x.md

Examples of using the surname mode for more accurate Pinyin conversion of names.

```APIDOC
## Surname Mode

### Basic Usage
```javascript
import { pinyin } from 'pinyin-pro';

// Get Pinyin in surname mode
pinyin('曾国藩', { mode: 'surname' }); // 'zēng guó fān'

// Get Pinyin in surname mode as an array
pinyin('曾国藩', { mode: 'surname', type: 'array' }); // ['zēng', 'guó', 'fān']
```
```

--------------------------------

### Generate HTML with Pinyin

Source: https://github.com/zh-lx/pinyin-pro/blob/main/README.md

Provides an example of generating an HTML string where Chinese characters are annotated with their pinyin.

```javascript
import { html } from "pinyin-pro";

// 带拼音汉字的 HTML 字符串
html("汉语拼音");
/*
<span class="py-result-item">
<ruby>
    <span class="py-chinese-item">汉</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">hàn</rt>
    <rp>)</rp>
</ruby>
</span>
<span class="py-result-item">
<ruby>
    <span class="py-chinese-item">语</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">yǔ</rt>
    <rp>)</rp>
</ruby>
</span>
*/
```

--------------------------------

### Get Initials

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.7.x.md

Extracts the initial consonant sound (声母) from Pinyin for Chinese characters.

```APIDOC
## Get Initials

### Description
Extracts the initial consonant sound (声母) from Pinyin for Chinese characters.

### Method
`pinyin(word, options)`

### Parameters
- **word** (string): Required. The Chinese text to convert to Pinyin.
- **options** (object): Optional. Configuration object.
  - **pattern** (string): Set to `initial` to get initials.
  - **type** (string): Optional. Specifies the output format. Possible values: `string` (default), `array`.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get initials
pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'

// Get initials as an array
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```
```

--------------------------------

### Get Tones as an Array

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.8.x.md

Retrieve the tone numbers as an array of strings by setting `pattern` to 'num' and `type` to 'array'.

```javascript
// 获取数组形式音调
pinyin('汉语拼音', { pattern: 'num', type: 'array' }); // ["4", "3", "1", "1"]
```

--------------------------------

### 获取音调 (Get Tones)

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.9.x.md

Retrieves Pinyin with numerical tone indicators. Supports returning tones as a string or an array.

```APIDOC
## 获取音调 (Get Tones)

### Description
Retrieves Pinyin with numerical tone indicators. Supports returning tones as a string or an array.

### Method
`pinyin(text: string, options?: object)`

### Parameters
#### Options
- **pattern** (string) - Required - Set to 'num' to get numerical tones.
- **type** (string) - Optional - Set to 'array' to get tones as an array.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get tones as a string
pinyin('汉语拼音', { pattern: 'num' });

// Get tones as an array
pinyin('汉语拼音', { pattern: 'num', type: 'array' });
```

### Response Example
```json
// String output: '4 3 1 1'
// Array output: ["4", "3", "1", "1"]
```
```

--------------------------------

### Get Initials of Pinyin as an Array

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.0.x.md

Obtain the initial consonant sounds of each syllable as an array of strings. This format is convenient for further processing.

```javascript
import { pinyin } from 'pinyin-pro';

// 获取数组形式声母
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```

--------------------------------

### Get Initials

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.5.x.md

Retrieves the initial consonants (声母) of Pinyin for Chinese characters. Supports string and array output formats.

```APIDOC
## Get Initials

### Description
Retrieves the initial consonants (声母) of Pinyin for Chinese characters. Supports string and array output formats.

### Method Signature
`pinyin(word: string, options: { pattern: 'initial', type?: 'string' | 'array' }): string | string[]`

### Parameters
- **word** (string): Required. The Chinese text to convert to Pinyin initials.
- **options** (object): Required. Configuration for output format.
  - **pattern** (string): Must be 'initial'.
  - **type** (string): Optional. Specifies the output type. Possible values: 'string' (default), 'array'.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get initials
pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'

// Get initials as an array
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```
```

--------------------------------

### Getting Finals (韵母)

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.4.x.md

Demonstrates how to extract only the final vowel sound from Chinese Pinyin, with options for tone marks and output format.

```APIDOC
## Get Finals

### Get finals with tone marks
```js
import { pinyin } from 'pinyin-pro';
pinyin('汉语拼音', { pattern: 'final' }); // 'àn ǔ īn īn'
```

### Get finals without tone marks
```js
pinyin('汉语拼音', { pattern: 'final', toneType: 'none' }); // 'an u in in'
```

### Get finals with numeric tone suffixes
```js
pinyin('汉语拼音', { pattern: 'final', toneType: 'num' }); // 'an4 u3 in1 in1'
```

### Get finals as an array with tone marks
```js
pinyin('汉语拼音', { pattern: 'final', type: 'array' }); // ["àn", "ǔ", "īn", "īn"]
```

### Get finals as an array without tone marks
```js
pinyin('汉语拼音', { pattern: 'final', toneType: 'none', type: 'array' }); // ["an", "u", "in", "in"]
```

### Get finals as an array with numeric tone suffixes
```js
pinyin('汉语拼音', { pattern: 'final', toneType: 'num', type: 'array' }); // ['an4', 'u3', 'in1', 'in1']
```
```

--------------------------------

### Get Tone Numbers as an Array

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.0.x.md

Obtain the tone numbers for each syllable as an array of strings. This provides a structured list of the tones.

```javascript
import { pinyin } from 'pinyin-pro';

// 获取数组形式音调
pinyin('汉语拼音', { pattern: 'num', type: 'array' }); // ["4", "3", "1", "1"]
```

--------------------------------

### 获取单个字的多音 (Get Multi-Pronunciation)

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.9.x.md

Retrieves all possible Pinyin pronunciations for a single Chinese character. This mode is only effective for single characters.

```APIDOC
## 获取单个字的多音 (Get Multi-Pronunciation)

### Description
Retrieves all possible Pinyin pronunciations for a single Chinese character. This mode is only effective for single characters.

### Method
`pinyin(text: string, options?: object)`

### Parameters
#### Options
- **multiple** (boolean) - Required - Set to `true` to enable multi-pronunciation mode.
- **type** (string) - Optional - Set to 'array' to get results as an array.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get multi-pronunciations as a string
pinyin('好', { multiple: true });

// Get multi-pronunciations as an array
pinyin('好', { multiple: true, type: 'array' });
```

### Response Example
```json
// String output: 'hǎo hào'
// Array output: ["hǎo", "hào"]
```
```

--------------------------------

### Get Pinyin with different tone types

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.5.x.md

Demonstrates how to retrieve Pinyin with different tone representations: symbol, none, or number suffix. The default is symbol.

```javascript
import { pinyin } from 'pinyin-pro';

// 获取带音调拼音
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
// 获取不带声调的拼音
pinyin('汉语拼音', { toneType: 'none' }); // 'han yu pin yin'
// 获取声调转换为数字后缀的拼音
pinyin('汉语拼音', { toneType: 'num' }); // 'han4 yu3 pin1 yin1'
```

--------------------------------

### Get Initial (Consonant)

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.8.x.md

This function retrieves the initial consonant of the Pinyin for a given Chinese word or sentence. It supports outputting as a string or an array.

```APIDOC
## Get Initial

### Description
Retrieves the initial consonant of the Pinyin for a given Chinese word or sentence.

### Method
`pinyin(word, options)`

### Parameters
- **word** (string) - Required - The Chinese word or sentence to convert.
- **options** (object) - Optional - Configuration object.
  - **pattern** (string) - Must be set to `initial`.
  - **type** (string) - Optional - Output result type. Possible values: `string`, `array`. Defaults to `string`.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get initials
pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'

// Get initials as an array
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```
```

--------------------------------

### Get Pinyin as an Array with Tones

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.8.x.md

Retrieve pinyin as an array of strings, with each string containing the tone symbol. Set `type` to 'array'.

```javascript
// 获取数组形式带音调拼音
pinyin('汉语拼音', { type: 'array' }); // ["hàn", "yǔ", "pīn", "yīn"]
```

--------------------------------

### Get Multiple Pronunciations as an Array

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.0.x.md

Retrieve all possible pinyin pronunciations for a single polyphonic character as an array of strings. This provides a structured list of all readings.

```javascript
import { pinyin } from 'pinyin-pro';

// 获取数组形式多音
pinyin('好', { multiple: true, type: 'array' }); // ["hǎo", "hào"]
```

--------------------------------

### Get Pinyin

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.9.x.md

This section covers how to retrieve Pinyin for Chinese text, with options for tone marks, numerical tones, and output as a string or array.

```APIDOC
## Get Pinyin

### Description
This function retrieves Pinyin for Chinese text. It supports various options for tone representation and output format.

### Method Signature
`pinyin(word, options)`

### Parameters
- **word** (string): Required. The Chinese text to convert to Pinyin.
- **options** (object): Optional. Configuration object for output format.
  - **toneType** (string): Optional. Specifies the tone format. Possible values: `symbol` (default), `none`, `num`.
  - **type** (string): Optional. Specifies the output format. Possible values: `string` (default), `array`.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get Pinyin with tone marks (default)
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'

// Get Pinyin without tones
pinyin('汉语拼音', { toneType: 'none' }); // 'han yu pin yin'

// Get Pinyin with numerical tones
pinyin('汉语拼音', { toneType: 'num' }); // 'han4 yu3 pin1 yin1'

// Get Pinyin as an array with tone marks
pinyin('汉语拼音', { type: 'array' }); // ["hàn", "yǔ", "pīn", "yīn"]

// Get Pinyin as an array without tones
pinyin('汉语拼音', { toneType: 'none', type: 'array' }); // ["han", "yu", "pin", "yin"]

// Get Pinyin as an array with numerical tones
pinyin('汉语拼音', { toneType: 'num', type: 'array' }); // ['han4', 'yu3', 'pin1', 'yin1']
```
```

--------------------------------

### Importing and Basic Usage

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.6.x.md

Demonstrates how to import the `pinyin` function and use it for basic Pinyin conversion.

```APIDOC
## Importing pinyin-pro

### ESModule
```javascript
import { pinyin } from 'pinyin-pro';
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
```

### CommonJS
```javascript
const { pinyin } = require('pinyin-pro');
pinyin('汉语拼son'); // 'hàn yǔ pīn yīn'
```

### Browser Script
```html
<script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@latest/dist/pinyin-pro.js"></script>
<script>
  var { pinyin } = pinyinPro;
  pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
</script>
```
```

--------------------------------

### Importing and Basic Usage

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.4.x.md

Demonstrates how to import the pinyin function and use it for basic Pinyin conversion with different tone types and output formats.

```APIDOC
## Import pinyin function

ESModule:
```javascript
import { pinyin } from 'pinyin-pro';
```

commonjs:
```javascript
const { pinyin } = require('pinyin-pro');
```

Browser script:
```html
<script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@latest/dist/pinyin-pro.js"></script>
<script>
  var { pinyin } = pinyinPro;
</script>
```

## Basic Pinyin Conversion

### Get Pinyin with tone marks
```js
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
```

### Get Pinyin without tone marks
```js
pinyin('汉语拼音', { toneType: 'none' }); // 'han yu pin yin'
```

### Get Pinyin with numeric tone suffixes
```js
pinyin('汉语拼音', { toneType: 'num' }); // 'han4 yu3 pin1 yin1'
```

### Get Pinyin as an array with tone marks
```js
pinyin('汉语拼音', { type: 'array' }); // ["hàn", "yǔ", "pīn", "yīn"]
```

### Get Pinyin as an array without tone marks
```js
pinyin('汉语拼音', { toneType: 'none', type: 'array' }); // ["han", "yu", "pin", "yin"]
```

### Get Pinyin as an array with numeric tone suffixes
```js
pinyin('汉语拼son', { toneType: 'num', type: 'array' }); // ['han4', 'yu3', 'pin1', 'yin1']
```
```

--------------------------------

### Importing the Library

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.0.x.md

Demonstrates how to import the pinyin function from the pinyin-pro library for use in different module systems (Browser, ESM, CommonJS).

```APIDOC
## Importing

### Browser Script
```html
<!-- Import a specific version, e.g., 3.3.0 -->
<!-- <script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@3.3.0/dist/pinyin-pro.js"></script> -->
<!-- Import the latest version -->
<script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@latest/dist/pinyin-pro.js"></script>
<script>
  var { pinyin } = pinyinPro;
  pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
</script>
```

### ESM Import
```javascript
import { pinyin } from 'pinyin-pro';
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
```

### CommonJS Import
```javascript
const { pinyin } = require('pinyin-pro');
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
```
```

--------------------------------

### Get Tone Numbers

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.7.x.md

Extracts the tone number for each Pinyin syllable in the Chinese text.

```APIDOC
## Get Tone Numbers

### Description
Extracts the tone number for each Pinyin syllable in the Chinese text.

### Method
`pinyin(word, options)`

### Parameters
- **word** (string): Required. The Chinese text to convert to Pinyin.
- **options** (object): Optional. Configuration object.
  - **pattern** (string): Set to `num` to get tone numbers.
  - **type** (string): Optional. Specifies the output format. Possible values: `string` (default), `array`.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get tone numbers
pinyin('汉语拼音', { pattern: 'num' }); // '4 3 1 1'

// Get tone numbers as an array
pinyin('汉语拼音', { pattern: 'num', type: 'array' }); // ["4", "3", "1", "1"]
```
```

--------------------------------

### Import pinyin-pro in Browser (specific version)

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.9.x.md

Include a specific version of pinyin-pro using a script tag in the browser. Access the pinyin function from the global pinyinPro object.

```html
<!--引入某个版本，如3.5.0版本-->
<!-- <script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@3.5.0/dist/pinyin-pro.js"></script> -->
```

--------------------------------

### Include pinyin-pro in Browser

Source: https://github.com/zh-lx/pinyin-pro/blob/main/README.md

Include the pinyin-pro library using a script tag for browser-based projects.

```html
<script src="https://unpkg.com/pinyin-pro"></script>
```

--------------------------------

### Import pinyin-pro via script tag

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.5.x.md

Include the pinyin-pro library in your HTML using a script tag. You can link to a specific version or the latest version from a CDN.

```html
<!--引入某个版本，如3.5.0版本-->
<!-- <script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@3.5.0/dist/pinyin-pro.js"></script> -->
<!--引入最新版本-->
<script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@latest/dist/pinyin-pro.js"></script>
<script>
  var { pinyin } = pinyinPro;
  pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
</script>
```

--------------------------------

### Get Initials as an Array

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.8.x.md

Retrieve the initials of Chinese characters as an array of strings by setting `type` to 'array'.

```javascript
// 获取数组形式声母
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```

--------------------------------

### Import pinyin-pro via script tag

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.4.x.md

Include the pinyin-pro library in your HTML using a script tag from a CDN. The latest version is linked by default.

```html
<script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@latest/dist/pinyin-pro.js"></script>
<script>
  var { pinyin } = pinyinPro;
  pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
</script>
```

--------------------------------

### Get Pinyin tones

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.5.x.md

Extracts the tone number for each Pinyin syllable. The output can be a string of numbers or an array.

```javascript
import { pinyin } from 'pinyin-pro';

// 获取音调
pinyin('汉语拼音', { pattern: 'num' }); // '4 3 1 1'
// 获取数组形式音调
pinyin('汉语拼音', { pattern: 'num', type: 'array' }); // ["4", "3", "1", "1"]
```

--------------------------------

### Surname Mode

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.4.x.md

Demonstrates how to use the 'surname' mode for more accurate Pinyin conversion of Chinese names.

```APIDOC
## Surname Mode

Use the `mode: 'surname'` option for more accurate Pinyin recognition of Chinese surnames.

```js
import { pinyin } from 'pinyin-pro';

pinyin('长风', { mode: 'surname' }); // 'cháng fēng'
pinyin('长风', { mode: 'surname', type: 'array' }); // ["cháng", "fēng"]
```
```

--------------------------------

### Browser Script Import for pinyin-pro

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.0.x.md

Include the pinyin-pro library in a browser environment using a script tag. You can link to a specific version or the latest version from a CDN.

```html
<!--引入某个版本，如3.3.0版本-->
<!-- <script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@3.3.0/dist/pinyin-pro.js"></script> -->
<!--引入最新版本-->
<script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@latest/dist/pinyin-pro.js"></script>
<script>
  var { pinyin } = pinyinPro;
  pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
</script>
```

--------------------------------

### Import pinyin-pro with ESM

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.7.x.md

Import the 'pinyin' function from the 'pinyin-pro' library using dynamic import for ES Modules.

```javascript
import('pinyin-pro').then((exports) => {
  exports.pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
});
```

--------------------------------

### Get Tones

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.5.x.md

Retrieves the tone numbers for Pinyin of Chinese characters. Supports string and array output formats.

```APIDOC
## Get Tones

### Description
Retrieves the tone numbers for Pinyin of Chinese characters. Supports string and array output formats.

### Method Signature
`pinyin(word: string, options: { pattern: 'num', type?: 'string' | 'array' }): string | string[]`

### Parameters
- **word** (string): Required. The Chinese text to get Pinyin tones from.
- **options** (object): Required. Configuration for output format.
  - **pattern** (string): Must be 'num'.
  - **type** (string): Optional. Specifies the output type. Possible values: 'string' (default), 'array'.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get tones
pinyin('汉语拼音', { pattern: 'num' }); // '4 3 1 1'

// Get tones as an array
pinyin('汉语拼音', { pattern: 'num', type: 'array' }); // ["4", "3", "1", "1"]
```
```

--------------------------------

### Get Finals

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.7.x.md

Extracts the final vowel sound (韵母) from Pinyin for Chinese characters, with options for tone type.

```APIDOC
## Get Finals

### Description
Extracts the final vowel sound (韵母) from Pinyin for Chinese characters, with options for tone type and output format.

### Method
`pinyin(word, options)`

### Parameters
- **word** (string): Required. The Chinese text to convert to Pinyin.
- **options** (object): Optional. Configuration object.
  - **pattern** (string): Set to `final` to get finals.
  - **toneType** (string): Optional. Specifies the tone format. Possible values: `symbol` (default), `num`, `none`.
  - **type** (string): Optional. Specifies the output format. Possible values: `string` (default), `array`.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get finals with tones
pinyin('汉语拼音', { pattern: 'final' }); // 'àn ǔ īn īn'

// Get finals without tones
pinyin('汉语拼音', { pattern: 'final', toneType: 'none' }); // 'an u in in'

// Get finals with numeric tones
pinyin('汉语拼音', { pattern: 'final', toneType: 'num' }); // 'an4 u3 in1 in1'

// Get finals as an array with tones
pinyin('汉语拼音', { pattern: 'final', type: 'array' }); // ["àn", "ǔ", "īn", "īn"]

// Get finals as an array without tones
pinyin('汉语拼音', { pattern: 'final', toneType: 'none', type: 'array' }); // ["an", "u", "in", "in"]

// Get finals as an array with numeric tones
pinyin('汉语拼音', { pattern: 'final', toneType: 'num', type: 'array' }); // ['an4', 'u3', 'in1', 'in1']
```
```

--------------------------------

### Import pinyin-pro using ESModule

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.4.x.md

Import the pinyin function from the pinyin-pro library in ESModule-compatible JavaScript environments.

```javascript
import { pinyin } from 'pinyin-pro';
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
```

--------------------------------

### Get Initials

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.9.x.md

This section explains how to extract only the initials of Pinyin for Chinese text, with options for string or array output.

```APIDOC
## Get Initials

### Description
This function extracts the initial consonant sound of Pinyin for Chinese text.

### Method Signature
`pinyin(word, options)`

### Parameters
- **word** (string): Required. The Chinese text to convert to Pinyin initials.
- **options** (object): Optional. Configuration object.
  - **pattern** (string): Must be set to `initial` to get initials.
  - **type** (string): Optional. Specifies the output format. Possible values: `string` (default), `array`.

### Request Example
```javascript
import { pinyin } from 'pinyin-pro';

// Get Pinyin initials as a string
pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'

// Get Pinyin initials as an array
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```
```

--------------------------------

### Get pinyin with tone symbols

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.4.x.md

Retrieve the pinyin for a Chinese string with standard tone symbols. This is the default behavior.

```javascript
import { pinyin } from 'pinyin-pro';

// 获取带音调拼音
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
```

--------------------------------

### Get initials of Pinyin

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.5.x.md

Extracts the initial consonant sound (声母) of each Pinyin syllable. The output can be a string or an array.

```javascript
import { pinyin } from 'pinyin-pro';

// 获取声母
pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'
// 获取数组形式声母
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
```

--------------------------------

### Get Pinyin with Tone Symbols

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.7.x.md

Converts Chinese characters to Pinyin with standard tone symbols. This is the default behavior.

```javascript
import { pinyin } from 'pinyin-pro';

pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
```

--------------------------------

### Match Text with Pinyin

Source: https://github.com/zh-lx/pinyin-pro/blob/main/README.md

Shows how to match Chinese text against pinyin using different matching strategies like first letter, full pinyin, or mixed.

```javascript
import { match } from "pinyin-pro";

// 支持首字母匹配
match("中文拼音", "zwp"); // [0, 1, 2]

// 支持全拼匹配
match("中文拼音", "zhongwenpin"); // [0, 1, 2]

// 支持混合匹配
match("中文拼音", "zhongwp"); // [0, 1, 2]
```

--------------------------------

### Get Pinyin with Numbered Tones

Source: https://github.com/zh-lx/pinyin-pro/blob/main/docs/3.8.x.md

Extract pinyin with tone numbers appended to each syllable by setting `toneType` to 'num'.

```javascript
// 获取声调转换为数字后缀的拼音
pinyin('汉语拼音', { toneType: 'num' }); // 'han4 yu3 pin1 yin1'
```
Tokens:
Raw