### Install Pinyin4NET

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Installation commands for .NET CLI and Package Manager.

```bash
# .NET CLI
dotnet add package hyjiacan.pinyin4net

# Package Manager
Install-Package hyjiacan.pinyin4net

# 直接引用
# <PackageReference Include="hyjiacan.pinyin4net" Version="4.1.0" />
```

--------------------------------

### Install NuGet Package

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Various methods to install the Pinyin4NET package.

```bash
Install-Package hyjiacan.pinyin4net
```

```bash
dotnet add package hyjiacan.pinyin4net
```

```bash
paket add hyjiacan.pinyin4net
```

```xml
<PackageReference Include="hyjiacan.pinyin4net" Version="4.1.0" />
```

--------------------------------

### Query Surname Pinyin

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Examples of using Name4Net to retrieve Pinyin for surnames.

```csharp
string firstName = "单于";
// 取出姓的拼音
string py = Name4Net.GetPinyin(firstName);
// 取出姓的拼音首字母
string py = Name4Net.GetFirstLetter(firstName);
// 取出姓的拼音(格式化后)
string py = Name4Net.GetPinyin(firstName, format);
// 取出匹配拼音的姓
string[] firstNames = Name4Net.GetHanzi("li", false);
```

--------------------------------

### Perform Pinyin Operations

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Examples of using Pinyin4Net to format, check, and convert Chinese characters.

```csharp
// 设置拼音输出格式
PinyinFormat format = PinyinFormat.WITHOUT_TONE | PinyinFormat.LOWERCASE | PinyinFormat.WITH_U_UNICODE;
char hanzi = '李';
// 判断是否是汉字
if(PinyinUtil.IsHanzi(hanzi)){
    return;
}
// 取出指定汉字的所有拼音
string[] py = Pinyin4Net.GetPinyin(hanzi);
// 取出指定汉字的所有拼音（经过格式化的）
string[] py = Pinyin4Net.GetPinyin(hanzi, format);
// 取指定汉字的唯一或者第一个拼音
Pinyin4Net.GetFirstPinyin(hanzi);
// 取指定汉字的唯一或者第一个拼音（经过格式化的）
Pinyin4Net.GetPinyin(hanzi, format);
// 根据拼音查汉字
string[] hanzi = Pinyin4Net.GetHanzi('li', true);
```

--------------------------------

### Get Surname Pinyin

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Retrieve the correct pinyin for Chinese surnames, automatically handling special pronunciations and compound surnames. Examples cover single, special, and compound surnames with and without formatting.

```csharp
using hyjiacan.py4n;

// 普通单姓
string py1 = Name4Net.GetPinyin("李");
// 结果: "li3"

// 姓氏特殊读音（"单"作为姓氏读 shàn）
string py2 = Name4Net.GetPinyin("单");
// 结果: "shan4"

// 复姓（自动用空格分隔）
string py3 = Name4Net.GetPinyin("单于");
// 结果: "chan2 yu2" (注意：复姓"单于"读 chán yú)

string py4 = Name4Net.GetPinyin("欧阳");
// 结果: "ou1 yang2"

// 带格式化参数
var format = PinyinFormat.WITH_TONE_MARK | PinyinFormat.CAPITALIZE_FIRST_LETTER | PinyinFormat.WITH_U_UNICODE;
string formatted1 = Name4Net.GetPinyin("李", format);
// 结果: "Lĭ"

string formatted2 = Name4Net.GetPinyin("单于", format);
// 结果: "Chán Yú"

string formatted3 = Name4Net.GetPinyin("吕", format);
// 结果: "Lǚ"

// 不存在的姓返回 null
string notFound = Name4Net.GetPinyin("佳");
// 结果: null
```

--------------------------------

### Query Hanzi by Pinyin

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Query Chinese characters by their pinyin. Supports exact and prefix matching. This example shows how to find characters for 'li' and 'li3'.

```csharp
using hyjiacan.py4n;

// 完全匹配：查找拼音为 "li" 的所有汉字
string[] hanzi1 = Pinyin4Net.GetHanzi("li", true);
// 结果: 包含所有读音为 li 的汉字

// 前缀匹配：查找拼音以 "li" 开头的所有汉字
string[] hanzi2 = Pinyin4Net.GetHanzi("li", false);
// 结果: 包含 li, lia, lian, liang, liao, lie, lin, ling, liu 等拼音的汉字

// 带声调的拼音查询
string[] hanzi3 = Pinyin4Net.GetHanzi("li3", true);
// 结果: 只返回三声 lǐ 的汉字

Console.WriteLine($"拼音 'li' 对应的汉字: {string.Join(", ", hanzi1.Take(10))}...");
```

--------------------------------

