获取汉语拼音

发表于 2023-04-04 更新于 2025-07-29 分类于工具类 Waline：阅读次数：本文字数： 6.4k 阅读时长 ≈ 6 分钟

汉语拼音转换工具 pinyin4j 实战：基础用法与多音字处理全指南

在中文数据处理场景中（如搜索推荐、排序、拼音检索），经常需要将汉字转换为汉语拼音。pinyin4j 是一款经典的 Java 拼音转换工具，支持全拼、简拼、声调标注等功能。本文将详细讲解 pinyin4j 的基础用法、多音字问题及解决方案，帮助你在实际开发中精准处理拼音转换需求。

pinyin4j 基础入门

引入依赖

pinyin4j 是开源工具，可通过 Maven 或 Gradle 引入项目：

Maven 依赖：

<dependency>  
    <groupId>com.belerweb</groupId>  
    <artifactId>pinyin4j</artifactId>  
    <version>2.5.1</version>  <!-- 最新稳定版 -->  
</dependency>

Gradle 依赖：

implementation 'com.belerweb:pinyin4j:2.5.1'

核心类与基础用法

pinyin4j 的核心功能通过 PinyinHelper 工具类实现，配合 HanyuPinyinOutputFormat 配置输出格式（如声调、大小写）。

基本拼音转换

将单个汉字转换为拼音（支持多音字返回多个结果）：

import net.sourceforge.pinyin4j.PinyinHelper;  
import net.sourceforge.pinyin4j.format.HanyuPinyinOutputFormat;  
import net.sourceforge.pinyin4j.format.HanyuPinyinToneType;  

public class PinyinDemo {  
    public static void main(String[] args) {  
        // 配置输出格式（无声调）  
        HanyuPinyinOutputFormat format = new HanyuPinyinOutputFormat();  
        format.setToneType(HanyuPinyinToneType.WITHOUT_TONE);  // 不显示声调  

        // 转换单个汉字  
        String[] pinyins = PinyinHelper.toHanyuPinyinStringArray('长', format);  
        for (String pinyin : pinyins) {  
            System.out.println(pinyin);  // 输出：chang、zhang（"长"是多音字）  
        }  
    }  
}

字符串批量转换

通过 toHanYuPinyinString 方法直接转换整段文字：

import net.sourceforge.pinyin4j.format.exception.BadHanyuPinyinOutputFormatCombination;  

public class StringPinyinDemo {  
    public static void main(String[] args) throws BadHanyuPinyinOutputFormatCombination {  
        HanyuPinyinOutputFormat format = new HanyuPinyinOutputFormat();  
        format.setToneType(HanyuPinyinToneType.WITHOUT_TONE);  // 无声调  
        format.setCaseType(HanyuPinyinCaseType.LOWERCASE);     // 小写字母  

        String chinese = "北京市";  
        // 转换字符串，分隔符为空，保留非汉字字符  
        String pinyin = PinyinHelper.toHanYuPinyinString(chinese, format, "", true);  
        System.out.println(pinyin);  // 输出：beijingshi  
    }  
}

输出格式配置

HanyuPinyinOutputFormat 支持多种格式定制，满足不同需求：

配置项	功能描述	可选值示例
声调类型	控制是否显示声调	`WITHOUT_TONE`（无声调）、`WITH_TONE_MARK`（带声调符号）
大小写类型	控制拼音字母大小写	`LOWERCASE`（小写）、`UPPERCASE`（大写）
元音字母 ü 处理	控制 ü 的显示方式	`WITH_U_AND_COLON`（u:）、`WITH_V`（v）

示例：带声调的拼音转换

format.setToneType(HanyuPinyinToneType.WITH_TONE_MARK);  // 带声调符号  
String pinyin = PinyinHelper.toHanYuPinyinString("你好", format, "", true);  
System.out.println(pinyin);  // 输出：nǐhǎo

多音字问题：痛点与解决方案

多音字转换的痛点

pinyin4j 对单个汉字的多音字转换默认返回所有可能读音，但在词语或句子中，多音字的读音需结合语境，例如：

“长沙” 中的 “长” 应读 cháng，而非 zhǎng；
“行” 在 “银行” 中读 háng，在 “行动” 中读 xíng。

默认情况下，pinyin4j 会按单个汉字拆分转换，导致错误：

// 问题示例：“长沙市” 错误转换  
String wrong = PinyinHelper.toHanYuPinyinString("长沙市", format, "", true);  
System.out.println(wrong);  // 输出：zhangshashi（错误，应为 changshashi）

解决方案：多音字外挂（MultiPinyin）

pinyin4j 提供了多音字外挂机制，通过自定义词典（multipy.txt）指定词语的正确读音组合，覆盖默认的单字读音。

配置多音字词典

创建 multipy.txt 文件，按格式定义词语的正确拼音（支持声调标注）：

# 格式：词语 (拼音1,拼音2,...)，声调可选（数字 1-4 或省略）  
长沙 (chang,sha)  
银行 (yin,hang)  
行动 (xing,dong)  
重庆 (zhong,qing)

每行定义一个词语，括号内为每个字的正确拼音（按顺序对应）；
声调可省略（默认无声调），或用数字 1-4 标注（如 chang2 表示第二声）；
非汉字字符（如标点、数字）无需配置，会被自动保留。

加载多音字词典

通过 MultiPinyinConfig 指定词典路径，使 pinyin4j 优先使用自定义读音：

import net.sourceforge.pinyin4j.multipinyin.MultiPinyinConfig;  

