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
```