0
# Output Styles
1
2
Seven different Pinyin output formats providing flexibility for various use cases from tone-marked pronunciation guides to search-friendly formats.
3
4
## Capabilities
5
6
### Style Types
7
8
Complete set of supported Pinyin output styles with multiple format variations for compatibility.
9
10
```typescript { .api }
11
type IPinyinStyle =
12
// Recommended lowercase formats (consistent with output)
13
| "normal" | "tone" | "tone2" | "to3ne" | "initials" | "first_letter" | "passport"
14
// Uppercase formats (v2.x compatibility)
15
| "NORMAL" | "TONE" | "TONE2" | "TO3NE" | "INITIALS" | "FIRST_LETTER" | "PASSPORT"
16
// Numeric formats (legacy compatibility)
17
| 0 | 1 | 2 | 3 | 4 | 5 | 6;
18
```
19
20
### Style Descriptions and Examples
21
22
**1. TONE Style (Default)**
23
- **Value**: `"tone"`, `"TONE"`, `1`
24
- **Description**: Standard style with tone marks on vowels
25
- **Use Case**: Pronunciation guides, language learning
26
27
```typescript
28
pinyin("中心", { style: "tone" });
29
// Result: [["zhōng"], ["xīn"]]
30
31
pinyin("我爱你", { style: "tone" });
32
// Result: [["wǒ"], ["ài"], ["nǐ"]]
33
```
34
35
**2. TONE2 Style**
36
- **Value**: `"tone2"`, `"TONE2"`, `2`
37
- **Description**: Numeric tones (1-4) appended to Pinyin
38
- **Use Case**: Text input systems, databases
39
40
```typescript
41
pinyin("中心", { style: "tone2" });
42
// Result: [["zhong1"], ["xin1"]]
43
44
pinyin("我爱你", { style: "tone2" });
45
// Result: [["wo3"], ["ai4"], ["ni3"]]
46
```
47
48
**3. TO3NE Style**
49
- **Value**: `"to3ne"`, `"TO3NE"`, `5`
50
- **Description**: Numeric tones (1-4) inserted after initials
51
- **Use Case**: Specialized romanization systems
52
53
```typescript
54
pinyin("中心", { style: "to3ne" });
55
// Result: [["zho1ng"], ["xi1n"]]
56
57
pinyin("我爱你", { style: "to3ne" });
58
// Result: [["wo3"], ["a4i"], ["ni3"]]
59
```
60
61
**4. NORMAL Style**
62
- **Value**: `"normal"`, `"NORMAL"`, `0`
63
- **Description**: Plain Pinyin without tone marks
64
- **Use Case**: Search, sorting, text processing
65
66
```typescript
67
pinyin("中心", { style: "normal" });
68
// Result: [["zhong"], ["xin"]]
69
70
pinyin("我爱你", { style: "normal" });
71
// Result: [["wo"], ["ai"], ["ni"]]
72
```
73
74
**5. INITIALS Style**
75
- **Value**: `"initials"`, `"INITIALS"`, `3`
76
- **Description**: Consonant initials only (声母)
77
- **Use Case**: Phonetic analysis, indexing
78
79
```typescript
80
pinyin("中心", { style: "initials" });
81
// Result: [["zh"], ["x"]]
82
83
pinyin("我爱你", { style: "initials" });
84
// Result: [[""], [""], [""]] // No initials for these characters
85
86
pinyin("北京", { style: "initials" });
87
// Result: [["b"], ["j"]]
88
```
89
90
**6. FIRST_LETTER Style**
91
- **Value**: `"first_letter"`, `"FIRST_LETTER"`, `4`
92
- **Description**: First letter only
93
- **Use Case**: Abbreviations, quick indexing
94
95
```typescript
96
pinyin("中心", { style: "first_letter" });
97
// Result: [["z"], ["x"]]
98
99
pinyin("我爱你", { style: "first_letter" });
100
// Result: [["w"], ["a"], ["n"]]
101
```
102
103
**7. PASSPORT Style**
104
- **Value**: `"passport"`, `"PASSPORT"`, `6`
105
- **Description**: Uppercase without tones, ü → YU
106
- **Use Case**: Official documents, passports
107
108
```typescript
109
pinyin("中心", { style: "passport" });
110
// Result: [["ZHONG"], ["XIN"]]
111
112
pinyin("绿色", { style: "passport" });
113
// Result: [["LYU"], ["SE"]] // ü becomes YU
114
```
115
116
## Style Compatibility
117
118
### Legacy v2.x Constants
119
120
The pinyin function object exposes style constants for backward compatibility:
121
122
```typescript { .api }
123
interface IPinyin {
124
// Style constants (legacy v2.x compatibility)
125
STYLE_TONE: number; // 1
126
STYLE_TONE2: number; // 2
127
STYLE_TO3NE: number; // 5
128
STYLE_NORMAL: number; // 0
129
STYLE_INITIALS: number; // 3
130
STYLE_FIRST_LETTER: number; // 4
131
STYLE_PASSPORT: number; // 6
132
}
133
```
134
135
**Usage Examples:**
136
137
```typescript
138
import pinyin from "pinyin";
139
140
// Using legacy constants
141
pinyin("中心", { style: pinyin.STYLE_TONE2 });
142
// Same as: pinyin("中心", { style: "tone2" });
143
144
pinyin("中心", { style: pinyin.STYLE_NORMAL });
145
// Same as: pinyin("中心", { style: "normal" });
146
```
147
148
## Advanced Style Usage
149
150
### Style with Multi-pronunciation
151
152
Different styles can produce different results when combined with heteronym support:
153
154
```typescript
155
// Multiple pronunciations with tone marks
156
pinyin("中", { style: "tone", heteronym: true });
157
// Result: [["zhōng", "zhòng"]]
158
159
// Multiple pronunciations with numeric tones
160
pinyin("中", { style: "tone2", heteronym: true });
161
// Result: [["zhong1", "zhong4"]]
162
163
// Initials may deduplicate identical consonants
164
pinyin("中", { style: "initials", heteronym: true });
165
// Result: [["zh"]] // Both pronunciations have same initial
166
```
167
168
### Style with Segmentation
169
170
Styles work consistently with segmentation options:
171
172
```typescript
173
// Tone style with phrase segmentation
174
pinyin("中国人", { style: "tone", segment: true, group: true });
175
// Result: [["zhōngguó"], ["rén"]]
176
177
// Normal style for search indexing
178
pinyin("中国人", { style: "normal", segment: true });
179
// Result: [["zhong"], ["guo"], ["ren"]]
180
```
181
182
## Character-Specific Behavior
183
184
### Vowel Characters
185
186
Characters starting with vowels (a, e, o, i, u, ü) may show different patterns across styles:
187
188
```typescript
189
pinyin("爱", { style: "initials" });
190
// Result: [[""]] // No initial consonant
191
192
pinyin("爱", { style: "first_letter" });
193
// Result: [["a"]] // Vowel first letter
194
```
195
196
### Special Characters
197
198
Non-Chinese characters are passed through unchanged regardless of style:
199
200
```typescript
201
pinyin("hello中国", { style: "tone" });
202
// Result: [["hello"], ["zhōng"], ["guó"]]
203
204
pinyin("hello中国", { style: "passport" });
205
// Result: [["hello"], ["ZHONG"], ["GUO"]]
206
```