設計文件

Pomelo 輸入法(pomelo-input)

隨 Pomelo 0.36 附上 這是開發者寫的設計筆記,比較技術;一般使用請看使用手冊。

最後更新:2026-10-20(0.33:多語系輸入法、注音選字)

為什麼自己寫

Pomelo 之前靠 fcitx5 或 ibus 打中文。在乾淨的 Pomelo 上實測它們要多裝的東西:

方案 多裝的套件 多佔空間 常駐記憶體
fcitx5 + 新酷音(不裝建議套件) 49 個 約 37 MB 約 30 MB
ibus + 新酷音 79 個 約 235 MB(帶進 GTK、Python) 兩個行程約 28 MB
pomelo-input 5 個 約 4 MB 約 6 MB

多出來的 37 MB 是 hunspell、enchant、pango、gdk-pixbuf、wayland 這些跟注音無關的東西。

有哪些輸入法

只有注音的話,介面換成簡體中文、日文、韓文、越南文的使用者還是要另外裝 fcitx5。0.33 把 pomelo-input 改成 「引擎」的架構(pomelo-input/engine.h),每個語言一個引擎:

引擎(設定裡的 id) 選單列 做法 需要的套件
注音(chewing) 注 libchewing(新酷音),直接連結 跟著 pomelo-input 裝好
拼音(簡體)(rime-pinyin) 拼 librime,方案 luna_pinyin_simp librime + 下載的方案資料
倉頡(rime-cangjie) 倉 librime,方案 cangjie5 同上
速成(rime-quick) 速 librime,方案 quick5 同上
粵拼(rime-jyutping) 粵 librime,方案 jyut6ping3 同上
日文(anthy) あ 羅馬字→假名自己做,假名→漢字交給 Anthy anthy(Fedora/Rocky 是 anthy-unicode)
韓文(hangul) 한 libhangul libhangul
越南文(viet) V Telex/VNI 規則自己寫 不用
  • 注音以外的函式庫都在執行時才 dlopen(libhangul.so.1、librime.so.1、libanthy.so.1 或 libanthy-unicode.so.0),所以 pomelo-input 套件不必相依它們;系統沒裝的引擎在設定頁顯示「要安裝」, 點一下用 install-min(不裝建議套件)在終端機安裝。Ubuntu 22.04/24.04/26.04 的套件名稱不同 (librime1 或 librime1t64),設定頁用 apt-cache show 挑這個系統有的那一個。
  • 介面語言預設啟用的輸入法(還沒自己勾選 input.engines 時):繁中→注音、簡中(zh_CN、zh_SG)→拼音、 港澳(zh_HK、zh_MO)→倉頡+速成、日文→日文、韓文→韓文、越南文→越南文,其他語言不啟用。 pomelo-input 與 pomelo-language 各有一份 default_engines(),要一起改。

Rime(拼音、倉頡、速成、粵拼)

  • librime 的 API 只用到 rime_api.h 定義的結構,所以把 librime 1.10.0 的標頭檔放在 pomelo-input/third-party/ (BSD-3-Clause),編譯時不需要 librime-dev。
  • 方案資料自己下載:Fedora 的 librime 沒附任何方案,Ubuntu 的 rime-data-* 版本又跟著發行版走, 所以各發行版一律從 GitHub 下載固定 commit 的檔案,檢查大小與 SHA256(表在 pomelo-language.c 的 rime_files)。 放在 $XDG_DATA_HOME/pomelo/rime-data;使用者資料(編好的字典、學到的詞)在 $XDG_DATA_HOME/pomelo/rime, 跟 fcitx、ibus 的 Rime 分開。各方案要的檔案:拼音 10.2 MB(prelude、essay、luna_pinyin、stroke), 倉頡再加 0.8 MB,速成再加 0.07 MB,粵拼再加 11.8 MB(倉頡、粵拼互相拿來反查)。
  • 下載在設定頁的背景執行緒跑(curl 一個檔一個檔下載,右邊顯示百分比),好了就自動勾選那個輸入法。 注意 pm_ui_run 讓子行程自動回收(SIGCHLD 忽略),拿不到 curl 的結束碼,所以成功與否看檔案大小與 SHA256。
  • pomelo-input 一啟動、或設定改了(例如剛下載好),就把 default.custom.yaml(方案清單、每頁字數)寫進使用者資料夾; 內容變了才呼叫 start_maintenance(True) 在背景「部署」(編字典,第一次十幾秒)。部署中按鍵照常交給程式, 選字列顯示「正在準備輸入法…」;部署完用新的「世代」重開工作階段。
  • 簡體拼音要 OpenCC 的繁轉簡設定:librime 在方案資料夾的 opencc/ 找,所以建一個連到 /usr/share/opencc 的捷徑 (Ubuntu 的 libopencc-data、Fedora 的 opencc 都會跟著 librime 裝好)。
  • 候選字的註解(粵拼的讀音、倉頡的補碼)用小一號的灰字畫在候選字後面。
  • Rocky 9 沒有 librime(EPEL 也沒有):這四個在設定頁顯示「這個系統沒有」。

