Google 谷歌拼音输入法

选择语言:

扩展 API 开发指南

新增功能

入门

为了帮助开发者在谷歌拼音输入法的基本输入功能基础上,开发和定义更丰富的扩展输入功能,谷歌拼音输入法提供了以Lua脚本编程语言为基础的输入法扩展API。利用输入法扩展API,开发者可以编写自定义的输入功能,并将脚本分享给谷歌拼音输入法的用户安装、使用。

一段简单的Lua脚本程序就可以构成一个最基本的输入法扩展模块。下面是“Hello,World!”程序示例:

helloworld.lua

function HelloWorld()
  return "Hello,World!"
end

ime.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(也可以从Windows资源管理器,右键单击helloworld.lua文件,选择“安装到谷歌拼音输入法”)。安装后,打开记事本程序,切换到谷歌拼音输入法,键入"ihw",谷歌拼音输入法的候选项窗口中将出现唯一候选项"Hello,World!"。

除了显式用"ihw"这样的命令来激活扩展函数以外,扩展函数还可以由用户在使用拼音输入法时输入的特定内容或特定候选词激活。例如,在上述helloworld.lua最后添加一行:

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

这一行的作用是将函数"HelloWorld"注册为谷歌拼音输入法的一个整合扩展。第一个参数是扩展对应的入口函数"HelloWorld",第二个参数是简短说明文字,第三个参数给出希望将扩展关联到哪个或哪几个用户输入串(这里是字符串"hello"),第四个参数给出希望将扩展关联到哪个或哪几个特定的候选词(这里是空表,表示不关联)。

打开谷歌拼音输入法选项设置窗口,在"扩展"页面中,使用"移除扩展包"按钮将刚才安装的helloworld.lua删除,然后重新安装更新后的helloworld.lua。打开记事本程序,切换到谷歌拼音输入法,键入"hello",谷歌拼音输入法的候选项窗口中,除了出现通常的中文英文候选词提示外,还将出现由整合扩展函数返回的候选项"Hello,World!"。

事实上,谷歌拼音输入法提供的输入法扩展API可以用来开发各种不同的输入体验,例如,根据用户输入的参数返回相应的信息内容,查表输入特定的文字信息,完成自定义的甚至包含随机变量的计算并以不同形式返回结果,将用户刚刚输入的文字内容转换为另一种表现形式,等等。谷歌拼音输入法提供的i模式的缺省功能,包括时间和日期格式转换,查星座,掷骰子,打印字符等,都是一些最简单的示例。

本指南的后续内容详细介绍了开发输入法扩展所需要的各种知识。我们也鼓励开发者直接参考已有的示例程序。例如,i扩展模式的缺省功能是由安装在以下位置的Lua脚本程序实现的:

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

三种不同的扩展方式[回页首]

谷歌拼音输入法扩展API提供了三种扩展拼音输入法的方式:命令扩展整合扩展转换器扩展

下表对不同的扩展方式进行简单的对比:

扩展方式 命令扩展 整合扩展 转换器扩展
注册方式 ime.register_command (...) ime.register_trigger (...) ime.register_converter (...)
适用范围 用户明确希望在特定场景下使用特定输入功能,且候选项较多,或较复杂的情况 在不妨碍用户正常输入的情况下,根据当前输入或候选内容,插入少数相关候选项的情况 为所有候选项增加装饰、特效,或者对所有候选项按规则进行变换的情形
应用实例 根据输入的生日查询星座;列举并输入特定的字符画 用户输入中文“时间”时,在候选项列表里插入当前时间;用户输入中文“哈哈”时,在候选项列表插入相应的表情符号 为候选项或候选项的每个字增加星号修饰;直接在候选项的每个字后面输出该字对应的Unicode编码;将简体汉字变为繁体汉字
激活方式 用户输入i加2字符长的命令,激活相应的命令扩展 用户输入的拼音字符串或输入法产生的某个候选项与整合扩展关联的特定字符串(可包含通配符)匹配时,激活相应的整合扩展 用户从输入法的用户界面(如功能菜单)开启特定的转换器,激活相应的转换器扩展

注册命令扩展[回页首]

在Lua脚本中,向谷歌拼音输入法注册一个命令扩展的基本语法是:

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

ime是提供给Lua脚本使用的,与输入法内核交互的专用模块。register_command是向谷歌拼音输入法注册新的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脚本中,向谷歌拼音输入法注册一个整合扩展的基本语法是:

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

ime是提供给Lua脚本使用的,与输入法内核交互的专用模块。register_trigger是向谷歌拼音输入法注册新的整合扩展所使用的函数。函数的各参数含义如下:

关于通配符匹配:input_trigger_strings和candidate_trigger_strings中的字符串可以在开头或结尾包含通配符*,表示前缀匹配或后缀匹配。例如:

使用ime.register_trigger注册整合扩展时,请注意以下几点:

整合扩展的入口函数一般应接收一个参数。在激活整合扩展函数时,输入法会把激活整合扩展函数的字符串(或者是用户输入的内容,或者是某个特定的候选项)作为唯一的参数传递给入口函数。这样,注册了多个匹配字符串的整合扩展函数就可以在被调用时通过参数知道究竟是哪个字符查激活了自己。当然,在不需要时,入口函数也可以简单地忽略这个参数。

注册转换器扩展[回页首]

在Lua脚本中,向谷歌拼音输入法注册一个转换器扩展的基本语法是:

ime.register_converter(lua_function_name, description)

ime是提供给Lua脚本使用的,与输入法内核交互的专用模块。register_converter是向谷歌拼音输入法注册新的转换器扩展所使用的函数。函数的各参数含义如下:

