0
# Pinyin
1
2
Pinyin is a comprehensive Chinese character to Pinyin conversion library that enables developers to convert Chinese text into Pinyin romanization for pronunciation, search, and sorting applications. It offers intelligent phrase-based matching for accurate Pinyin conversion, supports multiple pronunciation handling for polyphonic characters, provides various Pinyin style formats, and includes basic traditional Chinese character support.
3
4
## Package Information
5
6
- **Package Name**: pinyin
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install pinyin`
10
11
## Core Imports
12
13
```typescript
14
import pinyin from "pinyin";
15
```
16
17
For individual functions:
18
19
```typescript
20
import pinyin, { compare, compact } from "pinyin";
21
import type { IPinyinOptions, IPinyinSegment, IPinyinStyle } from "pinyin";
22
```
23
24
For CommonJS:
25
26
```javascript
27
const pinyin = require("pinyin");
28
const { compare, compact } = require("pinyin");
29
```
30
31
## Basic Usage
32
33
```typescript
34
import pinyin from "pinyin";
35
36
// Basic conversion
37
console.log(pinyin("中心"));
38
// Result: [["zhōng"], ["xīn"]]
39
40
// Multi-pronunciation support
41
console.log(pinyin("中心", { heteronym: true }));
42
// Result: [["zhōng", "zhòng"], ["xīn"]]
43
44
// Different styles
45
console.log(pinyin("中心", { style: "normal" }));
46
// Result: [["zhong"], ["xin"]]
47
48
// With segmentation for better accuracy
49
console.log(pinyin("中心", { segment: true }));
50
// Result: [["zhōng"], ["xīn"]]
51
52
// Surname mode for names
53
console.log(pinyin("华夫人", { mode: "surname" }));
54
// Result: [["huà"], ["fū"], ["rén"]]
55
```
56
57
## Architecture
58
59
Pinyin is built around several key components:
60
61
- **Core Conversion Engine**: Main `pinyin()` function handling Chinese character to Pinyin conversion
62
- **Style System**: 7 different output formats from tone marks to passport-style uppercase
63
- **Mode System**: Normal and surname-specific conversion modes
64
- **Segmentation Integration**: Support for multiple word segmentation libraries
65
- **Phrase Dictionary**: Intelligent phrase matching for accurate multi-character conversion
66
- **Utility Functions**: Comparison, compacting, and array manipulation helpers
67
68
## Capabilities
69
70
### Core Conversion
71
72
Main Pinyin conversion functionality with configurable styles, modes, and options. Handles single characters, phrases, and mixed text with intelligent segmentation.
73
74
```typescript { .api }
75
function pinyin(hans: string, options?: IPinyinOptions): string[][];
76
77
interface IPinyinOptions {
78
style?: IPinyinStyle;
79
mode?: IPinyinMode;
80
segment?: IPinyinSegment | boolean;
81
heteronym?: boolean;
82
group?: boolean;
83
compact?: boolean;
84
}
85
```
86
87
[Core Conversion](./core-conversion.md)
88
89
### Output Styles
90
91
Seven different Pinyin output formats including tone marks, numeric tones, initials only, and passport-style formatting.
92
93
```typescript { .api }
94
type IPinyinStyle =
95
| "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport"
96
| "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT"
97
| 0 | 1 | 2 | 3 | 4 | 5 | 6;
98
```
99
100
[Output Styles](./output-styles.md)
101
102
### Text Segmentation
103
104
Integrated support for multiple Chinese text segmentation libraries to improve conversion accuracy for phrases and compound words.
105
106
```typescript { .api }
107
type IPinyinSegment = "nodejieba" | "segmentit" | "@node-rs/jieba" | "Intl.Segmenter";
108
```
109
110
**Note**: Segmentation is handled internally when using the `segment` option in the main `pinyin()` function.
111
112
[Text Segmentation](./text-segmentation.md)
113
114
### Utility Functions
115
116
Helper functions for comparing Chinese strings by Pinyin pronunciation and manipulating Pinyin result arrays.
117
118
```typescript { .api }
119
function compare(a: string, b: string): number;
120
function compact(arr: string[][]): string[][];
121
```
122
123
[Utility Functions](./utility-functions.md)
124
125
## Types
126
127
Core type definitions used across the package:
128
129
```typescript { .api }
130
type IPinyinMode = "normal" | "surname" | "NORMAL" | "SURNAME";
131
132
interface IPinyin {
133
(han: string, options?: IPinyinOptions): string[][];
134
compare: (a: string, b: string) => number;
135
compact: (arr: string[][]) => string[][];
136
137
// Style constants (legacy v2.x compatibility)
138
STYLE_TONE: number;
139
STYLE_TONE2: number;
140
STYLE_TO3NE: number;
141
STYLE_NORMAL: number;
142
STYLE_INITIALS: number;
143
STYLE_FIRST_LETTER: number;
144
STYLE_PASSPORT: number;
145
146
// Mode constants (legacy v2.x compatibility)
147
MODE_NORMAL: number;
148
MODE_SURNAME: number;
149
}
150
```