### Custom Pinyin Handler for Polyphonic Characters

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Use a custom handler to control polyphonic character pinyin selection for more precise conversion logic. This example demonstrates handling the polyphonic character '行' based on its context.

```csharp
using hyjiacan.py4n;

string text = "银行行长";
var format = PinyinFormat.WITHOUT_TONE | PinyinFormat.LOWERCASE;

// 自定义处理器：根据上下文选择正确的读音
string result = Pinyin4Net.GetPinyin(text, format, false, (pinyinArray, currentChar, fullText) =>
{
    // 处理"行"字的多音字问题
    if (currentChar == '行')
    {
        int index = fullText.IndexOf(currentChar);
        // "银行"中的"行"读 hang
        if (index > 0 && fullText[index - 1] == '银')
        {
            return "hang";
        }
        // "行长"中的"行"读 hang
        if (index < fullText.Length - 1 && fullText[index + 1] == '长')
        {
            return "hang";
        }
    }
    // 默认返回第一个读音
    return PinyinUtil.Format(pinyinArray[0], format);
});

Console.WriteLine(result);
// 可根据业务逻辑自定义多音字处理
```

--------------------------------

### Retrieve First Pinyin Reading

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Get the primary Pinyin reading for a character, useful when multi-tone handling is not required.

```csharp
using hyjiacan.py4n;

// 获取第一个拼音（原始格式）
string py1 = Pinyin4Net.GetFirstPinyin('传');
// 结果: "chuan2"

string py2 = Pinyin4Net.GetFirstPinyin('李');
// 结果: "li3"

// 带格式化的首个拼音
var format = PinyinFormat.WITH_TONE_MARK | PinyinFormat.LOWERCASE | PinyinFormat.WITH_U_UNICODE;
string formatted1 = Pinyin4Net.GetFirstPinyin('绿', format);
// 结果: "lǜ"

string formatted2 = Pinyin4Net.GetFirstPinyin('门', format);
// 结果: "mén"

string formatted3 = Pinyin4Net.GetFirstPinyin('按', format);
// 结果: "àn"

// 首字母大写格式
var capitalFormat = PinyinFormat.WITH_TONE_MARK | PinyinFormat.CAPITALIZE_FIRST_LETTER | PinyinFormat.WITH_U_UNICODE;
string capital = Pinyin4Net.GetFirstPinyin('李', capitalFormat);
// 结果: "Lĭ"
```

--------------------------------

### Query Surnames by Pinyin

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Query Chinese surnames by their pinyin. Supports exact and prefix matching for single and compound surnames. Examples include queries for 'li', 'chan yu', 'ou', and 'f', including 'ü' and 'v' formats.

```csharp
using hyjiacan.py4n;

// 完全匹配：拼音为 "li" 的所有姓
string[] surnames1 = Name4Net.GetHanzi("li", true);
// 结果: ["犁", "黎", "理", "礼", "李", "厉", "励", "力", "栗", "利", "郦", "历"]

// 查询复姓
string[] surnames2 = Name4Net.GetHanzi("chan yu", true);
// 结果: ["单于"]

// 前缀匹配：拼音以 "ou" 开头的姓
string[] surnames3 = Name4Net.GetHanzi("ou", false);
// 结果: ["欧", "欧阳", "偶"]

// 按声母查询：所有 "f" 开头的姓
string[] surnames4 = Name4Net.GetHanzi("f", false);
// 结果: ["法", "藩", "繁", "樊", "范", "范姜", "方", "房", "飞", "肥", ...]

// 支持 lyu 格式查询 ü 音
string[] surnames5 = Name4Net.GetHanzi("lyu", true);
// 结果: ["闾", "旅", "吕", "律"]

// v 格式也支持
string[] surnames6 = Name4Net.GetHanzi("lv", true);
// 结果: ["闾", "旅", "吕", "律"]

Console.WriteLine($"姓 'li' 的姓氏: {string.Join(", ", surnames1)}");
```

--------------------------------

### Retrieve Detailed Pinyin Array

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Get a list of PinyinItem objects for a string, providing metadata like character type and all possible readings.

```csharp
using hyjiacan.py4n;

string text = "Hi好者";
var format = PinyinFormat.None;

List<PinyinItem> items = Pinyin4Net.GetPinyinArray(text, format);

foreach (var item in items)
{
    Console.WriteLine($"字符: '{item.RawChar}', 是汉字: {item.IsHanzi}");
    if (item.IsHanzi)
    {
        Console.WriteLine($"  拼音: {string.Join(", ", item)}");
    }
}
// 输出:
// 字符: 'H', 是汉字: False
// 字符: 'i', 是汉字: False
// 字符: '好', 是汉字: True
//   拼音: hao3, hao4
// 字符: '者', 是汉字: True
//   拼音: zhe3

// PinyinItem 的 ToString() 方法
var hanziItem = items.First(i => i.IsHanzi);
string itemStr = hanziItem.ToString();
// 结果: "[hao3,hao4]" (多音字用逗号分隔)
```

