go-pinyin 库使用指南

go-pinyin 是一个将中文汉字转换为汉语拼音的 Go 语言库，支持多种拼音风格和分词选项。

安装

go get -u github.com/mozillazg/go-pinyin

基本使用

简单转换

package main

import (
	"fmt"
	"github.com/mozillazg/go-pinyin"
)

func main() {
	hans := "你好世界"
	
	// 默认风格，带声调
	p := pinyin.NewArgs()
	fmt.Println(pinyin.Pinyin(hans, p))
	// 输出: [[nǐ] [hǎo] [shì] [jiè]]
	
	// 不带声调
	p.Style = pinyin.Normal
	fmt.Println(pinyin.Pinyin(hans, p))
	// 输出: [[ni] [hao] [shi] [jie]]
}

参数配置

go-pinyin 提供了多种配置选项：

args := pinyin.NewArgs()

// 拼音风格
args.Style = pinyin.Tone      // 带声调（默认） nǐ hǎo
args.Style = pinyin.Tone2     // 声调在拼音后 ni3 hao3
args.Style = pinyin.Tone3     // 数字声调在最后 n3i h3ao
args.Style = pinyin.Initials  // 只要声母 n h
args.Style = pinyin.FirstLetter // 首字母 n h
args.Style = pinyin.Normal    // 不带声调 ni hao

// 其他选项
args.Heteronym = true         // 启用多音字模式
args.Separator = "-"          // 设置拼音分隔符
args.Fallback = func(r rune, a pinyin.Args) []string {
	return []string{string(r)} // 无法转换的字符回调
}

多音字处理

func main() {
	hans := "银行行长一行人在银行的行长椅上"
	
	args := pinyin.NewArgs()
	args.Heteronym = true // 启用多音字模式
	
	fmt.Println(pinyin.Pinyin(hans, args))
	// 输出: [[yín] [háng xíng] [háng xíng zhǎng] [yī xíng háng] [de] [rén] [zài] [yín] [háng] [de] [háng xíng zhǎng] [yǐ]]
}

获取拼音字符串

func main() {
	hans := "中华人民共和国"
	
	args := pinyin.NewArgs()
	args.Style = pinyin.Normal
	
	// 获取二维拼音切片
	pys := pinyin.Pinyin(hans, args)
	fmt.Println(pys) 
	// 输出: [[zhong] [hua] [ren] [min] [gong] [he] [guo]]
	
	// 拼接为字符串
	var result []string
	for _, items := range pys {
		result = append(result, items[0])
	}
	fmt.Println(strings.Join(result, " "))
	// 输出: zhong hua ren min gong he guo
	
	// 或者使用LazyPinyin直接获取一维切片
	fmt.Println(pinyin.LazyPinyin(hans, args))
	// 输出: [zhong hua ren min gong he guo]
}

自定义字典

如果需要处理特殊字符或覆盖默认拼音，可以自定义字典：

func main() {
	hans := "㑇"
	
	// 默认无法转换
	args := pinyin.NewArgs()
	fmt.Println(pinyin.Pinyin(hans, args))
	// 输出: [[]]
	
	// 添加自定义拼音
	pinyin.AddDict("㑇", "zhou4")
	fmt.Println(pinyin.Pinyin(hans, args))
	// 输出: [[zhòu]]
}

高级用法

处理姓名

func main() {
	name := "单于"
	
	args := pinyin.NewArgs()
	args.Heteronym = true
	
	// 普通模式
	fmt.Println(pinyin.Pinyin(name, args))
	// 输出: [[dān shàn chán] [yú]]
	
	// 姓名模式
	args.Fallback = func(r rune, a pinyin.Args) []string {
		// 处理姓氏多音字
		if r == '单' {
			return []string{"shàn"}
		}
		if r == '于' {
			return []string{"yú"}
		}
		return pinyin.Fallback(r, a)
	}
	fmt.Println(pinyin.Pinyin(name, args))
	// 输出: [[shàn] [yú]]
}

性能优化

对于大量文本处理，可以预加载字典：

func init() {
	// 预加载字典到内存
	pinyin.Loading()
}

func main() {
	// 大量文本处理...
}

注意事项

1. 多音字处理需要上下文分析，库无法100%准确，必要时需要人工干预
2. 对于非常用汉字，可能需要自定义字典
3. 性能方面，首次调用会有字典加载时间，后续调用较快

go-pinyin 是一个功能全面且灵活的拼音转换库，适合大多数中文文本转拼音的需求。