新增功能

輸入法擴(kuò)展API支持轉(zhuǎn)換器擴(kuò)展，在用戶開啟轉(zhuǎn)換器時(shí)，可以對候選項(xiàng)做諸如裝飾、特效、變換等操作。

新增一組用于UNICODE編碼轉(zhuǎn)換的字符串實(shí)用函數(shù)。

入門

為了幫助開發(fā)者在谷歌拼音輸入法的基本輸入功能基礎(chǔ)上，開發(fā)和定義更豐富的擴(kuò)展輸入功能，谷歌拼音輸入法提供了以Lua腳本編程語言為基礎(chǔ)的輸入法擴(kuò)展API。利用輸入法擴(kuò)展API，開發(fā)者可以編寫自定義的輸入功能，并將腳本分享給谷歌拼音輸入法的用戶安裝、使用。

一段簡單的Lua腳本程序就可以構(gòu)成一個最基本的輸入法擴(kuò)展模塊。下面是“Hello,World!”程序示例：

helloworld.lua

function HelloWorld()  
return "Hello,World!"  
end  
ime.register_command("hw", "HelloWorld", "test") 

這一段代碼由一個自定義的Lua函數(shù)和一行ime.register_command函數(shù)調(diào)用組成。自定義的Lua函數(shù)HelloWorld()簡單地返回一個Lua字符串"Hello,World!"，這表明該輸入法擴(kuò)展函數(shù)被調(diào)用后，顯示給最終用戶的候選項(xiàng)為"Hello,World!"。ime.register_command函數(shù)調(diào)用將自定義函數(shù)注冊為谷歌拼音輸入法的一個命令擴(kuò)展。其中，第一個參數(shù)"hw"表示該命令擴(kuò)展在i擴(kuò)展模式中對應(yīng)的命令是"hw"，第二個參數(shù)表示該命令擴(kuò)展對應(yīng)的入口函數(shù)(自定義的Lua函數(shù))是"HelloWorld"，第三個參數(shù)是顯示在i擴(kuò)展模式命令列表內(nèi)的簡短說明文字。

使用任何文本編輯器輸入上述程序后，以helloworld.lua為文件名保存到安裝有谷歌拼音輸入法的計(jì)算機(jī)中。然后，打開谷歌拼音輸入法選項(xiàng)設(shè)置窗口，在"擴(kuò)展"頁面中，點(diǎn)擊"安裝擴(kuò)展包"按鈕，選擇保存在計(jì)算機(jī)內(nèi)的helloworld.lua(也可以從Windows資源管理器，右鍵單擊helloworld.lua文件，選擇“安裝到谷歌拼音輸入法”)。安裝后，打開記事本程序，切換到谷歌拼音輸入法，鍵入"ihw"，谷歌拼音輸入法的候選項(xiàng)窗口中將出現(xiàn)唯一候選項(xiàng)"Hello,World!"。

 

 

除了顯式用"ihw"這樣的命令來激活擴(kuò)展函數(shù)以外，擴(kuò)展函數(shù)還可以由用戶在使用拼音輸入法時(shí)輸入的特定內(nèi)容或特定候選詞激活。例如，在上述helloworld.lua最后添加一行：

ime.register_trigger("HelloWorld", "test", { "hello" }, {}) 

這一行的作用是將函數(shù)"HelloWorld"注冊為谷歌拼音輸入法的一個整合擴(kuò)展。第一個參數(shù)是擴(kuò)展對應(yīng)的入口函數(shù)"HelloWorld"，第二個參數(shù)是簡短說明文字，第三個參數(shù)給出希望將擴(kuò)展關(guān)聯(lián)到哪個或哪幾個用戶輸入串(這里是字符串"hello")，第四個參數(shù)給出希望將擴(kuò)展關(guān)聯(lián)到哪個或哪幾個特定的候選詞(這里是空表，表示不關(guān)聯(lián))。

打開谷歌拼音輸入法選項(xiàng)設(shè)置窗口，在"擴(kuò)展"頁面中，使用"移除擴(kuò)展包"按鈕將剛才安裝的helloworld.lua刪除，然后重新安裝更新后的helloworld.lua。打開記事本程序，切換到谷歌拼音輸入法，鍵入"hello"，谷歌拼音輸入法的候選項(xiàng)窗口中，除了出現(xiàn)通常的中文英文候選詞提示外，還將出現(xiàn)由整合擴(kuò)展函數(shù)返回的候選項(xiàng)"Hello,World!"。

 

 

事實(shí)上，谷歌拼音輸入法提供的輸入法擴(kuò)展API可以用來開發(fā)各種不同的輸入體驗(yàn)，例如，根據(jù)用戶輸入的參數(shù)返回相應(yīng)的信息內(nèi)容，查表輸入特定的文字信息，完成自定義的甚至包含隨機(jī)變量的計(jì)算并以不同形式返回結(jié)果，將用戶剛剛輸入的文字內(nèi)容轉(zhuǎn)換為另一種表現(xiàn)形式，等等。谷歌拼音輸入法提供的i模式的缺省功能，包括時(shí)間和日期格式轉(zhuǎn)換，查星座，擲骰子，打印字符等，都是一些最簡單的示例。