--------------------------------

### Get Surname First Letter

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Obtain the first letter of a surname's pinyin. Compound surnames return space-separated first letters. This includes examples for single and compound surnames and a practical grouping application.

```csharp
using hyjiacan.py4n;

// 单姓首字母
string letter1 = Name4Net.GetFirstLetter("李");
// 结果: "l"

string letter2 = Name4Net.GetFirstLetter("张");
// 结果: "z"

// 复姓首字母（空格分隔）
string letter3 = Name4Net.GetFirstLetter("单于");
// 结果: "c y" (chán yú 的首字母)

string letter4 = Name4Net.GetFirstLetter("欧阳");
// 结果: "o y"

string letter5 = Name4Net.GetFirstLetter("司马");
// 结果: "s m"

// 不存在的姓返回 null
string notFound = Name4Net.GetFirstLetter("佳");
// 结果: null

// 实际应用：按姓氏首字母分组
var names = new[] { "李明", "张三", "王五", "欧阳修" };
var grouped = names.GroupBy(n => Name4Net.GetFirstLetter(n.Substring(0, n.Length > 2 && Name4Net.GetPinyin(n.Substring(0, 2)) != null ? 2 : 1)));
```

--------------------------------

### Update Pinyin Database

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Dynamically update or add pinyin mappings for characters. This allows handling missing characters or custom pronunciations. Examples show adding custom pinyin and replacing existing mappings.

```csharp
using hyjiacan.py4n;

// 查看原始拼音
string[] original = Pinyin4Net.GetPinyin('吃');
// 结果: ["chi1", "ji2"]

// 添加新的拼音映射（不替换原有数据）
Pinyin4Net.UpdateMap(new Dictionary<char, string[]> 
{
    { '吃', new[] { "chi1", "ji2", "custom1" } }
}, false);

// 替换原有的拼音映射
Pinyin4Net.UpdateMap(new Dictionary<char, string[]> 
{
    { '吃', new[] { "qie", "qia" } }
}, true);

string[] updated = Pinyin4Net.GetPinyin('吃');
// 结果: ["qie", "qia"]

// 批量添加自定义汉字拼音
Pinyin4Net.UpdateMap(new Dictionary<char, string[]> 
{
    { '㐀', new[] { "qiu1" } },  // 生僻字
    { '㐁', new[] { "tian3" } }
}, false);
```

--------------------------------

### Build Project

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Commands for building the project with different configurations and target frameworks.

```bash
cd hyjiacan.py4n
```

```bash
dotnet build --configuration Debug
# 或
dotnet build
```

```bash
dotnet build --configuration Release
```

```bash
dotnet build -f net40
```

--------------------------------

### Run Unit Tests

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Commands to execute unit tests for the project.

```bash
cd UnitTestProject
```

```bash
dotnet test
```

```bash
dotnet test -f net45
```

--------------------------------

### Clone Source Code

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Commands to clone the repository from GitHub or Gitee.

```bash
git clone https://github.com/hyjiacan/Pinyin4Net.git
```

```bash
git clone https://gitee.com/hyjiacan/Pinyin4Net.git
```

--------------------------------

### To-Do List

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Future development tasks for the Pinyin4Net project.

```APIDOC
## To-Do List

- Add a custom processor for the GetPinyin interface for surnames.
```

--------------------------------

### Convert Strings to Pinyin

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Convert entire strings to Pinyin with support for mixed content, casing, and multi-tone expansion.

```csharp
using hyjiacan.py4n;

string text = "JavaScript 爱好者 传说";

// 基本转换：带声调符号 + 小写
var format = PinyinFormat.WITH_TONE_MARK | PinyinFormat.LOWERCASE | PinyinFormat.WITH_U_UNICODE;
string result1 = Pinyin4Net.GetPinyin(text, format);
// 结果: "JavaScript ài hăo zhĕ  chuán shuō"

// 首字母大写格式
var capitalFormat = PinyinFormat.WITH_TONE_MARK | PinyinFormat.CAPITALIZE_FIRST_LETTER | PinyinFormat.WITH_U_UNICODE;
string result2 = Pinyin4Net.GetPinyin(text, capitalFormat);
// 结果: "JavaScript Ài Hăo Zhĕ  Chuán Shuō"

// 全大写格式
var upperFormat = PinyinFormat.WITH_TONE_MARK | PinyinFormat.UPPERCASE | PinyinFormat.WITH_U_UNICODE;
string result3 = Pinyin4Net.GetPinyin(text, upperFormat);
// 结果: "Javascript ÀI HĂO ZHĔ  CHUÁN SHUŌ"

// 大小写扩展到非拼音字符（caseSpread = true）
string result4 = Pinyin4Net.GetPinyin(text, upperFormat, true, false, false);
// 结果: "JAVASCRIPT ÀI HĂO ZHĔ  CHUÁN SHUŌ"

// 只取拼音首字母
string result5 = Pinyin4Net.GetPinyin(text, PinyinFormat.None, false, true, false);
// 结果: "JavaScript [a] [h] [z]  [c] [s]"

// 多音字取所有首字母
string result6 = Pinyin4Net.GetPinyin(text, PinyinFormat.None, false, true, true);
// 结果: "JavaScript [a] [h] [z]  [c,z] [s,y]"
```

