TGZH.Pinyin 1.0.13

TGZH.Pinyin 使用文档

目录

• 简介
• 安装
• 使用说明
• 基本用法
• 详细API参考
• 高级功能
• 示例代码

简介

TGZH.Pinyin 是一个高性能的中文拼音转换库，提供了丰富的拼音处理功能：

• 支持多种拼音格式（带声调、不带声调、数字声调、首字母）
• 智能处理多音字
• 支持单字、词语和大文本的转换
• 包含拼音比较、匹配等实用工具
• 支持所有Unicode汉字（包括所有扩展区）
• 高效的批处理和缓存机制

安装

通过 NuGet 安装

Install-Package TGZH.Pinyin

或使用 .NET CLI:

dotnet add package TGZH.Pinyin

也可以通过 Visual Studio 的 NuGet 包管理器搜索 TGZH.Pinyin 进行安装。

使用说明

项目引用

1. NuGet 安装后可直接使用
2. 或在你的解决方案中添加TGZH.Pinyin项目引用

基本用法

初始化拼音库

在使用任何拼音功能前，需要先初始化拼音库：

using TGZH.Pinyin;

// 默认初始化
await UnifiedPinyinApi.InitializeAsync();

// 或者使用自定义选项初始化
var options = new PinyinLibraryOptions
{
    PreloadCommonChars = true,
    PrioritizeWordPinyin = true,
    MaxWordLength = 8
};
await UnifiedPinyinApi.InitializeAsync(options);

获取汉字拼音

// 获取单个汉字的拼音（支持多音字，返回所有可能的拼音）
string[] pinyins = await UnifiedPinyinApi.GetCharPinyinAsync('中');
Console.WriteLine(string.Join(", ", pinyins));  // 输出: zhōng

// 获取扩展区汉字的拼音（使用字符串重载）
string[] extPinyins = await UnifiedPinyinApi.GetCharPinyinAsync("𠀀");

// 不同的拼音格式
string[] withoutTone = await UnifiedPinyinApi.GetCharPinyinAsync('中', PinyinFormat.WithoutTone);
string[] withToneNumber = await UnifiedPinyinApi.GetCharPinyinAsync('中', PinyinFormat.WithToneNumber);
string[] firstLetter = await UnifiedPinyinApi.GetCharPinyinAsync('中', PinyinFormat.FirstLetter);

获取文本拼音

// 获取文本的拼音
string pinyin = await UnifiedPinyinApi.GetTextPinyinAsync("中国");
Console.WriteLine(pinyin);  // 输出: zhōng guó

// 自定义分隔符
string pinyinNoSpace = await UnifiedPinyinApi.GetTextPinyinAsync("中国", PinyinFormat.WithToneMark, "");
Console.WriteLine(pinyinNoSpace);  // 输出: zhōngguó

// 不带声调
string pinyinNoTone = await UnifiedPinyinApi.GetTextPinyinAsync("中国", PinyinFormat.WithoutTone);
Console.WriteLine(pinyinNoTone);  // 输出: zhong guo

// 首字母
string firstLetters = await UnifiedPinyinApi.GetFirstLettersAsync("中国");
Console.WriteLine(firstLetters);  // 输出: zg

详细API参考

枚举

PinyinFormat

public enum PinyinFormat
{
    // 带声调，如: zhōng guó
    WithToneMark,

    // 不带声调，如: zhong guo
    WithoutTone,

    // 带数字声调，如: zhong1 guo2
    WithToneNumber,

    // 仅首字母，如: z g
    FirstLetter
}

类和接口

UnifiedPinyinApi 类

主要的静态API类，提供所有拼音相关功能。

PinyinUtils 类

提供拼音相关的实用工具方法。

ChineseCharacterUtils 类

提供处理中文字符的通用方法。

PinyinLibraryOptions 类

拼音库初始化选项。

PinyinResult 类

拼音结果类。

高级功能

智能处理多音字

TGZH.Pinyin 内置了常见多音字的上下文识别能力，能根据词语智能判断正确读音：

// "行"字在不同上下文中的读音不同
string text1 = await UnifiedPinyinApi.GetTextPinyinAsync("银行");  // háng
string text2 = await UnifiedPinyinApi.GetTextPinyinAsync("行走");  // xíng

大文本处理

针对大文本处理，使用优化的批处理方法：