日文(Anthy)

  • 羅馬字→平假名是自己的對照表(eng-anthy.c),跟一般日文輸入法一樣:konnnichiha→こんにちは、 kitte→きって(重複子音變っ)、kanji 的 n 後面接子音變ん、nn/n' 都是ん、-→ー、, .→、。。
  • 空白鍵把假名交給 anthy_set_string() 分段轉換;←→ 換段、Shift+←→ 調整段落長度、空白/↑↓ 換候選字、 數字鍵直接選(選完最後一段就送出)、Enter 送出(每段 anthy_commit_segment(),讓 Anthy 學起來)、 Esc/Backspace 回到假名、F6 平假名、F7 片假名。日文鍵盤的「半角/全角」與「変換」鍵也能用。
  • Debian/Ubuntu 的 anthy(1:0.4)與 Fedora/Rocky 的 anthy-unicode 函式名稱一樣,都先設成 UTF-8。

韓文(libhangul)

  • 字母鍵交給 hangul_ic_process();數字、標點、空白、Enter、方向鍵先把組到一半的字送出再交給程式。
  • 鍵盤:兩排式(預設)、三排式(最終)、三排式(390)、羅馬字(input.hangul_kb)。韓文鍵盤的「한/영」鍵切換。
  • Caps Lock 開著時 X 給大寫,但兩排式的大寫是雙子音,所以大小寫照 Shift 判斷。

越南文(Telex、VNI)

  • 自己寫(eng-viet.c,約 270 行),不需要函式庫。一個音節放在組字區,打空白、標點、Enter 時送出。
  • Telex:aa â、aw ă、ee ê、oo ô、ow ơ、uw ư、w ư、dd đ;s f r x j 聲調、z 去掉聲調。 VNI:6 â ê ô、7 ơ ư、8 ă、9 đ;1~5 聲調、0 去掉聲調。同一個鍵按兩次就取消(ass→as)。
  • 聲調位置照傳統規則:有 â ê ô ă ơ ư 的放那個(ươ 放 ơ);兩個母音沒有尾子音放前面(hòa、thủy、của), 有尾子音放後面(toán);三個母音放中間(khoái);qu、gi 的 u、i 算子音(quốc、giữ)。
  • Backspace 刪最後一個字母,聲調跟著移到該放的地方(việt→việ)。
  • input.viet = telex(預設)或 vni。