--------------------------------

### Format Pinyin Output with PinyinFormat

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Control pinyin output formatting using bitwise combinations of PinyinFormat enum values. Note that WITH_TONE_MARK is incompatible with WITH_V, WITH_U_AND_COLON, and WITH_YU.

```csharp
using hyjiacan.py4n;

// 可用的格式选项
// PinyinFormat.None                    - 默认格式（原始拼音，如 li3）
// PinyinFormat.CAPITALIZE_FIRST_LETTER - 首字母大写
// PinyinFormat.LOWERCASE               - 全小写
// PinyinFormat.UPPERCASE               - 全大写
// PinyinFormat.WITH_U_AND_COLON        - ü 输出为 u:
// PinyinFormat.WITH_V                  - ü 输出为 v
// PinyinFormat.WITH_U_UNICODE          - ü 输出为 ü
// PinyinFormat.WITH_YU                 - ü 输出为 yu（如 lyu）
// PinyinFormat.WITH_TONE_MARK          - 带声调符号（如 lǐ）
// PinyinFormat.WITHOUT_TONE            - 不带声调（如 li）
// PinyinFormat.WITH_TONE_NUMBER        - 带声调数字（如 li3）

// 组合使用：带声调符号 + 小写 + Unicode ü
var format1 = PinyinFormat.WITH_TONE_MARK | PinyinFormat.LOWERCASE | PinyinFormat.WITH_U_UNICODE;
string py1 = Pinyin4Net.GetFirstPinyin('绿', format1);
// 结果: "lǜ"

// 组合使用：不带声调 + 全大写 + v 代替 ü
var format2 = PinyinFormat.WITHOUT_TONE | PinyinFormat.UPPERCASE | PinyinFormat.WITH_V;
string py2 = Pinyin4Net.GetFirstPinyin('绿', format2);
// 结果: "LV"

// 组合使用：首字母大写 + 不带声调
var format3 = PinyinFormat.WITHOUT_TONE | PinyinFormat.CAPITALIZE_FIRST_LETTER;
string py3 = Pinyin4Net.GetFirstPinyin('李', format3);
// 结果: "Li"

// 注意：WITH_TONE_MARK 不能与 WITH_V、WITH_U_AND_COLON、WITH_YU 同时使用
// 以下会抛出 PinyinException 异常：
// var invalidFormat = PinyinFormat.WITH_TONE_MARK | PinyinFormat.WITH_V;
```

--------------------------------

### Define Pinyin Formatting Options

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Use the PinyinFormat enum to specify how pinyin should be formatted. Combine bit flags to achieve desired output, such as capitalization, tone inclusion, or specific representations of 'ü'.

```csharp
[Flags]
public enum PinyinFormat
{
    /// <summary>
    /// 不指定格式
    /// </summary>
    None,
    /// <summary>
    /// 首字母大写，此选项对 a e o i u 几个独音无效
    /// </summary>
    CAPITALIZE_FIRST_LETTER = 1 << 1,
    /// <summary>
    /// 全小写
    /// </summary>
    LOWERCASE = 1 << 2,
    /// <summary>
    /// 全大写
    /// </summary>
    UPPERCASE = 1 << 3,
    /// <summary>
    /// 将 ü 输出为 u:
    /// </summary>
    WITH_U_AND_COLON = 1 << 4,
    /// <summary>
    /// 将 ü 输出为 v
    /// </summary>
    WITH_V = 1 << 5,
    /// <summary>
    /// 将 ü 输出为 ü
    /// </summary>
    WITH_U_UNICODE = 1 << 6,
    /// <summary>
    /// 将 ü 输出为 yu
    /// </summary>
    WITH_YU = 1 << 10,
    /// <summary>
    /// 带声调标志
    /// </summary>
    WITH_TONE_MARK = 1 << 7,
    /// <summary>
    /// 不带声调
    /// </summary>
    WITHOUT_TONE = 1 << 8,
    /// <summary>
    /// 带声调数字值
    /// </summary>
    WITH_TONE_NUMBER = 1 << 9,
}
```

--------------------------------

### Name4Net Surname Pinyin Utilities

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Methods for managing and querying surname Pinyin data within the Name4Net class.

