拼音工具 - PinyinUtil

---

1. 介绍

PinyinUtil 是 Hutool 提供的拼音处理工具类，用于将中文字符转换为拼音。该工具类支持多个拼音库，如 TinyPinyin、JPinyin 和 Pinyin4j，用户只需引入对应的依赖库即可。Hutool 会根据引入的库自动选择最优的拼音引擎，提供统一的 API 进行拼音处理。

2. 使用

2.1. 引入拼音库

Hutool 兼容以下拼音库，你可以根据需要选择其中一个进行引入。如果引入多个，Hutool 会按顺序优先使用第一个被识别的库。

<!-- 引入 TinyPinyin -->
<dependency>
    <groupId>io.github.biezhi</groupId>
    <artifactId>TinyPinyin</artifactId>
    <version>2.0.3.RELEASE</version>
</dependency>

<!-- 引入 Pinyin4j -->
<dependency>
    <groupId>com.belerweb</groupId>
    <artifactId>pinyin4j</artifactId>
    <version>2.5.1</version>
</dependency>

<!-- 引入 JPinyin -->
<dependency>
    <groupId>com.github.stuxuhai</groupId>
    <artifactId>jpinyin</artifactId>
    <version>1.1.8</version>
</dependency>

2.2. 获取汉字的拼音

import cn.hutool.extra.pinyin.PinyinUtil;

public class PinyinExample {
    public static void main(String[] args) {
        // 获取汉字的拼音，使用空格作为分隔符
        String pinyin = PinyinUtil.getPinyin("你好", " ");
        System.out.println("拼音: " + pinyin); // 输出: ni hao
    }
}

API解析：

• getPinyin(String str, String separator)：将中文字符转换为拼音并使用指定的分隔符连接。
  • str：要转换的中文字符。
  • separator：拼音之间的分隔符，可以是空格、逗号等。

实际开发场景：

• 在处理人名、地名等场景时，需要将中文转化为拼音用于显示、排序或搜索功能。

---

2.3. 获取拼音的首字母

import cn.hutool.extra.pinyin.PinyinUtil;

public class PinyinFirstLetterExample {
    public static void main(String[] args) {
        // 获取汉字拼音的首字母，使用逗号作为分隔符
        String firstLetters = PinyinUtil.getFirstLetter("我是第一个", ", ");
        System.out.println("拼音首字母: " + firstLetters); // 输出: w, s, d, y, g
    }
}

API解析：

• getFirstLetter(String str, String separator)：获取汉字拼音的首字母并使用指定的分隔符连接。
  • str：要处理的中文字符。
  • separator：首字母之间的分隔符。

实际开发场景：

• 在联系人列表或城市选择器等场景中，需要根据拼音首字母进行分组和排序。

---

2.4. 使用自定义的拼音引擎

import cn.hutool.extra.pinyin.engine.pinyin4j.Pinyin4jEngine;
import cn.hutool.extra.pinyin.PinyinEngine;

public class CustomEngineExample {
    public static void main(String[] args) {
        // 使用 Pinyin4j 作为拼音引擎
        PinyinEngine engine = new Pinyin4jEngine();

        // 获取拼音
        String pinyin = engine.getPinyin("你好h", " ");
        System.out.println("拼音: " + pinyin); // 输出: ni hao h
    }
}

API解析：

• Pinyin4jEngine：使用 Pinyin4j 引擎进行拼音转换。
• getPinyin(String str, String separator)：与 PinyinUtil 中的同名方法类似，但可以指定引擎实现。

实际开发场景：

• 当项目中有特殊需求或性能考虑时，可以手动指定拼音引擎。

---

4. 总结

PinyinUtil 是一个强大的拼音处理工具，支持多种拼音引擎，具有很好的兼容性和扩展性。开发者可以通过引入不同的拼音库，在不同场景下实现中文到拼音的转换需求，无需改动代码逻辑，极大地提高了开发效率。