本指南的后續(xù)內(nèi)容詳細(xì)介紹了開發(fā)輸入法擴(kuò)展所需要的各種知識。我們也鼓勵開發(fā)者直接參考已有的示例程序。例如，i擴(kuò)展模式的缺省功能是由安裝在以下位置的Lua腳本程序?qū)崿F(xiàn)的：

XP: C:\Documents and Settings\All Users\Application Data\Google\Google Pinyin 2\Extensions\base.lua

Vista / Windows 7: C:\ProgramData\Google\Google Pinyin 2\Extensions\base.lua

三種不同的擴(kuò)展方式

谷歌拼音輸入法擴(kuò)展API提供了三種擴(kuò)展拼音輸入法的方式：命令擴(kuò)展、整合擴(kuò)展與轉(zhuǎn)換器擴(kuò)展。

命令擴(kuò)展：將腳本程序中的某個入口函數(shù)關(guān)聯(lián)到一個兩字母長的自定義命令。當(dāng)用戶先鍵入i然后鍵入該命令時(shí)，輸入法即激活該擴(kuò)展函數(shù)，然后在候選項(xiàng)列表中顯示擴(kuò)展函數(shù)返回的候選項(xiàng)結(jié)果。

命令擴(kuò)展適用于那些用戶明確希望在特定場景下使用特定輸入功能，且候選項(xiàng)較多，或較復(fù)雜的情況。例如，用戶明確希望根據(jù)生日查詢并輸入星座信息等。

整合擴(kuò)展：將腳本程序中的某個入口函數(shù)關(guān)聯(lián)到特定的鍵盤輸入串，或特定的中英文候選項(xiàng)。當(dāng)用戶使用拼音輸入法時(shí)，一旦用戶通過鍵盤輸入的字符串與整合擴(kuò)展關(guān)聯(lián)的特定字符串(可包含通配符)匹配，或拼音輸入法解析出的某個候選項(xiàng)與整合擴(kuò)展關(guān)聯(lián)的特定字符串(可包含通配符)匹配，輸入法即激活該擴(kuò)展函數(shù)，并將擴(kuò)展函數(shù)返回的候選項(xiàng)結(jié)果插入到候選項(xiàng)列表中。

整合擴(kuò)展適用于那些在不妨礙用戶正常輸入的情況下，根據(jù)當(dāng)前輸入或候選內(nèi)容，插入少數(shù)相關(guān)候選項(xiàng)的情況。例如，用戶在輸入中文“時(shí)間”的同時(shí)，也可能希望直接輸入當(dāng)前時(shí)間，這時(shí)，整合擴(kuò)展直接把擴(kuò)展函數(shù)返回的當(dāng)前時(shí)間整合至候選項(xiàng)列表中，就顯得比較方便了。

轉(zhuǎn)換器擴(kuò)展：將腳本程序中的某個入口函數(shù)注冊為一個特定的轉(zhuǎn)換器。當(dāng)用戶通過輸入法的用戶界面(如功能菜單)開啟該轉(zhuǎn)換器時(shí)，輸入法產(chǎn)生的每個候選項(xiàng)被依次當(dāng)做參數(shù)送入該轉(zhuǎn)換器函數(shù)，進(jìn)行運(yùn)算后，函數(shù)返回的結(jié)果將會替換掉原候選項(xiàng)的內(nèi)容，被輸入法顯示在相應(yīng)位置。

轉(zhuǎn)換器擴(kuò)展必須由用戶主動開啟。一旦開啟，就會應(yīng)用于所有候選項(xiàng)。因此，轉(zhuǎn)換器擴(kuò)展適用于為所有候選項(xiàng)增加裝飾、特效，或者對所有候選項(xiàng)按規(guī)則進(jìn)行變換的情形。例如，為候選項(xiàng)或候選項(xiàng)的每個字增加星號修飾，直接在候選項(xiàng)的每個字后面輸出該字對應(yīng)的Unicode編碼，將簡體漢字變?yōu)榉斌w漢字，等等。

下表對不同的擴(kuò)展方式進(jìn)行簡單的對比：

擴(kuò)展方式	命令擴(kuò)展	整合擴(kuò)展	轉(zhuǎn)換器擴(kuò)展
注冊方式	ime.register_command (...)	ime.register_trigger (...)	ime.register_converter (...)
適用范圍	用戶明確希望在特定場景下使用特定輸入功能，且候選項(xiàng)較多，或較復(fù)雜的情況	在不妨礙用戶正常輸入的情況下，根據(jù)當(dāng)前輸入或候選內(nèi)容，插入少數(shù)相關(guān)候選項(xiàng)的情況	為所有候選項(xiàng)增加裝飾、特效，或者對所有候選項(xiàng)按規(guī)則進(jìn)行變換的情形
應(yīng)用實(shí)例	根據(jù)輸入的生日查詢星座；列舉并輸入特定的字符畫	用戶輸入中文“時(shí)間”時(shí)，在候選項(xiàng)列表里插入當(dāng)前時(shí)間；用戶輸入中文“哈哈”時(shí)，在候選項(xiàng)列表插入相應(yīng)的表情符號	為候選項(xiàng)或候選項(xiàng)的每個字增加星號修飾；直接在候選項(xiàng)的每個字后面輸出該字對應(yīng)的Unicode編碼；將簡體漢字變?yōu)榉斌w漢字
激活方式	用戶輸入i加2字符長的命令，激活相應(yīng)的命令擴(kuò)展	用戶輸入的拼音字符串或輸入法產(chǎn)生的某個候選項(xiàng)與整合擴(kuò)展關(guān)聯(lián)的特定字符串（可包含通配符）匹配時(shí)，激活相應(yīng)的整合擴(kuò)展	用戶從輸入法的用戶界面（如功能菜單）開啟特定的轉(zhuǎn)換器，激活相應(yīng)的轉(zhuǎn)換器擴(kuò)展