```csharp
/// <summary>
/// 更新姓氏数据库
/// </summary>
/// <param name="data">Key为姓，Value为读音(复姓拼音作为数组的项)</param>
/// <param name="replace">是否替换已经存在的项，默认为 false</param>
public static void UpdateMap(Dictionary<string, string[]> data, bool replace = false);

/// <summary>
/// 获取姓的拼音，如果是复姓则由空格分隔
/// </summary>
/// <param name="firstName">要查询拼音的姓</param>
/// <param name="format">输出拼音格式化参数</param>
/// <returns>返回姓的拼音，若未找到姓，则返回null</returns>
/// <exception cref="UnsupportedUnicodeException">当要获取拼音的字符不是汉字时抛出此异常</exception>
public static string GetPinyin(string firstName, PinyinFormat format = PinyinFormat.None);

 /// <summary>
/// 获取姓的首字母，如果是复姓则由空格分隔首字母
/// </summary>
/// <param name="firstName">要查询拼音的姓</param>
/// <returns>返回姓的拼音首字母，若未找到姓，则返回null</returns>
/// <exception cref="UnsupportedUnicodeException">当要获取拼音的字符不是汉字时抛出此异常</exception>
public static string GetFirstLetter(string firstName);

/// <summary>
/// 根据拼音查询匹配的姓
/// </summary>
/// <param name="pinyin">当 matchAll 为 true 时，会自动处理 v->u: 以及 lyu->lu:</param>
/// <param name="matchAll">是否全部匹配，为true时，匹配整个拼音，否则匹配开头字符，此参数用于告知传入的拼音是完整拼音还是仅仅是声母</param>
/// <returns>匹配的姓数组</returns>
public static string[] GetHanzi(string pinyin, bool matchAll);
```

--------------------------------

### Chinese Character Pinyin Conversion Methods

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Methods for retrieving Pinyin arrays or formatted strings from characters and strings.

```csharp
/// <summary>
/// 更新拼音数据库
/// </summary>
/// <param name="data">Key为汉字，Value为读音(多个读音的拼音作为数组的项)</param>
/// <param name="replace">是否替换已经存在的项，默认为 false</param>
public static void UpdateMap(Dictionary<char, string[]> data, bool replace = false);

/// <summary>
/// 获取汉字的拼音数组
/// </summary>
/// <param name="hanzi">要查询拼音的汉字字符</param>
/// <param name="format">设置输出拼音的格式</param>
/// <returns>汉字的拼音数组，若未找到汉字拼音，则返回空数组</returns>
/// <exception cref="UnsupportedUnicodeException">当要获取拼音的字符不是汉字时抛出此异常</exception>
public static string[] GetPinyin(char hanzi, PinyinFormat format = PinyinFormat.None);

/// <summary>
/// 获取格式化后的唯一拼音(单音字)或者第一个拼音(多音字)
/// </summary>
/// <param name="hanzi">要查询拼音的汉字字符</param>
/// <param name="format">拼音输出格式化参数</param>
/// <see cref="PinyinFormat"/>
/// <seealso cref="PinyinUtil"/>
/// <returns>格式化后的唯一拼音(单音字)或者第一个拼音(多音字)</returns>
/// <exception cref="UnsupportedUnicodeException">当要获取拼音的字符不是汉字时抛出此异常</exception>
public static string GetFirstPinyin(char hanzi, PinyinFormat format = PinyinFormat.None);


/// <summary>
/// 获取一个字符串内所有汉字的拼音数组
/// </summary>
/// <param name="text">要获取拼音的汉字字符串</param>
/// <param name="format">拼音输出格式化参数</param>
/// <returns>返回拼音列表，每个汉字的拼音会作为一个数组存放（无论是单音字还是多音字）</returns>
/// <see cref="PinyinItem"/>
public static List<PinyinItem> GetPinyinArray(string text, PinyinFormat format);

/// <summary>
/// 获取一个字符串内所有汉字的拼音（多音字取第一个读音，带格式）
/// </summary>
/// <param name="text">要获取拼音的汉字字符串</param>
/// <param name="format">拼音输出格式化参数</param>
/// <param name="caseSpread">是否将前面的格式中的大小写扩展到其它非拼音字符，默认为false。firstLetterOnly为false时有效 </param>
/// <param name="firstLetterOnly">是否只取拼音首字母，为true时，format无效</param>
/// <param name="multiFirstLetter">firstLetterOnly为true时有效，多音字的多个读音首字母是否全取，如果多音字拼音首字母相同，只保留一个</param>
/// <returns>firstLetterOnly为true时，只取拼音首字母格式为[L]，后面追加空格；multiFirstLetter为true时，多音字的多个拼音首字母格式为[L, H]，后面追加空格</returns>
public static string GetPinyin(string text, PinyinFormat format, bool caseSpread, bool firstLetterOnly, bool multiFirstLetter);

/// <summary>
/// 获取一个字符串内所有汉字的拼音（多音字取第一个读音，带格式）
/// </summary>
/// <param name="text">要获取拼音的汉字字符串</param>
/// <param name="format">拼音输出格式化参数</param>
/// <param name="caseSpread">是否将前面的格式中的大小写扩展到其它非拼音字符，默认为false。</param>
/// <param name="pinyinHandler">
/// 拼音处理器，在获取到拼音后通过这个来处理，
/// 如果传null，则默认取第一个拼音（多音字），
/// 参数：
/// 1 string[] 拼音数组
/// 2 char 当前的汉字
/// 3 string 要转成拼音的字符串
/// return 拼音字符串，这个返回值将作为这个汉字的拼音放到结果中
/// </param>
public static string GetPinyin(string text, PinyinFormat format, bool caseSpread, Func<string[], char, string, string> pinyinHandler);

/// <summary>
/// 获取一个字符串内所有汉字的拼音（多音字取第一个读音，带格式），format中指定的大小写模式不会扩展到非拼音字符
/// </summary>
/// <param name="text">要获取拼音的汉字字符串</param>
/// <param name="format">拼音输出格式化参数</param>
/// <returns>格式化后的拼音字符串</returns>
public static string GetPinyin(string text, PinyinFormat format);
```

