feat(3.5.0): 支持拼音匹配功能

2026-03-13 09:51:38 +08:00 · 2022-01-02 00:13:20 +08:00
parent 6324456a14
commit f794ccd664
8 changed files with 328 additions and 27 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,9 @@
+## 3.5.0
+当前版本： 3.4.1 -> 3.5.0
+
+- 新增功能
+  - 新增 `match` api 以支持[拼音文本匹配功能](#match)
+
 ## 3.4.1

 当前版本： 3.4.0 -> 3.4.1
--- a/README.md
+++ b/README.md
@@ -10,23 +10,23 @@

 ## 特色功能

- 支持汉字、词语、句子多种格式输入获取
- 获取拼音
- 获取声母
- 获取韵母
- 获取拼音首字母
- 获取音调
- 获取多音字的多种拼音
- 支持人名姓氏模式
- 支持自定义拼音
- 支持字符串和数组两种输出形式
+- [获取汉字、词语、句子等多种格式的拼音](#pinyin)
+- [获取声母](#initial)
+- [获取韵母](#final)
+- [获取拼音首字母](#first)
+- [获取音调](#num)
+- [获取多音字的多种拼音](#multiple)
+- [支持人名姓氏模式](#surname)
+- [支持自定义拼音](#custom)
+- [支持字符串和数组两种输出形式](#pinyin)
+- [支持拼音文本匹配功能](#match)

 ## 版本更新

-当前版本： 3.4.0 -> 3.4.1
+当前版本： 3.4.1 -> 3.5.0

- 问题修复
-  修复 `pattern: 'first'` 或者 `pattern: 'initial'` 时，指定 `toneType: 'num'` 获取音调失效的问题
+- 新增功能
+  - 新增 `match` api 以支持[拼音文本匹配功能](#match)

 点击查看 [版本更新文档](./CHANGELOG.md)

@@ -49,8 +49,8 @@ yarn add pinyin-pro
 浏览器 script 引入:

 ```html
-<!--引入某个版本，如3.3.0版本-->
-<!-- <script src="https://cdn.jsdelivr.net/gh/zh-lx/pinyin-pro@3.3.0/dist/pinyin-pro.js"></script> -->
+<!--引入某个版本，如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>
@@ -90,7 +90,7 @@ pinyin('汉语拼音'); // 'hàn yǔ pīn yīn'

 ## 使用示例

-### 获取拼音
+### <a id="pinyin">获取拼音</a>

 ```js
 import { pinyin } from 'pinyin-pro';
@@ -109,7 +109,7 @@ pinyin('汉语拼音', { toneType: 'none', type: 'array' }); // ["han", "yu", "p
 pinyin('汉语拼音', { toneType: 'num', type: 'array' }); // ["han4", "yu3", "pin1", "yin1"]
 ```

-### 获取声母
+### <a id="initial">获取声母</a>

 ```js
 import { pinyin } from 'pinyin-pro';
@@ -120,7 +120,7 @@ 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';
@@ -139,7 +139,7 @@ pinyin('汉语拼音', { pattern: 'final', toneType: 'none', type: 'array' }); /
 pinyin('汉语拼音', { pattern: 'final', toneType: 'num', type: 'array' }); // ['an4', 'u3', 'in1', 'in1']
 ```

-### 获取音调
+### <a id="num">获取音调</a>

 ```js
 import { pinyin } from 'pinyin-pro';
@@ -150,7 +150,7 @@ 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';
@@ -165,7 +165,7 @@ pinyin('赵钱孙李额', { pattern: 'first', type: 'array' }); // ['z', 'q', 's
 pinyin('赵钱孙李额', { pattern: 'first', toneType: 'none'， type: 'array' }); // ['z', 'q', 's', 'l', 'e']
 ```

-### 获取单个字的多音
+### <a id="multiple">获取单个字的多音</a>

 只有单字可以获取到多音模式, 词语、句子无效。同样可以通过配置 options 选项获取数组形式、韵母等格式

@@ -205,6 +205,22 @@ customPinyin({
 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)
--- a/dist/index.js
+++ b/dist/index.js
--- a/dist/pinyin-pro.js
+++ b/dist/pinyin-pro.js
--- a/docs/3.5.x.md
+++ b/docs/3.5.x.md
@@ -0,0 +1,232 @@
+[![pinyin-pro Logo](https://i.ibb.co/26fJ5vF/pinyin-logo.png)](https://github.com/zh-lx/pinyin-pro)
+
+[![NPM version](https://img.shields.io/npm/v/pinyin-pro.svg)](https://www.npmjs.com/package/pinyin-pro)
+[![GITHUB star](https://img.shields.io/github/stars/zh-lx/pinyin-pro.svg)](https://github.com/zh-lx/pinyin-pro)
+[![travis-build](https://travis-ci.com/zh-lx/pinyin-pro.svg?branch=main)](https://travis-ci.com/github/zh-lx/pinyin-pro)
+[![NPM Downloads](https://img.shields.io/npm/dm/pinyin-pro.svg)](https://npmcharts.com/compare/pinyin-pro?minimal=true)
+[![Coverage Status](https://coveralls.io/repos/github/zh-lx/pinyin-pro/badge.svg?branch=main)](https://coveralls.io/github/zh-lx/pinyin-pro?branch=main)
+[![MIT-license](https://img.shields.io/npm/l/pinyin-pro.svg)](https://opensource.org/licenses/MIT)
+[![GITHUB-language](https://img.shields.io/github/languages/top/zh-lx/pinyin-pro.svg)](https://github.com/zh-lx/pinyin-pro)
+
+## 特色功能
+
+- [获取汉字、词语、句子等多种格式的拼音](#pinyin)
+- [获取声母](#initial)
+- [获取韵母](#final)
+- [获取拼音首字母](#first)
+- [获取音调](#num)
+- [获取多音字的多种拼音](#multiple)
+- [支持人名姓氏模式](#surname)
+- [支持自定义拼音](#custom)
+- [支持字符串和数组两种输出形式](#pinyin)
+- [支持拼音文本匹配功能](#match)
+
+## 版本更新
+
+当前版本： 3.4.1 -> 3.5.0
+
+- 新增功能
+  - 新增 `match` api 以支持[拼音文本匹配功能](#match)
+
+点击查看 [版本更新文档](./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'
+```
+
+## 参数
+
+`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 |
+
+## 使用示例
+
+### <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="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。
+
+交流及参与贡献欢迎加微信：
+
+![wechat](https://i.ibb.co/VYXW19H/QQ-20210323221842.jpg)
--- a/lib/match.ts
+++ b/lib/match.ts
@@ -26,7 +26,7 @@ export const match = (words: string, pinyin: string) => {
      break;
    }
  }
-  return result.length ? result : null;
+  return result.length && !currentPinyin ? result : null;
 };

 // 检测两个拼音最大的匹配长度
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
  "name": "pinyin-pro",
-  "version": "3.4.1",
-  "description": "汉字转拼音库。获取中文拼音、韵母、声母、声调、首字母等信息。",
+  "version": "3.5.0",
+  "description": "汉字转拼音库。获取中文拼音、韵母、声母、声调、首字母，支持拼音匹配",
  "main": "./dist/index.js",
  "typings": "./types/lib/index.d.ts",
  "scripts": {
--- a/test/dist.test.js
+++ b/test/dist.test.js
@@ -1,4 +1,4 @@
-const { pinyin, customPinyin } = require('../dist/index');
+const { pinyin, customPinyin, match } = require('../dist/index');
 const expect = require('chai').expect;

 describe('aggregate', () => {
@@ -404,3 +404,50 @@ describe('pinyinFn', () => {
    expect(result).to.be.equal(result);
  });
 });
+
+describe('match', () => {
+  it('match1', () => {
+    const result = match('欢迎使用汉语拼音', 'hy');
+    expect(result).to.deep.equal([0, 1]);
+  });
+
+  it('match2', () => {
+    const result = match('欢迎使用汉语拼音', 'yingshy');
+    expect(result).to.deep.equal([1, 2, 3]);
+  });
+
+  it('match3', () => {
+    const result = match('会计', 'kj');
+    expect(result).to.deep.equal([0, 1]);
+  });
+
+  it('match4', () => {
+    const result = match('会计', 'huij');
+    expect(result).to.deep.equal([0, 1]);
+  });
+
+  it('match5', () => {
+    const result = match('开会', 'kaiui');
+    expect(result).to.deep.equal([0, 1]);
+  });
+
+  it('match6', () => {
+    const result = match('开会', 'kaig');
+    expect(result).to.deep.equal(null);
+  });
+
+  it('match7', () => {
+    const result = match('开会', 'l');
+    expect(result).to.deep.equal(null);
+  });
+
+  it('match8', () => {
+    const result = match('汉语拼音', 'hanpin');
+    expect(result).to.deep.equal([0, 2]);
+  });
+
+  it('match9', () => {
+    const result = match('汉语拼音', 'hyupy');
+    expect(result).to.deep.equal([0, 1, 2, 3]);
+  });
+});