match v3.15.0+

Using match api to match Chinese text string with pinyin string.

Example

Basic Use

If Pinyin matches text, return the indexes of the matching text.

import { match } from 'pinyin-pro';

match('汉语拼音', 'hanyupinyin'); // [0, 1, 2, 3]

import { match } from 'pinyin-pro';

match('汉语拼音', 'hanyupinyin'); // [0, 1, 2, 3]

Continuous

Using the continuous attribute to specify whether the matching Chinese indexes are continuous is considered a successful match (the default value is false, which means continuous matching is not required):

import { match } from 'pinyin-pro';

match('汉语拼音', 'hanpin'); // [0, 2]

match('汉语拼音', 'hanpin', { continuous: true }); // null

import { match } from 'pinyin-pro';

match('汉语拼音', 'hanpin'); // [0, 2]

match('汉语拼音', 'hanpin', { continuous: true }); // null

Precision

The precision attribute can be used to control the accuracy of Chinese character and Pinyin matching：

import { match } from 'pinyin-pro';

// 默认首字母匹配算匹配成功
match('中文拼音', 'zwpy'); // [0, 1, 2, 3]

// every 需要每一个字符都匹配成功
match('中文拼音', 'zwpy', { precision: 'every' }); // null
match('中文拼音', 'zhongwenpinyin', { precision: 'every' }); // [0, 1, 2, 3]

// start 只要开头任意个字母匹配就算匹配成功
match('中文拼音', 'zhwpy', { precision: 'start' }); // [0, 1, 2, 3]
match('中文拼音', 'zhwpy'); // null

// any 任意有一个字母匹配就算匹配成功
match('中文拼音', 'ongwpy', { precision: 'any' }); // [0, 1, 2, 3]
match('中文拼音', 'ongwpy'); // null

import { match } from 'pinyin-pro';

// 默认首字母匹配算匹配成功
match('中文拼音', 'zwpy'); // [0, 1, 2, 3]

// every 需要每一个字符都匹配成功
match('中文拼音', 'zwpy', { precision: 'every' }); // null
match('中文拼音', 'zhongwenpinyin', { precision: 'every' }); // [0, 1, 2, 3]

// start 只要开头任意个字母匹配就算匹配成功
match('中文拼音', 'zhwpy', { precision: 'start' }); // [0, 1, 2, 3]
match('中文拼音', 'zhwpy'); // null

// any 任意有一个字母匹配就算匹配成功
match('中文拼音', 'ongwpy', { precision: 'any' }); // [0, 1, 2, 3]
match('中文拼音', 'ongwpy'); // null

Space

Use the space attribute to control whether the spaces don't participate in matching:

import { match } from 'pinyin-pro';

// 默认不参与匹配
match('汉语拼音', 'han yupinyin'); // [0, 1, 2, 3]

match('汉语拼音', 'han yupinyin', { space: 'preserve' }); // null

import { match } from 'pinyin-pro';

// 默认不参与匹配
match('汉语拼音', 'han yupinyin'); // [0, 1, 2, 3]

match('汉语拼音', 'han yupinyin', { space: 'preserve' }); // null

lastPrecision

The lastPrecision attribute can be used to control the accuracy of matching the last Chinese character with Pinyin. By default, when the precision is any the lastPrecision is any; Otherwise, lastPrecision is start'.

import { match } from 'pinyin-pro';

// default
match('汉语拼音', 'hanyupiny'); // [1, 2, 3, 4]

// specify lastPrecision
match('汉语拼音', 'hanyupiny', { lastPrecision: 'every' }); // null

import { match } from 'pinyin-pro';

// default
match('汉语拼音', 'hanyupiny'); // [1, 2, 3, 4]

// specify lastPrecision
match('汉语拼音', 'hanyupiny', { lastPrecision: 'every' }); // null

Polyphonic Matching

For polyphonic characters, as long as one of the Pinyins matches, the matching is considered successful:

import { match } from 'pinyin-pro';

match('会计', 'kuaiji'); // [0, 1]
match('会计', 'huiji'); // [0, 1]

import { match } from 'pinyin-pro';

match('会计', 'kuaiji'); // [0, 1]
match('会计', 'huiji'); // [0, 1]

v match ü v3.25.0+

The v attribute can be used to allow using v to match ü:

import { match } from 'pinyin-pro';

match('吕布', 'lvbu'); // [0, 1]

import { match } from 'pinyin-pro';

match('吕布', 'lvbu'); // [0, 1]

API

Function

import { match } from 'pinyin-pro';

interface MatchOptions {
  precision?: 'first' | 'start' | 'every' | 'any';
  continuous?: boolean;
  space?: 'ignore' | 'preserve';
  lastPrecision?: 'first' | 'start' | 'every' | 'any';
  v?: boolean; // v3.25.0+
}

function match(text: string, pinyin: string， options?: MatchOptions): number[] | null; // 匹配成功返回匹配汉字对应下标数组; 不成功返回 null

import { match } from 'pinyin-pro';

interface MatchOptions {
  precision?: 'first' | 'start' | 'every' | 'any';
  continuous?: boolean;
  space?: 'ignore' | 'preserve';
  lastPrecision?: 'first' | 'start' | 'every' | 'any';
  v?: boolean; // v3.25.0+
}

function match(text: string, pinyin: string， options?: MatchOptions): number[] | null; // 匹配成功返回匹配汉字对应下标数组; 不成功返回 null

Parameters

text (required)：string, Chinese text to match
pinyin (required)：string, Pinyin to match
options (optional): object, the configuration of matching rules, more specific information is shown in the table below：

Attribute	Type	Description	Optional Values	Detail	Default Value
precision	string	matching accuracy	first	matching is considered successful when the initial letter or full pinyin is equal to the current pinyin	first
			start	starting with the current pinyin is considered a successful match
			every	full Pinyin and current Pinyin are strictly equal in order to be considered a successful match
			any	containing all characters of the current pinyin are considered as successful matches
continuous	boolean	Whether the matching Chinese indexes need to be continuous in order to be considered successful	true	not required	false
continuous	boolean		false	required	false
space	string	handling of spaces in Chinese characters and pinyin during matching	ignore	ignore	ignore
space	string		preserve	preserve	ignore
lastPrecision	string	the accuracy of the last character matching	first	Matching is considered successful when the initial letter or full pinyin is equal to the current pinyin	By default, when the `precision` is `any`, `lastPrecision` is `any`; Otherwise `lastPrecision` is `start`
			start	starting with the current pinyin is considered a successful match
			every	full Pinyin and current Pinyin are strictly equal in order to be considered a successful match
			any	containing all characters of the current pinyin are considered as successful matches
v	boolean	Whether to allow using `v` to match `ü`	true	allow using `v` to match `ü`	false
v	boolean	Whether to allow using `v` to match `ü`	false	not allow using `v` to match `ü`	false

match v3.15.0+ ​

Example ​

Basic Use ​

Continuous ​

Precision ​

Space ​

lastPrecision ​

Polyphonic Matching ​

v match ü v3.25.0+ ​

API ​

Function ​

Parameters ​