用户开启转换器时,输入法会依次将每个候选项作为参数调用转换器对应的Lua入口函数。也就是说,对于每个候选项,Lua入口函数都被调用一次。

转换器扩展对应的Lua入口函数应当返回且只返回一个结果,即返回对原候选项进行变换后的新候选项。如果不希望变换某个候选项,可以将输入参数的值直接返回。如果没有返回任何结果,或返回的结果数目多于一个,则输入法认为该扩展函数没有对候选项做任何变换。

安装了转换器扩展后,用户可以从输入法的用户界面启动或关闭特定的转换器。如下图,从功能菜单开启或关闭特定的转换器:

返回候选项[回页首]

一般的,扩展对应的入口函数可以返回一个或多个候选字符串。命令扩展会显示所有返回的候选项,整合扩展目前只会将第一个候选项结果插入到输入法的候选项列表中,而转换器扩展则只接受返回一个候选字符串的入口函数。

返回的参数类型可以是Lua字符串类型,也可以是Lua数字类型,还可以是Lua布尔类型。但这些返回值返回输入法内核后,都会被转换成字符串显示给最终用户,以便用户选择输入。

要返回唯一的候选字符串,只要直接使用return语句返回字符串、数字或布尔值即可,例如:

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

要返回两个或更多结果,只要返回一个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 "一二三"
  end
end

返回的提示信息表必须符合上述格式,即,表中的每个元素都是一个子表,每个子表内有两个元素:键名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"
  end
end

更详细的信息请参见API参考一节中有关ime模块的部分。

错误处理[回页首]

Lua入口函数接收无法处理的参数,或者发生其他内部错误时,可以简单地不返回任何参数,或者使用Lua语言内置的error()函数向输入法报告错误信息,例如:

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()函数报告的错误信息不会在输入法用户界面中显示,但可以使用控制台工具测试脚本程序并查看错误信息。参见下面的开发与调试一节。

开发和调试[回页首]

输入法扩展脚本程序可以使用任何源代码/文本编辑器创建。在将输入法扩展包安装到谷歌拼音输入法之前,可以使用控制台工具测试扩展程序,以确保程序功能正确。请从以下链接下载用于开发调试谷歌拼音输入法扩展脚本的控制台工具:

下载控制台工具 (GooglePinyinApiConsole.exe)

在命令行运行控制台工具GooglePinyinApiConsole.exe时,需要给出的命令行参数是一个或多个待测试的脚本文件路径,控制台工具会加载所有指定的输入法扩展脚本,并启动一个交互式界面,供开发者测试执行扩展模式。例如:

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

在控制台工具的交互式界面中,键入"help",可以查看帮助信息:

i - 列出所有已注册的命令扩展
i [COMMAND] - 无参数执行某命令扩展
i [COMMAND] [ARGUMENT] - 有参数执行某命令扩展
g [TRIGGER_STRING] - 尝试利用某字符串参数激活整合扩展
c - 列出所有已注册的转换器扩展
c [FUNCTION] [STRING] - 测试转换器函数
quit - 退出控制台工具
help - 显示帮助信息

当脚本加载或执行过程中发生错误时,控制台工具会打印显示错误信息。错误信息包括发生错误的脚本文件名,错误行号,错误内容等。

控制台工具并不是真实的输入法运行环境,因此,一些和输入法特定功能相关的接口,例如,ime.get_last_commit(),在控制台运行的脚本中无法得到实时的输入法相关信息,这时,此类函数的返回值是简单的固定字符串,如“测试”。整合扩展也无法像在输入法中那样,将结果插入在输入法的候选项列表中。

下图显示了使用控制台工具测试缺省输入法扩展包中各扩展功能的情形:

关于Lua语言[回页首]

目前,谷歌拼音输入法扩展API只提供了Lua一种开发语言。Lua是一种体积小巧却功能强大的动态脚本编程语言,广泛用于网络游戏等应用的插件或扩展功能的开发。对于一个有JavaScript语言、VBScript语言或者Python语言开发经验的开发者来说,学习Lua语言并不困难。请参考以下网址获得关于Lua语言的各种信息:

Lua程序设计语言

在输入法环境中,每个用户安装的输入法扩展都是一个独立的Lua语言模块,每个模块在自己的名字空间中运行。也就是说,不同模块间的同名符号不会冲突,但不同模块间也无法相互进行功能调用。用户安装的输入法扩展只能调用API参考一节描述的Lua内置功能函数和ime模块提供的输入法相关函数。

API参考[回页首]

使用Lua语言编写的输入法扩展程序保存在磁盘上时,推荐使用UTF-8编码的文本文件。文本文件可以包含也可以不包含BOM文件头。没有BOM文件头时,IME缺省认为按UTF-8编码加载。

使用Lua语言编写的输入法扩展程序可以使用以下内置函数。除了ime模块提供的输入法相关函数外,这些函数是标准Lua运行环境的一个子集。因此,在将已有的Lua程序移植到输入法扩展程序之前,请确认程序使用的函数在下表所涵盖的范围内。

以下凡属于Lua标准运行环境的函数,均只给出简要的功能说明。详细用法请参见Lua语言标准函数库的说明。

基本功能函数

字符串处理函数

日期和时间函数

数学函数

表处理函数

ime模块提供的输入法相关函数

注册输入法模块相关函数

输入法信息相关函数

实用工具函数

©2013 Google - 隐私权政策 - 服务条款 - 帮助中心 - 支持论坛 - 版权信息 - API 开发指南