#p#

注冊命令擴(kuò)展

在Lua腳本中，向谷歌拼音輸入法注冊一個命令擴(kuò)展的基本語法是：

ime.register_command(command_name, lua_function_name, description, leading, help) 

ime是提供給Lua腳本使用的，與輸入法內(nèi)核交互的專用模塊。register_command是向谷歌拼音輸入法注冊新的i擴(kuò)展模式命令擴(kuò)展所使用的函數(shù)。函數(shù)的各參數(shù)含義如下：

◆ command_name

2字符長的字符串，必須由兩個英文字母(a-z)組成。定義了要注冊的命令名字。如果新注冊的命令名稱和此前已經(jīng)注冊的某個命令重名(判斷重名時(shí)不區(qū)分大小寫)，則register_command函數(shù)調(diào)用失敗，新命令擴(kuò)展無法注冊到輸入法中。

◆ lua_function_name

字符串。給出此命令在i擴(kuò)展模式中運(yùn)行時(shí)對應(yīng)的Lua入口函數(shù)。這必須是一個已經(jīng)存在的，接收一個或零個參數(shù)的Lua函數(shù)。

◆ description

字符串。命令的簡短描述。此描述會顯示在i擴(kuò)展模式的命令選擇界面中，向用戶簡要說明某命令的功能。不要使用太長的簡短描述，一般不要超過10個字符。

◆ leading [可省略]

字符串。用戶選擇此命令的候選項(xiàng)目時(shí)，可以使用的快捷鍵，可以是以下三個特定字符串之一：

"digit": 默認(rèn)值。表示用1, 2, 3, ...這樣的數(shù)字作為候選項(xiàng)選擇鍵。

"alpha": 表示用a, b, c, ...這樣的英文字母序列作為候選項(xiàng)選擇鍵。

"none": 表示不使用候選項(xiàng)選擇鍵。

注：默認(rèn)情況下，輸入法使用1, 2, 3, ...數(shù)字鍵作為候選項(xiàng)選擇鍵。但是，當(dāng)i擴(kuò)展模式的某個命令希望接收數(shù)字1, 2, 3, ...作為自己的參數(shù)時(shí)，為避免沖突，就不能使用"digit"方式的候選項(xiàng)選擇鍵了。同理，當(dāng)命令希望接收包含英文字母的參數(shù)時(shí)，就不能使用"alpha"作為候選項(xiàng)選擇鍵。

◆ help [可省略]

字符串。比description略長的幫助信息，但一般不要超過50個字。當(dāng)用戶鍵入了"i"以及特定的命令名后，輸入法候選窗口的右上方會顯示此文字信息，用于提示用戶如何輸入后續(xù)參數(shù)。

lua_function_name給出的命令入口函數(shù)可以接收一個或零個參數(shù)，例如：

function my_entry_function()  
  -- 做某些處理并返回結(jié)果  
end 

當(dāng)入口函數(shù)接收一個參數(shù)時(shí)，輸入法會把用戶在i擴(kuò)展模式中i+兩字母命令名輸完后繼續(xù)輸入的所有內(nèi)容作為一個字符串參數(shù)，傳給入口函數(shù)。例如，用戶先后鍵入“ihw123”，則，用戶激活的命令名是“hw”，輸入法調(diào)用該命令對應(yīng)入口函數(shù)時(shí)，以字符串方式傳入?yún)?shù)“123”。入口函數(shù)可以對參數(shù)進(jìn)行運(yùn)算處理，并返回對應(yīng)的結(jié)果。例如：

function my_entry_function(argument)

-- 將參數(shù)argument轉(zhuǎn)換為數(shù)字，計(jì)算并返回其平方根...

end

注冊命令擴(kuò)展時(shí)傳入的提示信息description會在用戶看到i擴(kuò)展模式的命令列表時(shí)顯示，以提示用戶該命令的功能。這個字符串應(yīng)當(dāng)盡量簡短(不超過10個字符)。如下圖中的“擲骰子”，“打印字符”等，都是description：

 

 

注冊命令擴(kuò)展時(shí)傳入的提示信息help會在用戶選中了某特定命令后，顯示在輸入法候選窗口的右上角。這個字符串可以比description略長，但一般也不要超過50個字符。例如，下圖中用戶選擇了打印字符命令“zf”后，顯示出來的“請輸入字母或數(shù)字序列，例如hello”就是help的內(nèi)容：

 

 

注冊整合擴(kuò)展

在Lua腳本中，向谷歌拼音輸入法注冊一個整合擴(kuò)展的基本語法是：

ime.register_trigger(lua_function_name, description, input_trigger_strings, candidate_trigger_strings) 

ime是提供給Lua腳本使用的，與輸入法內(nèi)核交互的專用模塊。register_trigger是向谷歌拼音輸入法注冊新的整合擴(kuò)展所使用的函數(shù)。函數(shù)的各參數(shù)含義如下：

