萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery.Hz2Py.js 漢字轉拼音插件:原理、使用與現代替代方案

插件簡介

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>

HTML 結構

<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();
});

插件核心 API

方法參數回傳說明
$.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

解決方案:引入分詞庫(如 pinyin、jieba)結合語境判斷,或提供用戶手動選擇介面。

現代替代方案對比

方案優點缺點體積環境
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專注模糊搜尋/匹配、高效能非通用轉換~10KBNode + 瀏覽器

現代專案整合範例 (pinyin-pro + Vite)

// 安裝: 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-prodebounce 300ms、type="first" 索引優化
姓名/地址拼音註音顯示pinyin-promode="pinyin"、separator=" "、keepNonChinese=true
排序索引 (通訊錄、城市列表)pinyin-protype="no-tone"、去除分隔符、大寫首字母
輸入法候選、拼音輸入輔助專用輸入法引擎 (RIME、ibus)非前端範疇
舊專案維護、無建構工具jQuery.Hz2Py.js直接引入、即用即走

效能優化建議

  • Web Worker:大量文本轉換移至背景執行緒,避免阻塞主執行緒
  • 緩存結果:Map 緩存已轉換字串,重複輸入直接讀取
  • 按需載入詞典:pinyin-pro 支援動態 import 詞典分塊
  • 避免逐字轉換:批次處理字串,減少函數調用開銷

總結

jQuery.Hz2Py.js 曾是前端漢字轉拼音的主流選擇,但受限於無多音字支援、jQuery 依賴、停止維護。新專案強烈建議採用 pinyin-pro:原生 ESM、TypeScript 完整支援、智能多音字、極小體積、Tree-shaking 友善。若維護舊專案,可繼續使用 Hz2Py 並建立遷移計畫。

copyright © 萬盛學電腦網 all rights reserved