怎麼做的

  • 程式之間的溝通走 XIM 協定,協定本身用 libxcb-imdkit(fcitx5 自己的 XIM 前端也是用它)。 pomelo-input 是一個 XIM 伺服器,在 root 的 XIM_SERVERS 登記成 @server=pomelo; 程式只要環境變數 XMODIFIERS=@im=pomelo(GTK 程式再加 GTK_IM_MODULE=xim),pomelo-session 會設好。
  • 不登記觸發鍵:所有按鍵都轉到伺服器,由引擎決定吃掉還是原樣轉回去(放開鍵一律轉回)。引擎吃不吃都先把 要送出的字送出,再把沒吃掉的鍵轉回去,順序才對。
  • 狀態寫在 root:_POMELO_INPUT_MODE(zh=用輸入法、en=英文;沒有啟用任何輸入法時是空的)、 _POMELO_INPUT_LABEL(選單列上的字:注、拼、あ、한、V…)、_POMELO_INPUT_ENGINES(每行「id<Tab>字<Tab>名稱<Tab>1=目前」)。 選單列據此畫指示器(英文模式畫「英」,各語言翻譯成 EN、A),點它的選單列出所有啟用的輸入法; pomelo-input --toggle/--next/--engine ID 透過 root 屬性 _POMELO_INPUT_TOGGLE、_POMELO_INPUT_SELECT 通知伺服器。
  • 選字列是自己用 cairo-xcb 畫的 override-redirect 小視窗,跟著 XNSpotLocation 走(程式沒給游標位置時放在 視窗左下);第一行是組字區(已轉好的字+強調色的正在拼的部分+游標),第二行是候選字,第三行是說明。 深色模式與強調色跟系統設定走,設定改了會即時套用。
  • 每個輸入環境(IC)每個引擎各一個 context(第一次用到才建立),程式關掉時一起釋放。

選字(0.33 改進注音的選字)

  • 候選字列開著時 ←→ 移動反白(到頭自動翻上一頁/下一頁)、Enter 選反白的那個、數字鍵直接選。
  • 滑鼠移過去的候選字會反白,點一下就選;滾輪翻頁。右邊顯示「2/5」頁數(Rime 不告訴總頁數時顯示「2 ›」)。
  • libchewing 0.5 沒有 chewing_ack():commit_Check 會一直是 1 直到下一個「新酷音有處理」的按鍵, 所以用 taken 記住這次的字送過了;Ctrl、F5 這些新酷音不處理的鍵不能清掉它,不然上一次的字會再送一次。

操作

  • 輕點 Shift(400 ms 內沒按別的鍵)或 Ctrl+Space:輸入法/英文;切到英文時先把組字區送出。
  • Ctrl+Shift+Space:換下一個輸入法(input.engines 的順序);選單列的指示器也可以選。
  • 韓文鍵盤的「한/영」、日文鍵盤的「半角/全角」:輸入法/英文。
  • 注音:Shift+Space 全形/半形;空白鍵/↓ 開候選字;Esc 清掉;←→ 移游標、Shift+←→ 選詞範圍、Ctrl+數字 加詞 (都是 libchewing 的標準行為)。

Qt 程式(0.33 起,ibus.c)

Qt5/Qt6 沒有 XIM,只認 IBus 與 fcitx 的外掛;IBus 的外掛(libibusplatforminputcontextplugin.so)是 Qt 自己附的, 不用另外裝。所以 pomelo-input 也講 IBus 的 D-Bus 協定:

  • 用 libdbus 開一個只有自己一個服務的小「匯流排」($XDG_RUNTIME_DIR/pomelo-input-ibus-<顯示器>,路徑太長時用抽象 socket; 只接受同一個使用者),位址寫在 ~/.config/ibus/bus/<machine-id>-unix-<顯示器編號>(Qt 照 ibus-daemon 的規則找這個檔, 也會檢查裡面的 IBUS_DAEMON_PID 還活著);結束時刪掉(還是我們寫的才刪)。
  • 回答匯流排的方法(Hello、GetNameOwner、AddMatch…),自己的唯一名稱是 :1.0,訊號都標成從 :1.0 送出(Qt 用這個比對)。
  • CreateInputContext → /org/freedesktop/IBus/InputContext_N;ProcessKeyEvent(keyval, keycode, state) 交給跟 XIM 一樣的 handle_key(IBus 的修飾鍵低 8 位元跟 X 一樣,Super/Meta 當 Mod4,1<<30 是放開);打好的字用 CommitText 訊號, 比 ProcessKeyEvent 的回覆早送,程式先收到字、再處理沒吃掉的鍵。SetCursorLocation 給選字列的位置(螢幕座標)。 組字區照樣畫在我們的選字列裡(沒有送 UpdatePreeditText)。
  • XIM 與 IBus 的輸入環境都是 ic.h 的 IC,共用引擎狀態、選字列與快速鍵。
  • pomelo-session 用 Pomelo 輸入法時設 QT_IM_MODULE=ibus。Qt 的外掛還要在 PATH 找得到 ibus-daemon 才會啟用: 沒裝真的 IBus 時,把 pomelo-input 附的佔位檔(/usr/lib/pomelo-input/qt-ibus/ibus-daemon,什麼都不做)的資料夾加在 PATH 最後面; 「語言與輸入法」判斷有沒有裝 IBus 時跳過這個資料夾。
  • 測試:fcitx5-config-qt(Qt5)的搜尋框,注音「su3cl3」+Enter → 你好,選字列出現在輸入框下面。