◆ lua_function_name

字符串。給出此擴(kuò)展運(yùn)行時(shí)對應(yīng)的Lua入口函數(shù)。這必須是一個已經(jīng)存在的，接收一個參數(shù)的Lua函數(shù)。

◆ description

字符串。擴(kuò)展功能的簡短描述，向用戶簡要說明某擴(kuò)展的功能。不要使用太長的簡短描述，一般不要超過10個字符。

◆ input_trigger_strings

一個字符串組成的Lua列表，包含零個或多個特定的由英文字母或通配符*組成的字符串。這里給出的所有字符串在輸入法運(yùn)行時(shí)將分別與用戶的輸入內(nèi)容匹配，一旦用戶的輸入和給出的某個特定字符串相同(或使用通配符匹配成功)，注冊的擴(kuò)展函數(shù)就會被調(diào)用，擴(kuò)展函數(shù)返回的候選項(xiàng)結(jié)果將會被插入到輸入法的候選項(xiàng)列表中。

◆ candidate_trigger_strings

一個字符串組成的Lua列表，包含零個或多個特定的由英文、中文、數(shù)字等可顯示字符或通配符*組成的字符串。這里給出的所有字符串在輸入法運(yùn)行時(shí)將分別與輸入法得到的候選項(xiàng)進(jìn)行匹配，一旦候選項(xiàng)列表第一頁中某個候選項(xiàng)和給出的某個特定字符串相同(或使用通配符匹配成功)，注冊的擴(kuò)展函數(shù)就會被調(diào)用，擴(kuò)展函數(shù)返回的候選項(xiàng)結(jié)果將會被插入到輸入法的候選項(xiàng)列表中。

關(guān)于通配符匹配：input_trigger_strings和candidate_trigger_strings中的字符串可以在開頭或結(jié)尾包含通配符*，表示前綴匹配或后綴匹配。例如：

◆ abc*

表示匹配前綴為abc的任意字符串。例如，字符串a(chǎn)bc，abcd，abcde都可以與之成功匹配。

◆ *abc

表示匹配后綴為abc的任意字符串。例如，字符串a(chǎn)bc，dabc，deabc都可以與之成功匹配。

使用ime.register_trigger注冊整合擴(kuò)展時(shí)，請注意以下幾點(diǎn)：

◆ 參數(shù)input_trigger_strings和candidate_trigger_strings不能同時(shí)為空表。

◆ 輸入法在激活整合擴(kuò)展函數(shù)時(shí)，將優(yōu)先匹配input_trigger_strings，然后再匹配candidate_trigger_strings。匹配candidate_trigger_strings時(shí)，會按照輸入法得到的候選項(xiàng)順序依次嘗試。對每一次輸入，一旦找到了匹配，就只插入該匹配對應(yīng)的擴(kuò)展函數(shù)返回的候選項(xiàng)結(jié)果，不再繼續(xù)嘗試其他匹配。

◆ 雖然擴(kuò)展函數(shù)可以返回一個或多個結(jié)果，但對于整合擴(kuò)展來說，目前只有第一個候選項(xiàng)結(jié)果會被插入到輸入法的候選項(xiàng)列表中。

◆ 目前一個整合擴(kuò)展可以通過input_trigger_strings和candidate_trigger_strings注冊的字符串?dāng)?shù)目是有限制的，一般不要超過200個。

◆ 目前整合擴(kuò)展在匹配candidate_trigger_strings時(shí)，只會與候選項(xiàng)列表第一頁中的候選項(xiàng)進(jìn)行匹配。

整合擴(kuò)展的入口函數(shù)一般應(yīng)接收一個參數(shù)。在激活整合擴(kuò)展函數(shù)時(shí)，輸入法會把激活整合擴(kuò)展函數(shù)的字符串(或者是用戶輸入的內(nèi)容，或者是某個特定的候選項(xiàng))作為唯一的參數(shù)傳遞給入口函數(shù)。這樣，注冊了多個匹配字符串的整合擴(kuò)展函數(shù)就可以在被調(diào)用時(shí)通過參數(shù)知道究竟是哪個字符查激活了自己。當(dāng)然，在不需要時(shí)，入口函數(shù)也可以簡單地忽略這個參數(shù)。

注冊轉(zhuǎn)換器擴(kuò)展

在Lua腳本中，向谷歌拼音輸入法注冊一個轉(zhuǎn)換器擴(kuò)展的基本語法是：

ime.register_converter(lua_function_name, description) 

ime是提供給Lua腳本使用的，與輸入法內(nèi)核交互的專用模塊。register_converter是向谷歌拼音輸入法注冊新的轉(zhuǎn)換器擴(kuò)展所使用的函數(shù)。函數(shù)的各參數(shù)含義如下：

◆ lua_function_name

字符串。給出此擴(kuò)展運(yùn)行時(shí)對應(yīng)的Lua入口函數(shù)。這必須是一個已經(jīng)存在的，接收一個參數(shù)的Lua函數(shù)。

◆ description

字符串。擴(kuò)展功能的簡短描述，向用戶簡要說明某擴(kuò)展的功能。不要使用太長的簡短描述，一般不要超過10個字符。對于轉(zhuǎn)換器擴(kuò)展，此描述信息會被輸入法的用戶界面顯示給用戶，以便選擇特定的轉(zhuǎn)換器擴(kuò)展。

