0
# Core Conversion
1

2
Main Pinyin conversion functionality providing Chinese character to Pinyin romanization with configurable styles, modes, and intelligent phrase matching.
3

4
## Capabilities
5

6
### Main Conversion Function
7

8
Converts Chinese characters to Pinyin with comprehensive configuration options.
9

10
```typescript { .api }
11
/**
12
 * Convert Chinese characters to Pinyin
13
 * @param hans - Chinese text to convert
14
 * @param options - Conversion configuration options
15
 * @returns Array of Pinyin arrays, each sub-array contains Pinyin for one character/phrase
16
 */
17
function pinyin(hans: string, options?: IPinyinOptions): string[][];
18

19
interface IPinyinOptions {
20
  /** Pinyin output style - controls tone marks, casing, etc. */
21
  style?: IPinyinStyle;
22
  /** Conversion mode - normal or surname-optimized */
23
  mode?: IPinyinMode;
24
  /** Text segmentation library for phrase recognition */
25
  segment?: IPinyinSegment | boolean;
26
  /** Enable multiple pronunciations for polyphonic characters */
27
  heteronym?: boolean;
28
  /** Group phrase Pinyin together instead of character-by-character */
29
  group?: boolean;
30
  /** Return all possible pronunciation combinations in compact form */
31
  compact?: boolean;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import pinyin from "pinyin";
39

40
// Basic character conversion
41
console.log(pinyin("你好"));
42
// Result: [["nǐ"], ["hǎo"]]
43

44
// Multiple pronunciation support
45
console.log(pinyin("中", { heteronym: true }));
46
// Result: [["zhōng", "zhòng"]]
47

48
// Different output styles
49
console.log(pinyin("你好", { style: "tone2" }));
50
// Result: [["ni3"], ["hao3"]]
51

52
console.log(pinyin("你好", { style: "normal" }));
53
// Result: [["ni"], ["hao"]]
54

55
// Segmentation for phrase accuracy
56
console.log(pinyin("北京大学", { segment: true }));
57
// Result: [["běi"], ["jīng"], ["dà"], ["xué"]]
58

59
// Grouped phrase output
60
console.log(pinyin("北京大学", { segment: true, group: true }));
61
// Result: [["běijīng"], ["dàxué"]]
62

63
// Compact pronunciation combinations
64
console.log(pinyin("你好吗", { heteronym: true, compact: true }));
65
// Result: [["nǐhǎoma"], ["nǐhǎomá"], ["nǐhǎomǎ"], ["nǐhàoma"], ...]
66
```
67

68
### Conversion Modes
69

70
Controls how the conversion algorithm prioritizes different pronunciations.
71

72
```typescript { .api }
73
type IPinyinMode = "normal" | "surname" | "NORMAL" | "SURNAME";
74
```
75

76
**Mode Details:**
77

78
- **normal**: Standard conversion using most common pronunciations
79
- **surname**: Optimized for Chinese surnames and names, prioritizing surname pronunciations
80

81
**Usage Examples:**
82

83
```typescript
84
// Normal mode (default)
85
console.log(pinyin("华夫人"));
86
// Result: [["huá"], ["fū"], ["rén"]]
87

88
// Surname mode - better for names
89
console.log(pinyin("华夫人", { mode: "surname" }));
90
// Result: [["huà"], ["fū"], ["rén"]]
91
```
92

93
### Multi-pronunciation Handling
94

95
Support for polyphonic characters that have multiple valid pronunciations.
96

97
```typescript { .api }
98
interface IPinyinOptions {
99
  /** Enable multiple pronunciations for polyphonic characters */
100
  heteronym?: boolean;
101
}
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
// Single pronunciation (default)
108
console.log(pinyin("中"));
109
// Result: [["zhōng"]]
110

111
// Multiple pronunciations
112
console.log(pinyin("中", { heteronym: true }));
113
// Result: [["zhōng", "zhòng"]]
114

115
// Multiple characters with heteronyms
116
console.log(pinyin("中心", { heteronym: true }));
117
// Result: [["zhōng", "zhòng"], ["xīn"]]
118
```
119

120
### Phrase Grouping
121

122
Controls whether phrase Pinyin is grouped together or split character-by-character.
123

124
```typescript { .api }
125
interface IPinyinOptions {
126
  /** Group phrase Pinyin together instead of character-by-character */
127
  group?: boolean;
128
}
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
// Character-by-character (default)
135
console.log(pinyin("我喜欢你", { segment: true }));
136
// Result: [["wǒ"], ["xǐ"], ["huān"], ["nǐ"]]
137

138
// Grouped phrases
139
console.log(pinyin("我喜欢你", { segment: true, group: true }));
140
// Result: [["wǒ"], ["xǐhuān"], ["nǐ"]]
141
```
142

143
### Compact Output
144

145
Generates all possible pronunciation combinations in a compact format.
146

147
```typescript { .api }
148
interface IPinyinOptions {
149
  /** Return all possible pronunciation combinations in compact form */
150
  compact?: boolean;
151
}
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
// Normal heteronym output
158
console.log(pinyin("你好吗", { heteronym: true }));
159
// Result: [["nǐ"], ["hǎo", "hào"], ["ma", "má", "mǎ"]]
160

161
// Compact combinations
162
console.log(pinyin("你好吗", { heteronym: true, compact: true }));
163
// Result: [
164
//   ["nǐ", "hǎo", "ma"], ["nǐ", "hǎo", "má"], ["nǐ", "hǎo", "mǎ"],
165
//   ["nǐ", "hào", "ma"], ["nǐ", "hào", "má"], ["nǐ", "hào", "mǎ"]
166
// ]
167
```
168

169
## Error Handling
170

171
The function handles various input edge cases gracefully:
172

173
- **Empty string**: Returns empty array `[]`
174
- **Non-string input**: Returns empty array `[]`
175
- **Non-Chinese characters**: Returns original characters in result arrays
176
- **Mixed Chinese/non-Chinese**: Processes Chinese characters, preserves others
177

178
**Examples:**
179

180
```typescript
181
console.log(pinyin(""));           // []
182
console.log(pinyin("hello"));      // [["hello"]]
183
console.log(pinyin("你好world"));   // [["nǐ"], ["hǎo"], ["world"]]
184
```