string largeText = File.ReadAllText("大文件.txt");
string pinyin = await UnifiedPinyinApi.ProcessLargeTextAsync(largeText);

拼音比较与匹配

// 比较拼音相似度
double similarity = PinyinUtils.CompareSimilarity("zhong guo", "zhōng guó");
Console.WriteLine(similarity);  // 输出接近 1.0 的值

// 拼音模式匹配
bool matches = await PinyinUtils.MatchesPinyinPattern("中国人", "zgr");
Console.WriteLine(matches);  // 输出: True

示例代码

完整使用示例

using System;
using System.Threading.Tasks;
using TGZH.Pinyin;

class Program
{
    static async Task Main()
    {
        // 初始化拼音库
        await UnifiedPinyinApi.InitializeAsync();
        
        // 示例文本
        string text = "中国是一个有着五千年历史的文明古国";
        
        // 获取带声调的拼音
        string withTone = await UnifiedPinyinApi.GetTextPinyinAsync(text);
        Console.WriteLine($"带声调: {withTone}");
        
        // 获取不带声调的拼音
        string withoutTone = await UnifiedPinyinApi.GetTextPinyinAsync(text, PinyinFormat.WithoutTone);
        Console.WriteLine($"不带声调: {withoutTone}");
        
        // 获取数字声调的拼音
        string withNumber = await UnifiedPinyinApi.GetTextPinyinAsync(text, PinyinFormat.WithToneNumber);
        Console.WriteLine($"数字声调: {withNumber}");
        
        // 获取首字母
        string firstLetter = await UnifiedPinyinApi.GetFirstLettersAsync(text);
        Console.WriteLine($"首字母: {firstLetter}");
        
        // 处理多音字
        string multiTone = await UnifiedPinyinApi.GetTextPinyinAsync("银行和行走");
        Console.WriteLine($"多音字处理: {multiTone}");
        
        // 拼音匹配
        bool match = await PinyinUtils.MatchesPinyinPattern("中国银行", "zgyx");
        Console.WriteLine($"拼音匹配 'zgyx': {match}");
        
        // 使用字符串重载方法处理扩展区字符
        string[] extPinyin = await UnifiedPinyinApi.GetCharPinyinAsync("𠀀");
        Console.WriteLine($"扩展区字符拼音: {string.Join(", ", extPinyin)}");
    }
}

输出结果

带声调: zhōng guó shì yī gè yǒu zhe wǔ qiān nián lì shǐ de wén míng gǔ guó
不带声调: zhong guo shi yi ge you zhe wu qian nian li shi de wen ming gu guo
数字声调: zhong1 guo2 shi4 yi1 ge4 you3 zhe5 wu3 qian1 nian2 li4 shi3 de5 wen2 ming2 gu3 guo2
首字母: zgsy1gyzw5qnlsdwmgg
多音字处理: yín háng hé xíng zǒu
拼音匹配 'zgyx': True
扩展区字符拼音: qiū

自定义配置示例

using System;
using System.Threading.Tasks;
using TGZH.Pinyin;

class Program
{
    static async Task Main()
    {
        // 自定义配置初始化
        var options = new PinyinLibraryOptions
        {
            // 自定义词典路径（如果有）
            DatabasePath = "custom_pinyin_db.sqlite",
            
            // 是否预加载常用汉字
            PreloadCommonChars = true,
            
            // 是否优先使用词语拼音（影响多音字处理）
            PrioritizeWordPinyin = true,
            
            // 最大词语长度限制
            MaxWordLength = 10
        };
        
        // 使用自定义配置初始化
        await UnifiedPinyinApi.InitializeAsync(options);
        
        // 使用功能
        var text = "长城长度很长";
        var pinyin = await UnifiedPinyinApi.GetTextPinyinAsync(text);
        Console.WriteLine($"原文: {text}");
        Console.WriteLine($"拼音: {pinyin}");
    }
}

特别鸣谢

TGZH.Pinyin 使用了以下开源数据：

• 汉字拼音数据来源于 pinyin-data，基于 MIT 许可证
• 词语拼音数据来源于 phrase-pinyin-data，基于 MIT 许可证

感谢 @mozillazg 的工作使本项目得以实现。

本软件由Copilot辅助编写，若与其他开源项目雷同，作者不承担任何责任。

许可证

此库遵循 MIT 许可证。

联系方式

如有问题或建议，请在项目中提交Issue或联系开发者。