用戶開啟轉(zhuǎn)換器時(shí)，輸入法會依次將每個候選項(xiàng)作為參數(shù)調(diào)用轉(zhuǎn)換器對應(yīng)的Lua入口函數(shù)。也就是說，對于每個候選項(xiàng)，Lua入口函數(shù)都被調(diào)用一次。

轉(zhuǎn)換器擴(kuò)展對應(yīng)的Lua入口函數(shù)應(yīng)當(dāng)返回且只返回一個結(jié)果，即返回對原候選項(xiàng)進(jìn)行變換后的新候選項(xiàng)。如果不希望變換某個候選項(xiàng)，可以將輸入?yún)?shù)的值直接返回。如果沒有返回任何結(jié)果，或返回的結(jié)果數(shù)目多于一個，則輸入法認(rèn)為該擴(kuò)展函數(shù)沒有對候選項(xiàng)做任何變換。

安裝了轉(zhuǎn)換器擴(kuò)展后，用戶可以從輸入法的用戶界面啟動或關(guān)閉特定的轉(zhuǎn)換器。如下圖，從功能菜單開啟或關(guān)閉特定的轉(zhuǎn)換器：

 

 

#p#

返回候選項(xiàng)

一般的，擴(kuò)展對應(yīng)的入口函數(shù)可以返回一個或多個候選字符串。命令擴(kuò)展會顯示所有返回的候選項(xiàng)，整合擴(kuò)展目前只會將第一個候選項(xiàng)結(jié)果插入到輸入法的候選項(xiàng)列表中，而轉(zhuǎn)換器擴(kuò)展則只接受返回一個候選字符串的入口函數(shù)。

返回的參數(shù)類型可以是Lua字符串類型，也可以是Lua數(shù)字類型，還可以是Lua布爾類型。但這些返回值返回輸入法內(nèi)核后，都會被轉(zhuǎn)換成字符串顯示給最終用戶，以便用戶選擇輸入。

要返回唯一的候選字符串，只要直接使用return語句返回字符串、數(shù)字或布爾值即可，例如：

function TestString(argument)  
  -- 做某些處理  
  return "a string"  
end  
 
function TestNumber(argument)  
  -- 做某些處理  
  return 1234.56789  
end  
 
function TestBoolean(argument)  
  -- 做某些處理  
  return true  
end  
 
function TestAnotherBoolean(argument)  
  -- 做某些處理  
  return 3 > 2  
end 

要返回兩個或更多結(jié)果，只要返回一個Lua的列表對象即可，例如：

function TestTable(argument)  
  return {"abc", "def", "ghi", 123, true}  
end 

列表中的每個元素可以是Lua字符串，數(shù)字或布爾值，但不能嵌套列表。列表中的每個元素將對應(yīng)于輸入法顯示給用戶的候選項(xiàng)列表中的一個候選項(xiàng)。上面這個函數(shù)返回的列表在輸入法中的顯示如下圖所示：

 

 

除了單行字符串結(jié)果外，命令擴(kuò)展的入口函數(shù)還可以返回一個或多個包含換行符的多行結(jié)果(其他擴(kuò)展方式，如整合擴(kuò)展和轉(zhuǎn)換器擴(kuò)展，目前不建議返回多行的結(jié)果)。換行符在Lua程序的字符串常量中用"\n"表示。例如下面的函數(shù)：

function TestMultilines(argument)  
  return "line 1" .. "\n" .. "line 2" .. "\n" .. "line 3"  
end 

多行結(jié)果在輸入法的候選窗口中被顯示為“<字符畫>”，當(dāng)用戶選擇輸入該候選項(xiàng)后，多行文本被插入到用戶當(dāng)前文檔中，如下圖：

 

 

返回提示信息

對于命令擴(kuò)展，當(dāng)用戶剛輸入完i擴(kuò)展模式的命令名稱，尚未輸入命令參數(shù)時(shí)，入口函數(shù)將被調(diào)用，此時(shí)傳給入口函數(shù)的參數(shù)為空字符串。這時(shí)，入口函數(shù)可以通過返回一個提示信息表，來提示用戶有幾種預(yù)定義的候選參數(shù)，并在輸入法的候選窗口中，允許用戶直接選擇某個預(yù)定義參數(shù)。例如：

function TestMetatables(argument)  
  if #argument == 0 then  
    -- 如果沒有參數(shù)，則返回提示信息表，以便用戶直接選擇預(yù)定義的參數(shù)"num"或"chs"  
    return { { suggest = "num", help = "數(shù)字123" },  
             { suggest = "chs", help = "中文一二三" },  
           }  
  elseif argument == "num" then  
    -- 如果參數(shù)是"num"（可能是用戶鍵入的，也可能是用戶根據(jù)提示信息表直接選擇的），則返回?cái)?shù)字結(jié)果  
    return 123  
  elseif argument == "chs" then  
    -- 如果參數(shù)是"chs"（可能是用戶鍵入的，也可能是用戶根據(jù)提示信息表直接選擇的），則返回中文結(jié)果  
    return "一二三"  
  end  
end 