public class MultiPinyinDemo {  
    public static void main(String[] args) throws Exception {  
        // 1. 配置多音字词典路径（资源文件放在 src/main/resources/pinyindb/ 下）  
        String dictPath = Thread.currentThread().getContextClassLoader()  
            .getResource("pinyindb/multipy.txt").getPath();  
        MultiPinyinConfig.setMultiPinyinPath(dictPath);  // 设置词典路径  

        // 2. 配置输出格式  
        HanyuPinyinOutputFormat format = new HanyuPinyinOutputFormat();  
        format.setToneType(HanyuPinyinToneType.WITHOUT_TONE);  

        // 3. 转换带多音字的词语  
        String correct = PinyinHelper.toHanYuPinyinString("长沙市", format, "", true);  
        System.out.println(correct);  // 输出：changshashi（正确）  
    }  
}

词典匹配规则

pinyin4j 会按最长匹配原则优先匹配词典中的词语：

若输入包含 “长沙”，则优先使用词典中 “长沙” 的读音（chang,sha）；
未匹配到词语的部分，仍按单字默认读音转换（如 “长沙市” 中的 “市” 按单字转换为 shi）。

高级：动态添加多音字规则

除了加载本地词典，还可通过代码动态添加多音字规则，适用于需要 runtime 灵活配置的场景：

import net.sourceforge.pinyin4j.multipinyin.MultiPinyinDictionary;  

// 动态添加“重庆”的读音规则  
MultiPinyinDictionary.addMultiPinyin("重庆", new String[]{"chong", "qing"});  

// 转换验证  
String pinyin = PinyinHelper.toHanYuPinyinString("重庆", format, "", true);  
System.out.println(pinyin);  // 输出：chongqing

实战场景：拼音转换工具类封装

为提高复用性，可封装一个通用的拼音转换工具类，整合基础转换、多音字处理和格式定制功能：

import net.sourceforge.pinyin4j.PinyinHelper;  
import net.sourceforge.pinyin4j.format.HanyuPinyinCaseType;  
import net.sourceforge.pinyin4j.format.HanyuPinyinOutputFormat;  
import net.sourceforge.pinyin4j.format.HanyuPinyinToneType;  
import net.sourceforge.pinyin4j.format.exception.BadHanyuPinyinOutputFormatCombination;  
import net.sourceforge.pinyin4j.multipinyin.MultiPinyinConfig;  

import java.io.IOException;  

public class PinyinUtils {  
    // 静态初始化多音字词典  
    static {  
        try {  
            // 加载资源文件中的多音字词典  
            String dictPath = Thread.currentThread().getContextClassLoader()  
                .getResource("pinyindb/multipy.txt").getPath();  
            MultiPinyinConfig.setMultiPinyinPath(dictPath);  
        } catch (Exception e) {  
            System.err.println("加载多音字词典失败：" + e.getMessage());  
        }  
    }  

    /**  
     * 转换汉字为拼音（无声调、小写）  
     * @param chinese 汉字字符串  
     * @return 拼音字符串（如“长沙”→“changsha”）  
     */  
    public static String toPinyin(String chinese) {  
        try {  
            HanyuPinyinOutputFormat format = new HanyuPinyinOutputFormat();  
            format.setToneType(HanyuPinyinToneType.WITHOUT_TONE);  // 无声调  
            format.setCaseType(HanyuPinyinCaseType.LOWERCASE);     // 小写  
            return PinyinHelper.toHanYuPinyinString(chinese, format, "", true);  
        } catch (BadHanyuPinyinOutputFormatCombination e) {  
            throw new RuntimeException("拼音转换失败：" + e.getMessage());  
        }  
    }  

    /**  
     * 转换汉字为带声调的拼音  
     * @param chinese 汉字字符串  
     * @return 带声调的拼音（如“你好”→“nǐhǎo”）  
     */  
    public static String toPinyinWithTone(String chinese) {  
        try {  
            HanyuPinyinOutputFormat format = new HanyuPinyinOutputFormat();  
            format.setToneType(HanyuPinyinToneType.WITH_TONE_MARK);  // 带声调符号  
            return PinyinHelper.toHanYuPinyinString(chinese, format, "", true);  
        } catch (BadHanyuPinyinOutputFormatCombination e) {  
            throw new RuntimeException("带声调拼音转换失败：" + e.getMessage());  
        }  
    }  

    // 测试方法  
    public static void main(String[] args) {  
        System.out.println(toPinyin("长沙市"));         // 输出：changshashi  
        System.out.println(toPinyinWithTone("你好，长沙"));  // 输出：nǐhǎo，chángshā  
    }  
}

常见问题与解决方案

1. 非汉字字符处理

问题：转换包含字母、数字或标点的字符串时，非汉字字符被过滤；

解决：toHanYuPinyinString方法的最后一个参数设为true，保留非汉字字符：

// 保留非汉字字符（如标点、字母）  
PinyinHelper.toHanYuPinyinString("北京2024！", format, "", true);  // 输出：beijing2024！

2. 词典加载失败

问题：MultiPinyinConfig.setMultiPinyinPath 报路径错误；
解决：
- 检查资源文件路径是否正确（避免空格或特殊字符）；
- 用getResourceAsStream替代路径读取，兼容 JAR 包内资源：
```
MultiPinyinConfig.setMultiPinyinInputStream(  
    Thread.currentThread().getContextClassLoader().getResourceAsStream("pinyindb/multipy.txt")  
);
```

3. 多音字匹配优先级

问题：短词语被长词语覆盖（如 “长” 和 “长沙” 同时存在时）；
解决：pinyin4j 默认按最长匹配，无需额外配置，确保词典中长词语定义优先。