jQuery.Hz2Py.js 是一款輕量級 jQuery 插件,將中文漢字轉換為拼音(支援帶聲調、首字母、全拼等模式)。核心原理:內建漢字→拼音映射表(約 2萬常用字),透過查表實現同步轉換,無需後端請求。
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="path/to/jQuery.Hz2Py.min.js"></script>
<textarea id="input-text" placeholder="輸入中文文字..." rows="4"></textarea>
<div class="output-modes">
<label><input type="radio" name="mode" value="pinyin" checked> 全拼 (zhōng wén) </label>
<label><input type="radio" name="mode" value="first"> 首字母 (zw) </label>
<label><input type="radio" name="mode" value="tone"> 數字聲調 (zhong1 wen2) </label>
<label><input type="radio" name="mode" value="no-tone"> 無聲調 (zhong wen) </label>
</div>
<textarea id="output-text" readonly rows="4"></textarea>
$(function() {
var $input = $("#input-text");
var $output = $("#output-text");
var $modeRadios = $("input[name='mode']");
function convert() {
var text = $input.val();
if (!text) { $output.val(""); return; }
var mode = $modeRadios.filter(":checked").val();
var result = $.fn.toPinyin(text, { mode: mode });
$output.val(result);
}
// 即時轉換
$input.on("input propertychange", convert);
$modeRadios.on("change", convert);
// 初始轉換
convert();
});
| 方法 | 參數 | 回傳 | 說明 |
|---|---|---|---|
$.fn.toPinyin(text, options) | text: 字串 options: 設定物件 | 字串 | 靜態方法,直接轉換字串 |
$(selector).toPinyin(options) | options: 設定物件 | 字串 | 實例方法,轉換元素值/文字 |
{
mode: "pinyin", // "pinyin" | "first" | "tone" | "no-tone"
separator: " ", // 拼音間分隔符
keepNonChinese: true // 保留非中文字符(英文、數字、標點)
}
// 簡化版映射表結構 (實際約 20,000+ 字符)
var PINYIN_MAP = {
"中": ["zhōng", "zhong1", "zhong", "z"],
"文": ["wén", "wen2", "wen", "w"],
"網": ["wǎng", "wang3", "wang", "w"],
// ... 萬餘字符
};
// 查表邏輯 (簡化)
function toPinyin(text, options) {
return text.split("").map(function(char) {
var pinyins = PINYIN_MAP[char];
if (!pinyins) return options.keepNonChinese ? char : "";
switch (options.mode) {
case "pinyin": return pinyins[0]; // 帶聲調
case "tone": return pinyins[1]; // 數字聲調
case "no-tone": return pinyins[2]; // 無聲調
case "first": return pinyins[3]; // 首字母
}
}).join(options.separator);
}
插件採用單一映射,無法根據上下文判斷正確讀音:
行 → 只能輸出 xíng 或 háng 其中之一長 → 只能輸出 cháng 或 zhǎng| 方案 | 優點 | 缺點 | 體積 | 環境 |
|---|---|---|---|---|
| jQuery.Hz2Py.js | 零依賴 (僅 jQuery)、同步、API 簡單 | 無多音字支援、停止維護、無 TypeScript、ESM 不支援 | ~40KB | 瀏覽器 |
| pinyin (hotoo) | 支援多音字、分詞優化、Node/瀏覽器雙端、TypeScript | 體積較大、需建構工具 | ~200KB (含詞典) | Node + 瀏覽器 |
| pinyin-pro | 極小體積、Tree-shaking 友善、多音字、分詞、TypeScript | 相對較新 | ~15KB (gz) | Node + 瀏覽器 + ESM |
| pinyin-match | 專注模糊搜尋/匹配、高效能 | 非通用轉換 | ~10KB | Node + 瀏覽器 |
// 安裝: npm i pinyin-pro
import { pinyin } from "pinyin-pro";
const text = "重慶長江大橋";
console.log(pinyin(text)); // "chóng qìng cháng jiāng dà qiáo" (智能多音字)
console.log(pinyin(text, { toneType: "num" })); // "chong2 qing4 chang2 jiang1 da4 qiao2"
console.log(pinyin(text, { type: "first" })); // "c q c j d q"
console.log(pinyin(text, { separator: "-" })); // "chóng-qìng-cháng-jiāng-dà-qiáo"
// 瀏覽器直接使用 (IIFE 版)
/* <script src="https://cdn.jsdelivr.net/npm/pinyin-pro/dist/index.umd.min.js"></script>
pinyin("測試"); // 全域變數 pinyin */
| 場景 | 推薦方案 | 關鍵配置 |
|---|---|---|
| 用戶輸入即時轉拼音 (搜尋提示) | pinyin-pro | debounce 300ms、type="first" 索引優化 |
| 姓名/地址拼音註音顯示 | pinyin-pro | mode="pinyin"、separator=" "、keepNonChinese=true |
| 排序索引 (通訊錄、城市列表) | pinyin-pro | type="no-tone"、去除分隔符、大寫首字母 |
| 輸入法候選、拼音輸入輔助 | 專用輸入法引擎 (RIME、ibus) | 非前端範疇 |
| 舊專案維護、無建構工具 | jQuery.Hz2Py.js | 直接引入、即用即走 |
Map 緩存已轉換字串,重複輸入直接讀取jQuery.Hz2Py.js 曾是前端漢字轉拼音的主流選擇,但受限於無多音字支援、jQuery 依賴、停止維護。新專案強烈建議採用 pinyin-pro:原生 ESM、TypeScript 完整支援、智能多音字、極小體積、Tree-shaking 友善。若維護舊專案,可繼續使用 Hz2Py 並建立遷移計畫。