返回的提示信息表必須符合上述格式，即，表中的每個元素都是一個子表，每個子表內(nèi)有兩個元素：鍵名suggset的元素表示要提示用戶輸入的一個候選參數(shù)，鍵名help的元素表示對該參數(shù)的簡短說明文字(不要超過10個字符)。上述入口函數(shù)在用戶沒有輸入?yún)?shù)時(shí)，輸入法顯示的提示窗口如下圖：

 

 

這時(shí)，用戶可以試用上下鍵，翻頁鍵和鼠標(biāo)選擇自己要輸入的參數(shù)，也可以直接用鍵盤輸入。

其他擴(kuò)展方式，如整合擴(kuò)展和轉(zhuǎn)換器擴(kuò)展，不支持提示選擇參數(shù)功能，它們將忽略入口函數(shù)返回的此類提示信息。

使用ime模塊

在開發(fā)者編寫的Lua腳本中，代碼除了可以調(diào)用Lua本身提供的各模塊功能(是標(biāo)準(zhǔn)Lua運(yùn)行環(huán)境所提供功能的一個子集)，還可以使用ime模塊訪問輸入法的相關(guān)信息，以實(shí)現(xiàn)與輸入法有關(guān)的特定功能。

例如，可以使用ime模塊的get_last_commit()函數(shù)獲得用戶上一次鍵入的字符串，并根據(jù)字符串的內(nèi)容進(jìn)行相應(yīng)的計(jì)算，返回特定結(jié)果。比如，用戶鍵入了“你好”，然后使用i擴(kuò)展模式中的某個功能，該功能看到“你好”后，自動返回“hello”。實(shí)現(xiàn)這一簡單邏輯的代碼如下：

function TestConvertHello()  
  if ime.get_last_commit() == "你好" then  
    return "hello"  
  else  
    return "not found"  
  end  
end 

更詳細(xì)的信息請參見API參考一節(jié)中有關(guān)ime模塊的部分。

錯誤處理

Lua入口函數(shù)接收無法處理的參數(shù)，或者發(fā)生其他內(nèi)部錯誤時(shí)，可以簡單地不返回任何參數(shù)，或者使用Lua語言內(nèi)置的error()函數(shù)向輸入法報(bào)告錯誤信息，例如：

function TestIgnoreError(argument)  
  if #argument > 5 then  
    return  
  end  
  return 123  
end  
 
function TestReportError(argument)  
  if #argument > 5 then  
    error("argument length > 5")  
  end  
  return 123  
end 

使用error()函數(shù)報(bào)告的錯誤信息不會在輸入法用戶界面中顯示，但可以使用控制臺工具測試腳本程序并查看錯誤信息。參見下面的開發(fā)與調(diào)試一節(jié)。

開發(fā)和調(diào)試

輸入法擴(kuò)展腳本程序可以使用任何源代碼/文本編輯器創(chuàng)建。在將輸入法擴(kuò)展包安裝到谷歌拼音輸入法之前，可以使用控制臺工具測試擴(kuò)展程序，以確保程序功能正確。請從以下鏈接下載用于開發(fā)調(diào)試谷歌拼音輸入法擴(kuò)展腳本的控制臺工具：

下載控制臺工具 (GooglePinyinApiConsole.exe) http://dl.google.com/pinyin/v2/GooglePinyinApiConsole.exe

在命令行運(yùn)行控制臺工具GooglePinyinApiConsole.exe時(shí)，需要給出的命令行參數(shù)是一個或多個待測試的腳本文件路徑，控制臺工具會加載所有指定的輸入法擴(kuò)展腳本，并啟動一個交互式界面，供開發(fā)者測試執(zhí)行擴(kuò)展模式。例如：

GooglePinyinApiConsole.exe ext1.lua ext2.lua ext3.lua 

在控制臺工具的交互式界面中，鍵入"help"，可以查看幫助信息：

i - 列出所有已注冊的命令擴(kuò)展

i [COMMAND] - 無參數(shù)執(zhí)行某命令擴(kuò)展

i [COMMAND] [ARGUMENT] - 有參數(shù)執(zhí)行某命令擴(kuò)展

g [TRIGGER_STRING] - 嘗試?yán)媚匙址畢?shù)激活整合擴(kuò)展

c - 列出所有已注冊的轉(zhuǎn)換器擴(kuò)展

c [FUNCTION] [STRING] - 測試轉(zhuǎn)換器函數(shù)

quit - 退出控制臺工具

help - 顯示幫助信息

當(dāng)腳本加載或執(zhí)行過程中發(fā)生錯誤時(shí)，控制臺工具會打印顯示錯誤信息。錯誤信息包括發(fā)生錯誤的腳本文件名，錯誤行號，錯誤內(nèi)容等。

控制臺工具并不是真實(shí)的輸入法運(yùn)行環(huán)境，因此，一些和輸入法特定功能相關(guān)的接口，例如，ime.get_last_commit()，在控制臺運(yùn)行的腳本中無法得到實(shí)時(shí)的輸入法相關(guān)信息，這時(shí)，此類函數(shù)的返回值是簡單的固定字符串，如“測試”。整合擴(kuò)展也無法像在輸入法中那樣，將結(jié)果插入在輸入法的候選項(xiàng)列表中。

下圖顯示了使用控制臺工具測試缺省輸入法擴(kuò)展包中各擴(kuò)展功能的情形：

 

 

#p#

關(guān)于Lua語言

