mirror of
https://github.com/zh-lx/pinyin-pro.git
synced 2026-03-13 09:51:38 +08:00
feat(3.7.0): 增加 esm 引入方式以及完善测试用例
This commit is contained in:
zh-lx
256
docs/3.7.x.md
Normal file
256
docs/3.7.x.md
Normal file
@@ -0,0 +1,256 @@
|
||||
[](https://github.com/zh-lx/pinyin-pro)
|
||||
|
||||
[](https://www.npmjs.com/package/pinyin-pro)
|
||||
[](https://github.com/zh-lx/pinyin-pro)
|
||||
[](https://travis-ci.com/github/zh-lx/pinyin-pro)
|
||||
[](https://npmcharts.com/compare/pinyin-pro?minimal=true)
|
||||
[](https://coveralls.io/github/zh-lx/pinyin-pro?branch=main)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/zh-lx/pinyin-pro)
|
||||
|
||||
## 特色功能
|
||||
|
||||
- [获取汉字、词语、句子等多种格式的拼音](#pinyin)
|
||||
- [获取声母](#initial)
|
||||
- [获取韵母](#final)
|
||||
- [获取拼音首字母](#first)
|
||||
- [获取音调](#num)
|
||||
- [获取多音字的多种拼音](#multiple)
|
||||
- [支持人名姓氏模式](#surname)
|
||||
- [支持自定义拼音](#custom)
|
||||
- [支持字符串和数组两种输出形式](#pinyin)
|
||||
- [支持拼音文本匹配功能](#match)
|
||||
|
||||
## 版本更新
|
||||
|
||||
当前版本： 3.6.2 -> 3.7.0
|
||||
|
||||
- 使用完善
|
||||
- 增加 esm 引入方式
|
||||
- 完善测试用例
|
||||
|
||||
点击查看 [版本更新文档](./CHANGELOG.md)
|
||||
|
||||
## 安装
|
||||
|
||||
npm 安装
|
||||
|
||||
```
|
||||
npm install pinyin-pro
|
||||
```
|
||||
|
||||
yarn 安装
|
||||
|
||||
```
|
||||
yarn add pinyin-pro
|
||||
```
|
||||
|
||||
## 引入
|
||||
|
||||
浏览器 script 引入:
|
||||
|
||||
```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>
|
||||
```
|
||||
|
||||
ESModule 引入：
|
||||
|
||||
```javascript
|
||||
import { pinyin } from 'pinyin-pro';
|
||||
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
|
||||
```
|
||||
|
||||
commonjs 引入：
|
||||
|
||||
```javascript
|
||||
const { pinyin } = require('pinyin-pro');
|
||||
pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
|
||||
```
|
||||
|
||||
esm 引入：
|
||||
|
||||
```javascript
|
||||
import('pinyin-pro').then((exports) => {
|
||||
exports.pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'
|
||||
});
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
`pinyin(word, options)` 接收两个参数<br>
|
||||
|
||||
- <b>word：</b>必填。String 类型，需要转化为拼音的中文
|
||||
- <b>options：</b>可选。Object 类型，用于配置各种输出形式，options 的键值配置如下：
|
||||
|
||||
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|
||||
| ----------- | ------------------------------------------------------------- | ------- | -------------------------------------- | ------ |
|
||||
| pattern | 输出的结果的信息（拼音 / 声母 / 韵母 / 音调 / 首字母） | string | pinyin / initial / final / num / first | pinyin |
|
||||
| toneType | 音调输出形式(拼音符号 / 数字 / 不加音调) | string | symbol / num / none | symbol |
|
||||
| type | 输出结果类型（字符串/数组） | string | string / array | string |
|
||||
| multiple | 输出多音字全部拼音（仅在 word 为长度为 1 的汉字字符串时生效） | boolean | true / false | false |
|
||||
| mode | 拼音查找的模式（常规模式 / 姓氏模式） | string | normal / surname | normal |
|
||||
| removeNonZh | 是否输入字符串中将非汉字的字符过滤掉 | boolean | true / false | false |
|
||||
|
||||
## 使用示例
|
||||
|
||||
### <a id="pinyin">获取拼音</a>
|
||||
|
||||
```js
|
||||
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'
|
||||
// 获取数组形式带音调拼音
|
||||
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"]
|
||||
```
|
||||
|
||||
### <a id="initial">获取声母</a>
|
||||
|
||||
```js
|
||||
import { pinyin } from 'pinyin-pro';
|
||||
|
||||
// 获取声母
|
||||
pinyin('汉语拼音', { pattern: 'initial' }); // 'h y p y'
|
||||
// 获取数组形式声母
|
||||
pinyin('汉语拼音', { pattern: 'initial', type: 'array' }); // ["h", "y", "p", "y"]
|
||||
```
|
||||
|
||||
### <a id="final">获取韵母</a>
|
||||
|
||||
```js
|
||||
import { pinyin } from 'pinyin-pro';
|
||||
|
||||
// 获取带音调韵母
|
||||
pinyin('汉语拼音', { pattern: 'final' }); // 'àn ǔ īn īn'
|
||||
// 获取不带音调韵母
|
||||
pinyin('汉语拼音', { pattern: 'final', toneType: 'none' }); // 'an u in in'
|
||||
// 获取音调为数字的韵母
|
||||
pinyin('汉语拼音', { pattern: 'final', toneType: 'num' }); // 'an4 u3 in1 in1'
|
||||
// 获取数组形式带音调韵母
|
||||
pinyin('汉语拼音', { pattern: 'final', type: 'array' }); // ["àn", "ǔ", "īn", "īn"]
|
||||
// 获取数组形式不带音调韵母
|
||||
pinyin('汉语拼音', { pattern: 'final', toneType: 'none', type: 'array' }); // ["an", "u", "in", "in"]
|
||||
// 获取数组形式音调为数字的韵母
|
||||
pinyin('汉语拼音', { pattern: 'final', toneType: 'num', type: 'array' }); // ['an4', 'u3', 'in1', 'in1']
|
||||
```
|
||||
|
||||
### <a id="num">获取音调</a>
|
||||
|
||||
```js
|
||||
import { pinyin } from 'pinyin-pro';
|
||||
|
||||
// 获取音调
|
||||
pinyin('汉语拼音', { pattern: 'num' }); // '4 3 1 1'
|
||||
// 获取数组形式音调
|
||||
pinyin('汉语拼音', { pattern: 'num', type: 'array' }); // ["4", "3", "1", "1"]
|
||||
```
|
||||
|
||||
### <a id="first">获取拼音首字母</a>
|
||||
|
||||
```js
|
||||
import { pinyin } from 'pinyin-pro';
|
||||
|
||||
// 获取拼音首字母
|
||||
pinyin('赵钱孙李额', { pattern: 'first' }); // 'z q s l é'
|
||||
// 获取不带音调拼音首字母
|
||||
pinyin('赵钱孙李额', { pattern: 'first', toneType: 'none' }); // 'z q s l e'
|
||||
// 获取数组形式拼音首字母
|
||||
pinyin('赵钱孙李额', { pattern: 'first', type: 'array' }); // ['z', 'q', 's', 'l', 'é']
|
||||
// 获取数组形式不带音调拼音首字母
|
||||
pinyin('赵钱孙李额', { pattern: 'first', toneType: 'none'， type: 'array' }); // ['z', 'q', 's', 'l', 'e']
|
||||
```
|
||||
|
||||
### <a id="multiple">获取单个字的多音</a>
|
||||
|
||||
只有单字可以获取到多音模式, 词语、句子无效。同样可以通过配置 options 选项获取数组形式、韵母等格式
|
||||
|
||||
```javascript
|
||||
import { pinyin } from 'pinyin-pro';
|
||||
|
||||
// 获取多音
|
||||
pinyin('好', { multiple: true }); // 'hǎo hào'
|
||||
// 获取数组形式多音
|
||||
pinyin('好', { multiple: true, type: 'array' }); // ["hǎo", "hào"]
|
||||
```
|
||||
|
||||
### <a id="surname">姓氏模式</a>
|
||||
|
||||
通过设置 `mode: 'surname'` 开启姓氏模式后，匹配到百家姓中的姓氏优先输出姓氏拼音
|
||||
|
||||
```javascript
|
||||
import { pinyin } from 'pinyin-pro';
|
||||
|
||||
// 不开启姓氏模式
|
||||
pinyin('我叫曾小贤'); // 'wǒ jiào céng xiǎo xián'
|
||||
|
||||
// 开启姓氏模式
|
||||
pinyin('我叫曾小贤', { mode: 'surname' }); // 'wǒ jiào zēng xiǎo xián'
|
||||
```
|
||||
|
||||
### <a id="removeNonZh">过滤非汉字字符</a>
|
||||
|
||||
通过设置 `removeNonZh: true` ，可以过滤输入字符串中的非汉字字符
|
||||
|
||||
```javascript
|
||||
import { pinyin } from 'pinyin-pro';
|
||||
|
||||
// 不开启过滤
|
||||
pinyin('汉sa语2拼音'); // 'hàn s a yǔ 2 pīn yīn'
|
||||
|
||||
// 开启过滤
|
||||
pinyin('汉sa语2拼音', { removeNonZh: true }); // 'hàn yǔ pīn yīn'
|
||||
```
|
||||
|
||||
### <a id="custom">自定义拼音</a>
|
||||
|
||||
包内部导出了 `customPinyin` 方法，支持用户自定义设置词句拼音，当中文中匹配用户自己定义的词句拼音时，优先使用用户自定义的词句拼音
|
||||
|
||||
```javascript
|
||||
import { pinyin, customPinyin } from 'pinyin-pro';
|
||||
|
||||
customPinyin({
|
||||
干一行行一行: 'gàn yī háng xíng yī háng',
|
||||
});
|
||||
pinyin('干一行行一行'); // 'gàn yī háng xíng yī háng'
|
||||
```
|
||||
|
||||
### <a id="match">拼音匹配</a>
|
||||
|
||||
包内含 `match` 方法，可以检测拼音和文本内容是否匹配，拼音支持缩写，且默认开启多音字所有读音匹配模式：
|
||||
|
||||
```javascript
|
||||
import { match } from 'pinyin-pro';
|
||||
|
||||
const matches1 = match('汉语拼音', 'hanyupinyin'); // [0, 1, 2, 3] 拼音和文本匹配，返回匹配上的文本下标
|
||||
const matches2 = match('汉语拼音', 'hanpin'); // [0, 2] 拼音和文本匹配，返回匹配上的文本下标
|
||||
const matches3 = match('汉语拼音', 'hyupy'); // [0, 1, 2, 3] 支持各种格式的拼音缩写匹配
|
||||
const matches4 = match('汉语拼音', 'lsaf'); // null，未匹配成功返回 null
|
||||
const matches5 = match('汉语拼音', 'hanyupinle'); // null，最后的 le 和音不匹配，匹配不成功，返回 null
|
||||
const matches6 = match('会计', 'kuaiji'); // [0, 1]，匹配成功，返回匹配上的文本下标
|
||||
const matches7 = match('会计', 'huiji'); // [0, 1]，多音字只要其中一个读音匹配上即算匹配成功
|
||||
```
|
||||
|
||||
## 贡献与反馈
|
||||
|
||||
参与开源贡献请参照 [pinyin-pro 贡献](./docs/contribute.md)
|
||||
|
||||
使用遇到问题或者需要功能支持欢迎提 issue。
|
||||
|
||||
交流及参与贡献欢迎加微信：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user