--------------------------------

### Update Surname Mappings with Name4Net

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Use UpdateMap to dynamically add or correct surname pinyin mappings in the library's internal database.

```csharp
using hyjiacan.py4n;

// 查看原始拼音
string original = Name4Net.GetPinyin("张");
// 结果: "zhang1"

// 检查不存在的姓
string notExist = Name4Net.GetPinyin("小");
// 结果: null

// 批量更新姓氏库
Name4Net.UpdateMap(new Dictionary<string, string[]>
{
    // 替换已存在的姓氏读音
    { "张", new[] { "zhang1" } },
    // 添加新的姓氏（单姓）
    { "小", new[] { "xiao3" } },
    // 添加新的复姓
    { "西门", new[] { "xi1", "men2" } }
}, true);

// 验证更新
string updated = Name4Net.GetPinyin("小");
// 结果: "xiao3"

string complex = Name4Net.GetPinyin("西门");
// 结果: "xi1 men2"
```

--------------------------------

### Pinyin4Net.GetPinyinArray

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Returns a detailed list of Pinyin items for each character in a string.

```APIDOC
## Pinyin4Net.GetPinyinArray

### Description
Returns a list of PinyinItem objects containing detailed information for each character.

### Parameters
- **text** (string) - Required - The input string.
- **format** (PinyinFormat) - Optional - Formatting options.

### Response
- **List<PinyinItem>** - A list of objects containing the character, its type, and Pinyin readings.
```

--------------------------------

### Pinyin to Chinese Character Lookup

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

Method for retrieving Chinese characters based on a provided Pinyin string.

```csharp
/// <summary>
/// 根据单个拼音查询匹配的汉字
/// </summary>
/// <param name="pinyin">要查询汉字的单个拼音</param>
/// <param name="matchAll">是否全部匹配，为true时，匹配整个拼音，否则匹配开头字符</param>
/// <returns></returns>
public static string[] GetHanzi(string pinyin, bool matchAll);
```

--------------------------------

### Pinyin4Net.GetFirstPinyin

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Retrieves the first Pinyin reading for a character, useful when polyphonic handling is not required.

```APIDOC
## Pinyin4Net.GetFirstPinyin

### Description
Returns the first Pinyin reading for a character.

### Parameters
- **ch** (char) - Required - The character to convert.
- **format** (PinyinFormat) - Optional - Formatting options.

### Response
- **string** - The first Pinyin reading.
```

--------------------------------

### Pinyin Formatting Options

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

The PinyinFormat enum provides various options to control the output format of pinyin, including capitalization, tone marks, and representation of 'ü'. These options can be combined using bitwise flags.

```APIDOC
## Pinyin Formatting Options

### Description
Used to control the formatting of pinyin input.

### Enum: PinyinFormat

- **None**: No specific format.
- **CAPITALIZE_FIRST_LETTER** (1 << 1): Capitalize the first letter. This option is ineffective for single-character syllables like 'a', 'e', 'o', 'i', 'u'.
- **LOWERCASE** (1 << 2): Convert all pinyin to lowercase.
- **UPPERCASE** (1 << 3): Convert all pinyin to uppercase.
- **WITH_U_AND_COLON** (1 << 4): Represent 'ü' as 'u:'.
- **WITH_V** (1 << 5): Represent 'ü' as 'v'.
- **WITH_U_UNICODE** (1 << 6): Represent 'ü' as 'ü' (unicode character).
- **WITH_YU** (1 << 10): Represent 'ü' as 'yu'.
- **WITH_TONE_MARK** (1 << 7): Include tone marks.
- **WITHOUT_TONE** (1 << 8): Do not include tones.
- **WITH_TONE_NUMBER** (1 << 9): Include tone as a number.

### Usage
Combine bit flag values to format pinyin input. See [Examples](#examples).
```