目前，谷歌拼音輸入法擴(kuò)展API只提供了Lua一種開發(fā)語言。Lua是一種體積小巧卻功能強(qiáng)大的動態(tài)腳本編程語言，廣泛用于網(wǎng)絡(luò)游戲等應(yīng)用的插件或擴(kuò)展功能的開發(fā)。對于一個有JavaScript語言、VBScript語言或者Python語言開發(fā)經(jīng)驗(yàn)的開發(fā)者來說，學(xué)習(xí)Lua語言并不困難。請參考以下網(wǎng)址獲得關(guān)于Lua語言的各種信息：

Lua編程語言

Lua程序設(shè)計(jì)語言

在輸入法環(huán)境中，每個用戶安裝的輸入法擴(kuò)展都是一個獨(dú)立的Lua語言模塊，每個模塊在自己的名字空間中運(yùn)行。也就是說，不同模塊間的同名符號不會沖突，但不同模塊間也無法相互進(jìn)行功能調(diào)用。用戶安裝的輸入法擴(kuò)展只能調(diào)用API參考一節(jié)描述的Lua內(nèi)置功能函數(shù)和ime模塊提供的輸入法相關(guān)函數(shù)。

API參考

使用Lua語言編寫的輸入法擴(kuò)展程序保存在磁盤上時(shí)，推薦使用UTF-8編碼的文本文件。文本文件可以包含也可以不包含BOM文件頭。沒有BOM文件頭時(shí)，IME缺省認(rèn)為按UTF-8編碼加載。

使用Lua語言編寫的輸入法擴(kuò)展程序可以使用以下內(nèi)置函數(shù)。除了ime模塊提供的輸入法相關(guān)函數(shù)外，這些函數(shù)是標(biāo)準(zhǔn)Lua運(yùn)行環(huán)境的一個子集。因此，在將已有的Lua程序移植到輸入法擴(kuò)展程序之前，請確認(rèn)程序使用的函數(shù)在下表所涵蓋的范圍內(nèi)。

以下凡屬于Lua標(biāo)準(zhǔn)運(yùn)行環(huán)境的函數(shù)，均只給出簡要的功能說明。詳細(xì)用法請參見Lua語言標(biāo)準(zhǔn)函數(shù)庫的說明。

基本功能函數(shù)

◆ assert (v [, message])

斷言。如果v的值是非(nil或false)，就報(bào)告錯誤。

◆ error (message [, level])

報(bào)告錯誤。

◆ ipairs (t)

迭代器函數(shù)。用于對列表中元素的(序號，值)進(jìn)行迭代。

◆ loadstring (string [, chunkname])

加載并執(zhí)行字符串。

◆ next (table [, index])

用于遍歷列表的每個元素。

◆ pairs (t)

迭代器函數(shù)。用于對列表中元素的(鍵，值)進(jìn)行迭代。

◆ select (index, ...)

返回變長參數(shù)列表中從index之后開始的所有參數(shù)。

◆ tonumber (e [, base])

轉(zhuǎn)換為數(shù)字。

◆ tostring (e)

轉(zhuǎn)換為字符串。

◆ type (v)

返回參數(shù)的類型名。

◆ unpack (list [, i [, j]])

返回列表中的各個元素。

字符串處理函數(shù)

◆ string.byte (s [, i [, j]])

返回字符內(nèi)部編碼。

◆ string.char (···)

返回內(nèi)部編碼對應(yīng)的字符串。

◆ string.find (s, pattern [, init [, plain]])

字符串查找。

◆ string.format (formatstring, ···)

字符串格式化。

◆ string.gmatch (s, pattern)

迭代器函數(shù)。用于在字符串中對所有匹配項(xiàng)進(jìn)行迭代。

◆ string.gsub (s, pattern, repl [, n])

字符串全局替換。

◆ string.len (s)

返回字符串長度。

◆ string.lower (s)

轉(zhuǎn)換為小寫。

◆ string.match (s, pattern [, init])

字符串匹配。

◆ string.rep (s, n)

重復(fù)字符串n次。

◆ string.reverse (s)

字符串反轉(zhuǎn)。

◆ string.sub (s, i [, j])

字符串替換。

◆ string.upper (s)

轉(zhuǎn)換為大寫。

日期和時(shí)間函數(shù)

◆ os.date ([format [, time]])

返回格式化的日期時(shí)間字符串。

◆ os.difftime (t2, t1)

返回兩個時(shí)間相差的秒數(shù)。

◆ os.time ([table])

返回當(dāng)前日期，或指定的日期。

數(shù)學(xué)函數(shù)

◆ math.abs (x)

絕對值。

◆ math.acos (x)

反余弦。

◆ math.asin (x)

反正弦。

◆ math.atan (x)

反正切。

◆ math.ceil (x)

向上取整。

◆ math.cos (x)

余弦。

◆ math.cosh (x)

雙曲余弦。

◆ math.deg (x)

弧度轉(zhuǎn)角度。

◆ math.exp (x)

計(jì)算ex

◆ math.floor (x)

向下取整。

◆ math.fmod (x, y)

浮點(diǎn)數(shù)取模。

◆ math.frexp (x)

返回使x = m2e成立的m和e

◆ math.ldexp (m, e)

計(jì)算m2e

◆ math.log (x)

計(jì)算自然對數(shù)。

◆ math.log10 (x)

