谷歌拼音输入法扩展API开发指南
入门
为了帮助开发者在谷歌拼音输入法的基本输入功能基础上，开发和定义更丰富的扩展输入功能，谷歌拼音输入法提供了以Lua脚本编程语言为基础的输入法扩展API。利用输入法扩展API，开发者可以编写自定义的输入功能，并将脚本分享给谷歌拼音输入法的用户安装、使用。
一段简单的Lua脚本程序就可以构成一个最基本的输入法扩展模块。下面是“Hello,World!”程序示例：
helloworld.lua
function HelloWorld() return "Hello,World!"endime.register_command("hw", "HelloWorld", "test")这一段代码由一个自定义的Lua函数和一行ime.register_command函数调用组成。自定义的Lua函数HelloWorld()简单地返回一个Lua字符串"Hello,World!"，这表明该输入法扩展函数被调用后，显示给最终用户的候选项为"Hello,World!"。ime.register_command函数调用将自定义的输入法扩展函数注册到谷歌拼音输入法中。其中，第一个参数"hw"表示该扩展功能在i扩展模式中对应的命令名是"hw"，第二个参数表示该扩展功能对应的入口函数(自定义的Lua函数)是"HelloWorld"，第三个参数是显示在i扩展模式命令列表内的简短说明文字。
使用任何文本编辑器输入上述程序后，以helloworld.lua为文件名保存到安装有谷歌拼音输入法的计算机中。然后，打开谷歌拼音输入法选项设置窗口，在"扩展"页面中，点击"安装扩展包"按钮，选择保存在计算机内的helloworld.lua。安装后，打开记事本程序，切换到谷歌拼音输入法，键入"ihw"，谷歌拼音输入法的候选项窗口中将出现唯一候选项"Hello,World!"。
事实上，谷歌拼音输入法提供的输入法扩展API可以用来开发各种不同的输入体验，例如，根据用户输入的参数返回相应的信息内容，查表输入特定的文字信息，完成自定义的甚至包含随机变量的计算并以不同形式返回结果，将用户刚刚输入的文字内容转换为另一种表现形式，等等。谷歌拼音输入法提供的i模式的缺省功能，包括时间和日期格式转换，查星座，掷骰子，打印字符等，都是一些最简单的示例。
本指南的后续内容详细介绍了开发输入法扩展所需要的各种知识。我们也鼓励开发者直接参考已有的示例程序，例如i扩展模式的缺省功能是由安装在以下位置的Lua脚本程序实现的：
XP: C:\Documents and Settings\All Users\Application Data\Google\Google Pinyin 2\Extensions\base.luaVista / Windows 7: C:\ProgramData\Google\Google Pinyin 2\Extensions\base.lua
命令和参数
i扩展模式是由安装在用户计算机中的脚本程序定义的多个命令组成的。在谷歌拼音输入法中，用户先键入“i”，再根据提示键入（或选择）两字母长的某个命令，即可实现特定功能。开发者利用扩展API开发的脚本程序在谷歌拼音输入法中注册相关命令并提供命令的实现代码。
在Lua脚本中，向谷歌拼音输入法注册一个命令的基本语法是：
ime.register_command(command_name, lua_function_name, description, leading, help)
ime是提供给Lua脚本试用的，与输入法内核交互的专用模块。register_command是向谷歌拼音输入法注册新的i扩展模式命令所试用的函数。函数的各参数含义如下：
- command_name
- 2字符长的字符串，必须由两个英文字母（a-z）组成。定义了要注册的命令名字。如果新注册的命令名称和此前已经注册的某个命令重名（判断重名时不区分大小写），则register_command函数调用失败，新命令无法注册到输入法中。
- lua_function_name
- 字符串。给出此命令在i扩展模式中运行时对应的Lua入口函数。这必须是一个已经存在的，接收一个或零个参数的Lua函数。
- description
- 字符串。命令的简短描述。此描述会显示在i扩展模式的命令选择界面中，向用户简要说明某命令的功能。不要使用太长的简短描述，一般不要超过10个字符。
- leading [可省略]
- 字符串。用户选择此命令的候选项目时，可以使用的快捷键，可以是以下三个特定字符串之一：
- "digit": 默认值。表示用1, 2, 3, ...这样的数字作为候选项选择键。
- "alpha": 表示用a, b, c, ...这样的英文字母序列作为候选项选择键。
- "none": 表示不使用候选项选择键。
- 注：默认情况下，输入法使用1, 2, 3, ...数字键作为候选项选择键。但是，当i扩展模式的某个命令希望接收数字1, 2, 3, ...作为自己的参数时，为避免冲突，就不能使用"digit"方式的候选项选择键了。同理，当命令希望接收包含英文字母的参数时，就不能使用"alpha"作为候选项选择键。
- help [可省略]
- 字符串。比description略长的帮助信息，但一般不要超过50个字。当用户键入了"i"以及特定的命令名后，输入法候选窗口的右上方会显示此文字信息，用于提示用户如何输入后续参数。
lua_function_name给出的命令入口函数可以接收一个或零个参数，例如：
function my_entry_function() -- 做某些处理并返回结果end
当入口函数接收一个参数时，输入法会把用户在i扩展模式中i+双字母命令名输完后继续输入的所有内容作为一个字符串参数，传给入口函数。例如，用户先后键入“ihw123”，则，用户激活的扩展命令名是“hw”，输入法调用该命令对应入口函数时，以字符串方式传入参数“123”。入口函数可以对参数进行运算处理，并返回对应的结果。例如：
function my_entry_function(argument) -- 将参数argument转换为数字，计算并返回其平方根...end
注册扩展命令时传入的提示信息description会在用户看到i扩展模式的命令列表时显示，以提示用户该命令的功能。这个字符串应当尽量简短（不超过10个字符）。如下图中的“掷骰子”，“打印字符”等，都是description：
注册扩展命令时传入的提示信息help会在用户选中了某特定命令后，显示在输入法候选窗口的右上角。这个字符串可以比description略长，但一般也不要超过50个字符。例如，下图中用户选择了打印字符命令“zf”后，显示出来的“请输入字母或数字序列，例如hello”就是help的内容：
返回候选项
一个命令对应的入口函数可以返回一个或多个候选字符串。返回的参数类型可以是Lua字符串类型，也可以是Lua数字类型，还可以是Lua布尔类型。但这些返回值返回输入法内核后，都会被转换成字符串显示给最终用户，以便用户选择输入。
要返回唯一的候选字符串，只要直接使用return语句返回字符串、数字或布尔值即可，例如：
function TestString(argument) -- 做某些处理 return "a string"endfunction TestNumber(argument) -- 做某些处理 return 1234.56789endfunction TestBoolean(argument) -- 做某些处理 return trueendfunction TestAnotherBoolean(argument) -- 做某些处理 return 3 > 2end
要返回两个或更多结果，只要返回一个Lua的列表对象即可，例如：
function TestTable(argument) return {"abc", "def", "ghi", 123, true}end列表中的每个元素可以是Lua字符串，数字或布尔值，但不能嵌套列表。列表中的每个元素将对应于输入法显示给用户的候选项列表中的一个候选项。上面这个函数返回的列表在输入法中的显示如下图所示：
除了单行字符串结果外，命令的入口函数还可以返回一个或多个包含换行符的多行结果。换行符在Lua程序的字符串常量中用"\n"表示。例如下面的函数：
function TestMultilines(argument) return "line 1" .. "\n" .. "line 2" .. "\n" .. "line 3"end
多行结果在输入法的候选窗口中被显示为“<字符画>”，当用户选择输入该候选项后，多行文本被插入到用户当前文档中，如下图：
返回提示信息
当用户刚输入完i扩展模式的命令名称，尚未输入命令参数时，入口函数将被调用，此时传给入口函数的参数为空字符串。这时，入口函数可以通过返回一个提示信息表，来提示用户有几种预定义的候选参数，并在输入法的候选窗口中，允许用户直接选择某个预定义参数。例如：
function TestMetatables(argument) if #argument == 0 then -- 如果没有参数，则返回提示信息表，以便用户直接选择预定义的参数"num"或"chs" return { { suggest = "num", help = "数字123" }, { suggest = "chs", help = "中文一二三" }, } elseif argument == "num" then -- 如果参数是"num"（可能是用户键入的，也可能是用户根据提示信息表直接选择的），则返回数字结果 return 123 elseif argument == "chs" then -- 如果参数是"chs"（可能是用户键入的，也可能是用户根据提示信息表直接选择的），则返回中文结果 return "一二三" endend返回的提示信息表必须符合上述格式，即，表中的每个元素都是一个子表，每个子表内有两个元素：键名suggset的元素表示要提示用户输入的一个候选参数，键名help的元素表示对该参数的简短说明文字（不要超过10个字符）。上述入口函数在用户没有输入参数时，输入法显示的提示窗口如下图：
这时，用户可以试用上下键，翻页键和鼠标选择自己要输入的参数，也可以直接用键盘输入。
使用ime模块
在开发者编写的Lua脚本中，代码除了可以调用Lua本身提供的各模块功能（是标准Lua运行环境所提供功能的一个子集），还可以使用ime模块访问输入法的相关信息，以实现与输入法有关的特定功能。
例如，可以使用ime模块的get_last_commit()函数获得用户上一次键入的字符串，并根据字符串的内容进行相应的计算，返回特定结果。比如，用户键入了“你好”，然后使用i扩展模式中的某个功能，该功能看到“你好”后，自动返回“hello”。实现这一简单逻辑的代码如下：
function TestConvertHello() if ime.get_last_commit() == "你好" then return "hello" else return "not found" endend
更详细的信息请参见API参考一节中有关ime模块的部分。
错误处理
Lua入口函数接收无法处理的参数，或者发生其他内部错误时，可以简单地不返回任何参数，或者使用Lua语言内置的error()函数向输入法报告错误信息，例如：
function TestIgnoreError(argument) if #argument > 5 then return end return 123endfunction TestReportError(argument) if #argument > 5 then error("argument length > 5") end return 123end使用error()函数报告的错误信息不会在输入法用户界面中显示，但可以使用控制台工具测试脚本程序并查看错误信息。参见下面的开发与调试一节。
开发和调试
输入法扩展脚本程序可以使用任何源代码/文本编辑器创建。在将输入法扩展包安装到谷歌拼音输入法之前，可以使用控制台工具测试扩展程序，以确保程序功能正确。请从以下链接下载用于开发调试谷歌拼音输入法扩展脚本的控制台工具：
下载控制台工具 (GooglePinyinApiConsole.exe)
在命令行运行控制台工具GooglePinyinApiConsole.exe时，需要给出的命令行参数是一个或多个待测试的脚本文件路径，控制台工具会加载所有指定的输入法扩展脚本，并启动一个交互式界面，供开发者测试执行扩展模式命令。例如：
GooglePinyinApiConsole.exe ext1.lua ext2.lua ext3.lua
在控制台工具的交互式界面中，键入"help"，可以查看帮助信息：
i - 列出所有已注册的扩展命令i[COMMAND] - 无参数执行某命令i[COMMAND][ARGUMENT] - 有参数执行某命令quit - 退出控制台工具help - 显示帮助信息
当脚本加载或执行过程中发生错误时，控制台工具会打印显示错误信息。错误信息包括发生错误的脚本文件名，错误行号，错误内容等。
控制台工具并不是真实的输入法运行环境，因此，一些和输入法特定功能相关的接口，例如，ime.get_last_commit()，在控制台运行的脚本中无法得到实时的输入法相关信息，这时，此类函数的返回值是简单的固定字符串，如“测试”。
下图显示了使用控制台工具测试缺省输入法扩展包中各命令功能的情形：
关于Lua语言
目前，谷歌拼音输入法扩展API只提供了Lua一种开发语言。Lua是一种体积小巧却功能强大的动态脚本编程语言，广泛用于网络游戏等应用的插件或扩展功能的开发。对于一个有JavaScript语言、VBScript语言或者Python语言开发经验的开发者来说，学习Lua语言并不困难。请参考以下网址获得关于Lua语言的各种信息：