--------------------------------

### Pinyin4Net.GetPinyin

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Converts text to Pinyin with support for custom polyphonic character handlers.

```APIDOC
## Pinyin4Net.GetPinyin

### Description
Converts a string of Chinese characters into their Pinyin representation, allowing for custom logic to handle polyphonic characters via a handler function.

### Parameters
- **text** (string) - Required - The text to convert.
- **format** (PinyinFormat) - Required - The formatting options for the Pinyin output.
- **isMulti** (bool) - Required - Whether to enable multi-character processing.
- **handler** (Func) - Optional - A delegate to resolve polyphonic character readings based on context.

### Request Example
```csharp
Pinyin4Net.GetPinyin("银行行长", format, false, (pinyinArray, currentChar, fullText) => { ... });
```
```

--------------------------------

### Pinyin4Net.GetPinyin(string)

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Converts a full string of text into Pinyin, supporting mixed content and various output styles.

```APIDOC
## Pinyin4Net.GetPinyin(string)

### Description
Converts a string to its Pinyin representation.

### Parameters
- **text** (string) - Required - The text to convert.
- **format** (PinyinFormat) - Optional - Formatting options.
- **caseSpread** (bool) - Optional - Whether to apply case formatting to non-Pinyin characters.
- **firstLetterOnly** (bool) - Optional - Whether to return only the first letter of each Pinyin.
- **allPolyphonic** (bool) - Optional - Whether to include all polyphonic options.

### Response
- **string** - The converted Pinyin string.
```

--------------------------------

### Name4Net.GetPinyin

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Retrieves the correct Pinyin for Chinese surnames, handling special readings and compound surnames.

```APIDOC
## Name4Net.GetPinyin

### Description
Returns the Pinyin for a given Chinese surname, automatically handling special cases like '单' or compound surnames like '欧阳'.

### Parameters
- **surname** (string) - Required - The surname to look up.
- **format** (PinyinFormat) - Optional - Formatting options for the output.
```

--------------------------------

### Donors

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

A list of individuals who have supported the project through donations.

```APIDOC
## Donors

### Description
Listed in order of donation date.

- [king.jin](https://gitee.com/kingking)
- 袁智远

Thank you to the above friends for their support, which gives us more confidence in open source.
```

--------------------------------

### Surname Pinyin Lookup (Name4Net)

Source: https://github.com/hyjiacan/pinyin4net/blob/master/README.md

APIs for converting Chinese surnames to their Pinyin representations and vice versa.

```APIDOC
## UpdateSurnameMap

### Description
Updates the surname Pinyin database.

### Method
POST

### Endpoint
/surname/update

### Parameters
#### Request Body
- **data** (Dictionary<string, string[]>) - Required - Key is the surname, Value is an array of its pronunciations (for compound surnames, each pronunciation is an item in the array).
- **replace** (bool) - Optional - Whether to replace existing entries. Defaults to false.

### Request Example
```json
{
  "data": {
    "王": ["wáng"]
  },
  "replace": true
}
```

### Response
#### Success Response (200)
Indicates the surname database was updated successfully.

## GetSurnamePinyin

### Description
Retrieves the Pinyin for a given Chinese surname. For compound surnames, Pinyin is space-separated.

### Method
GET

### Endpoint
/surname/pinyin/{firstName}

### Parameters
#### Path Parameters
- **firstName** (string) - Required - The surname to query.
- **format** (PinyinFormat) - Optional - The desired format for the Pinyin output. Defaults to PinyinFormat.None.

### Response
#### Success Response (200)
- **pinyin** (string) - The Pinyin for the surname. Returns null if not found.

#### Error Response (400)
- **error** (string) - "UnsupportedUnicodeException: The character is not a Chinese character."

## GetSurnameFirstLetter

### Description
Retrieves the first letter of the Pinyin for a given Chinese surname. For compound surnames, first letters are space-separated.

### Method
GET

### Endpoint
/surname/firstLetter/{firstName}

### Parameters
#### Path Parameters
- **firstName** (string) - Required - The surname to query.

### Response
#### Success Response (200)
- **firstLetter** (string) - The first letter of the Pinyin for the surname. Returns null if not found.

#### Error Response (400)
- **error** (string) - "UnsupportedUnicodeException: The character is not a Chinese character."

## GetSurnameByPinyin

### Description
Retrieves Chinese surnames that match a given Pinyin string.

### Method
GET

### Endpoint
/surname/search/{pinyin}

### Parameters
#### Path Parameters
- **pinyin** (string) - Required - The Pinyin string to search for. Special handling for 'v' to 'u:' and 'lyu' to 'lu:' is applied when `matchAll` is true.
- **matchAll** (bool) - Optional - If true, performs an exact match of the entire Pinyin string. If false, matches the beginning of the Pinyin string. Defaults to false.

### Response
#### Success Response (200)
- **surnameArray** (string[]) - An array of surnames matching the provided Pinyin.

```