計(jì)算常用對數(shù)。

◆ math.max (x, ···)

求最大值。

◆ math.min (x, ···)

求最小值。

◆ math.modf (x)

返回浮點(diǎn)數(shù)的整數(shù)和小數(shù)部分。

◆ math.pi

返回π值。

◆ math.pow (x, y)

計(jì)算xy

◆ math.rad (x)

角度轉(zhuǎn)弧度。

◆ math.random ([m [, n]])

生成偽隨機(jī)數(shù)。

◆ math.randomseed (x)

設(shè)置隨機(jī)數(shù)種子。

◆ math.sin (x)

正弦。

◆ math.sinh (x)

雙曲正弦。

◆ math.sqrt (x)

平方根。

◆ math.tan (x)

正切。

◆ math.tanh (x)

雙曲正切。

表處理函數(shù)

◆ table.concat (table [, sep [, i [, j]]])

連接列表元素。

◆ table.insert (table, [pos,] value)

插入元素。

◆ table.maxn (table)

返回最大整數(shù)索引號。

◆ table.remove (table [, pos])

刪除元素。

◆ table.sort (table [, comp])

排序。

ime模塊提供的輸入法相關(guān)函數(shù)

注冊輸入法模塊相關(guān)函數(shù)

◆ ime.register_command (command_name, lua_function_name, description [, leading [, help]])

注冊命令擴(kuò)展。詳細(xì)說明參見注冊命令擴(kuò)展。

◆ ime.register_trigger (lua_function_name, description, input_trigger_strings, candidate_trigger_strings)

注冊整合擴(kuò)展。詳細(xì)說明參見注冊整合擴(kuò)展。

◆ ime.register_converter (lua_function_name, description)

注冊轉(zhuǎn)換器擴(kuò)展。詳細(xì)說明參見注冊轉(zhuǎn)換器擴(kuò)展。

輸入法信息相關(guān)函數(shù)

◆ ime.get_version ()

以字符串方式返回當(dāng)前輸入法的版本號。

◆ ime.get_last_commit ()

返回用戶通過谷歌拼音輸入法輸入的上一個字符串。

實(shí)用工具函數(shù)

◆ ime.int_to_hex_string(value [, width])

將整數(shù)值value轉(zhuǎn)換成16進(jìn)制表示的字符串?？蛇x參數(shù)width指定了結(jié)果字符串的最小長度，不足最小長度時(shí)，高位用"0"補(bǔ)齊。

◆ ime.join_string (str_list, sep)

將str_list列表中的所有字符串連接成一個大字符串，并使用sep作為連接字符，返回結(jié)果字符串。

◆ ime.parse_mapping (src_string, line_sep, key_value_sep, values_sep)

字符串src_string是一個用字符串方式表示的<鍵, 一個或多個值>的映射表，每一行表示一個鍵與其值的映射，行與行之間的分隔字符是line_sep，每行內(nèi)鍵與后續(xù)的一個或多個值之間的分隔字符是key_value_sep，多個值之間的分隔字符是values_sep。ime.parse_mapping解析此格式的字符串，將其轉(zhuǎn)換為Lua語言可直接使用的列表。結(jié)果列表的格式為{key1={value1, value2, ...}, key2={value1, value2, ...}, ...}。此工具函數(shù)的典型應(yīng)用實(shí)例是：在輸入法擴(kuò)展模塊中預(yù)置一個字符串形式、易于閱讀和編輯的映射表(比如一種漢字編碼到對應(yīng)的一個或多個漢字的映射)，然后在擴(kuò)展模塊中用此函數(shù)解析該映射表，以便Lua代碼快速查詢。

示例代碼：

_MAPPING_TABLE = [[  
a 啊  
b 不,吧  
c 從,穿,出  
]]  
 
_MAPPING = ime.parse_mapping(_MAPPING_TABLE, "\n", " ", ",")  
 
function Lookup(input)  
  if _MAPPING[input] then  
    return _MAPPING[input]  
  else  
    error("Invalid argument")  
  end  
end  
 
ime.register_command("lp", "Lookup", "mapping lookup") 

◆ ime.split_string (str, sep)

根據(jù)分隔字符sep，將字符串str拆分為一組字符串，返回這一組字符串組成的列表。

◆ ime.trim_string (str)

去除字符串str左右兩邊的空白字符，返回結(jié)果字符串。

◆ ime.trim_string_left (str)

去除字符串str左邊的空白字符，返回結(jié)果字符串。

◆ ime.trim_string_right (str)

去除字符串str右邊的空白字符，返回結(jié)果字符串。

◆ ime.utf8_to_utf16 (str)

將UTF-8編碼的字符串轉(zhuǎn)換為UTF-16編碼的字符串，返回的結(jié)果字符串以"\0\0"結(jié)尾。

◆ ime.utf16_to_utf8 (str)

將UTF-16編碼的字符串轉(zhuǎn)換為UTF-8編碼的字符串。

原文：http://www.google.com/intl/zh-CN/ime/pinyin/api.html

【編輯推薦】

1. 百度地圖API之如何制作駕車導(dǎo)航
2. 詳解百度地圖API之地圖標(biāo)注
3. 教你如何構(gòu)建簡單Web API
4. Google+開放Hangouts API接口
5. C++中通過LUA API訪問LUA腳本變量學(xué)習(xí)教程