設定(settings.conf)

鍵 值 說明
input.framework auto / pomelo / fcitx5 / ibus / none auto 時有裝 pomelo-input 就優先用它
input.engines 例如 chewing,rime-pinyin,anthy 啟用的輸入法與順序(沒設定時照介面語言)
input.engine 引擎 id 目前的輸入法(切換時存起來,重新登入還是同一個)
input.kb KB_DEFAULT / KB_HSU / KB_ET… 注音鍵盤
input.space_select 0/1 注音:空白鍵選字
input.shift_toggle 0/1 輕點 Shift 切換
input.cand_per_page 4~9 每頁候選字(Rime 改了要重新部署)
input.hangul_kb 2 / 3f / 39 / ro 韓文鍵盤
input.viet telex / vni 越南文打字方式

限制

  • Flatpak、Snap 的程式打不了:它們在沙盒裡,Qt 會改用 IBus 的 portal(工作階段匯流排上的 org.freedesktop.portal.IBus),我們還沒有實作。系統套件裝的 Qt 程式可以(見下面「Qt 程式」)。
  • GTK4 程式沒有 XIM 模組;Firefox、Chrome、Electron(VS Code)、LibreOffice 都是 GTK3,沒問題。
  • GTK 程式用的是「over-the-spot」:組字區顯示在我們的小視窗裡,不是直接嵌在程式的文字裡。
  • Rocky 9 沒有 librime:拼音、倉頡、速成、粵拼不能用(日文、韓文、越南文可以)。
  • 日文沒有預測輸入、沒有半形片假名(F8);越南文沒有自動拼字檢查(打英文字請切到英文)。
  • Rime 的使用者資料(學到的詞)與 fcitx/ibus 的 Rime 分開,不會共用;注音的使用者詞庫跟 fcitx5-chewing 一樣用 libchewing 預設的位置。

測試

  • 在 Xvfb :21、隔離的家目錄上:用 pomelo-edit 打字並存檔比對內容。 注音「su3cl3」→你好、↓ 開候選字 → 再 → Enter 選「妳好」;拼音「nihao」→你好、「women」→我们; 倉頡「oiar」→倉;速成「or」→個;粵拼「neihou」→你好(候選字旁邊有讀音);日文「nihongo」→日本語、 「watashihagakuseidesu」分兩段「私は/学生です」、F7「コンピューター」;韓文「dkssudgktpdy」→안녕하세요; 越南文「Tieengs Vieetj raats hay.」→Tiếng Việt rất hay.
  • 越南文的規則另外用單元測試跑 37 組(Telex、VNI、取消、Backspace、大寫)。
  • 設定頁:把一個方案的字典移走 → 顯示「要下載 8.4 MB」→「下載中 37%」→「已啟用」,下載的檔案 SHA256 正確, pomelo-input 跟著重新部署,馬上能打。
  • POMELO_INPUT_DEBUG=1 會把每個 XIM 封包與按鍵決定印到 stderr。