--------------------------------

### Name4Net.GetFirstLetter

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Retrieves the first letter(s) of a surname's Pinyin.

```APIDOC
## Name4Net.GetFirstLetter

### Description
Returns the first letter of the Pinyin for a surname. For compound surnames, returns multiple letters separated by spaces.

### Parameters
- **surname** (string) - Required - The surname to process.
```

--------------------------------

### PinyinFormat Enum - Pinyin Formatting Options

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Controls the format of pinyin output. Multiple format options can be combined using bitwise operations.

```APIDOC
## PinyinFormat Enum - Pinyin Formatting Options

### Description
Controls the format of pinyin output. Multiple format options can be combined using bitwise operations.

### Available Format Options:
- `PinyinFormat.None`: Default format (original pinyin, e.g., li3).
- `PinyinFormat.CAPITALIZE_FIRST_LETTER`: Capitalizes the first letter.
- `PinyinFormat.LOWERCASE`: Converts the entire pinyin to lowercase.
- `PinyinFormat.UPPERCASE`: Converts the entire pinyin to uppercase.
- `PinyinFormat.WITH_U_AND_COLON`: Represents 'ü' as 'u:'.
- `PinyinFormat.WITH_V`: Represents 'ü' as 'v'.
- `PinyinFormat.WITH_U_UNICODE`: Represents 'ü' as 'ü'.
- `PinyinFormat.WITH_YU`: Represents 'ü' as 'yu' (e.g., lyu).
- `PinyinFormat.WITH_TONE_MARK`: Includes tone marks (e.g., lǐ).
- `PinyinFormat.WITHOUT_TONE`: Excludes tones (e.g., li).
- `PinyinFormat.WITH_TONE_NUMBER`: Includes tone numbers (e.g., li3).

### Usage Example (Combining Formats)
```csharp
// Example 1: Tone mark + lowercase + Unicode ü
var format1 = PinyinFormat.WITH_TONE_MARK | PinyinFormat.LOWERCASE | PinyinFormat.WITH_U_UNICODE;
string py1 = Pinyin4Net.GetFirstPinyin('绿', format1);
// Result: "lǜ"

// Example 2: No tone + uppercase + 'v' for ü
var format2 = PinyinFormat.WITHOUT_TONE | PinyinFormat.UPPERCASE | PinyinFormat.WITH_V;
string py2 = Pinyin4Net.GetFirstPinyin('绿', format2);
// Result: "LV"

// Example 3: Capitalize first letter + no tone
var format3 = PinyinFormat.WITHOUT_TONE | PinyinFormat.CAPITALIZE_FIRST_LETTER;
string py3 = Pinyin4Net.GetFirstPinyin('李', format3);
// Result: "Li"

### Important Note:
`PinyinFormat.WITH_TONE_MARK` cannot be used simultaneously with `PinyinFormat.WITH_V`, `PinyinFormat.WITH_U_AND_COLON`, or `PinyinFormat.WITH_YU`. Doing so will throw a `PinyinException`.
```

--------------------------------

### Name4Net.UpdateMap - Update Surname Database

Source: https://context7.com/hyjiacan/pinyin4net/llms.txt

Dynamically updates or adds surname-pinyin mappings to the database. This is useful for adding missing surnames or correcting pronunciations.

```APIDOC
## Name4Net.UpdateMap - Update Surname Database

### Description
Dynamically updates or adds surname-pinyin mappings to the database. This is useful for adding missing surnames or correcting pronunciations.

### Method
`Name4Net.UpdateMap`

### Parameters
#### Request Body
- **surnameMap** (Dictionary<string, string[]>) - Required - A dictionary where keys are surnames and values are arrays of their corresponding pinyin pronunciations.
- **overwrite** (bool) - Optional - If true, existing entries will be overwritten. Defaults to false.

### Request Example
```csharp
Name4Net.UpdateMap(new Dictionary<string, string[]> 
{
    { "张", new[] { "zhang1" } },
    { "小", new[] { "xiao3" } },
    { "西门", new[] { "xi1", "men2" } }
}, true);
```

### Response
This method does not return a value. Updates are reflected in subsequent calls to `Name4Net.GetPinyin`.
```