Java 實作漢字轉拼音完整代碼教學

在 Java 開發中，將中文字符轉換為拼音是常見需求，無論是實現搜索功能、排序邏輯還是輸入法開發都會用到。本文提供一個基於 pinyin4j 庫的完整實作方案，包含依賴配置、核心代碼與使用示例。

一、功能演示

輸入字符串：「北京歡迎你」

輸出拼音：「bei jing huan ying ni」

二、環境準備

專案需引入 pinyin4j 依賴。Maven 配置如下：

<dependency>
    <groupId>com.belerweb</groupId>
    <artifactId>pinyin4j</artifactId>
    <version>2.5.0</version>
</dependency>

三、核心實作代碼

import net.sourceforge.pinyin4j.*;
import net.sourceforge.pinyin4j.format.*;

public class PinyinUtil {

    /**
     * 將漢字字符串轉換為拼音（小寫、無聲調、v 代表 ü）
     * @param src 待轉換的字符串
     * @return 拼音字符串，非漢字字符保持原樣
     */
    public static String getPinYin(String src) {
        if (src == null || src.isEmpty()) {
            return "";
        }

        char[] chars = src.toCharArray();
        HanyuPinyinOutputFormat format = new HanyuPinyinOutputFormat();
        format.setCaseType(HanyuPinyinCaseType.LOWERCASE);
        format.setToneType(HanyuPinyinToneType.WITHOUT_TONE);
        format.setVCharType(HanyuPinyinVCharType.WITH_V);

        StringBuilder result = new StringBuilder();

        try {
            for (char c : chars) {
                String charStr = String.valueOf(c);
                // 判斷是否為中文字符（基本漢字區塊）
                if (charStr.matches("[\\u4E00-\\u9FA5]")) {
                    String[] pinyinArray = PinyinHelper.toHanyuPinyinStringArray(c, format);
                    if (pinyinArray != null && pinyinArray.length > 0) {
                        result.append(pinyinArray[0]).append(" ");
                    }
                } else {
                    // 非漢字直接保留
                    result.append(c);
                }
            }
        } catch (BadHanyuPinyinOutputFormatCombination e) {
            e.printStackTrace();
        }

        return result.toString().trim();
    }

    public static void main(String[] args) {
        System.out.println(getPinYin("北京歡迎你")); // 輸出：bei jing huan ying ni
    }
}

四、關鍵點解析

• 輸出格式配置：通過 HanyuPinyinOutputFormat 設定小寫、去聲調、ü 以 v 表示。
• 多音字處理：toHanyuPinyinStringArray 返回所有可能讀音，此處取第一個（最常用讀音）。
• 非漢字透傳：標點、數字、英文等字符直接保留，不做轉換。

五、擴展建議

若需支援首字母縮寫、多音字選擇或自定義詞庫，可在此基礎上進一步封裝。生產環境建議加入緩存機制提升高頻調用性能。