本文示例说明了如何在Chrome浏览器中增加JavaScript API。为了简化,先假设是在已有的namespace中增加一个新的API,文章的最后将指出如果增加一下全新的namespace所需注意的事项。
在继续之前,请确保你的Chrome浏览器中已安装了一些扩展程序。可以在地址栏中输入chrome://extensions查看已安装的扩展程序。下图示例说明了我的浏览器中已安装了Google Mail Checker扩展程序,我们将使用它来测试新增的API(测试可以使用任何扩展程序,而不需指定这所示例的Google Mail checker)。
从上图也同时示例了如何打开Chrome网上商店,我们需要进入该页面查看已开发好的API。进入页面后按F12打开开发者工具,并将开发者工具切换到控制台。
在开发者工具的控制台中,输入“chrome.management.un”其将显示management namespace所支持的API。
下面我们要做的,就是在management中增加showButton API,用于显示或隐藏扩展栏上(某)扩展程序的Icon。增加showButton API大体上分成两大部骤。步骤一为变更C++代码,步骤二为变更management.json接口描述文件。下面逐步讲解基于Chrome R28源码的具体变更内容。
首先,在src\chrome\browser\extensions\api\management\management_api.h中增加一个新类的声明。当showButton在Javascript中被调用时,该类将负责进行后续处理,其RunImpl方法将会被调用。
class ManagementShowButtonFunction : public ManagementFunction { public: DECLARE_EXTENSION_FUNCTION("management.showButton", MANAGEMENT_UNINSTALL) private: virtual bool RunImpl() OVERRIDE; };
接着,在src\chrome\browser\extensions\api\management\management_api.cc中增加新类的实现。RunImpl方法根据JavaScript所传入的两个参数调用SetBrowserActionVisibility函数,实现对扩展程序Icon的显示和隐藏。第一个参数为扩展程序的ID,第二个参数是一个布尔变量,用于指示是显示(true)抑或隐藏(false)扩展程序的Icon。
bool ManagementShowButtonFunction::RunImpl() { std::string extension_id; EXTENSION_FUNCTION_VALIDATE(args_->GetString(0, &extension_id)); bool enable; EXTENSION_FUNCTION_VALIDATE(args_->GetBoolean(1, &enable)); const Extension* extension = service()->GetExtensionById(extension_id, true); if (!extension) { error_ = ErrorUtils::FormatErrorMessage( keys::kNoExtensionError, extension_id); return false; } service()->extension_prefs()->SetBrowserActionVisibility(extension, enable); return true; }
最后,我们在src\chrome\common\api\management.json中增加showButton的描述。请注意,在该文件中存在functoins和events两大部分,一定要将新增内容放入functions部分。为了防止变更JSON文件时出错,可以使用Notepad++,并在其上安装JSLint和JSMin两个插件。在编辑完JSON文件后先调用Plugins->JSMin->JSFormat(Notepad++中的菜单命令),然后是Plugins->JSLint->JSLint Current File检查是否存在错误。
{ "name" : "showButton", "description" : "Show/Hide extension icon on extension bar.", "parameters" : [ { "name" : "id", "type" : "string", "description" : "This should be the id from an item of $ref:ExtensionInfo." }, { "name" : "enabled", "type" : "boolean", "description" : "Whether this item should be enabled or disabled." } ] }
有了以上的变更后,在编译Chrome项目之前,需手动重新编译api项目,因为Chrome项目并不依赖于api项目。重新编译将使得在自动生成的GeneratedFunctionRegistry:: RegisterAll函数内增加对ManagementShowButtonFunction的注册。
程序编译完成后,我们可以在开发者工具的控制台上测试showButton函数。下图示例说明了通过调用该函数隐藏和显示Google Mail Checker扩展程序的Icon。
上面示例了如何在已存在的management namespace中增加一个API。在Chrome中,JavaScript API的使用存在权限的概念。如果新增API的同时也需新增namespace的话,需要注意在APIPermissionInfo::RegisterAllPermissions方法中注册新增namespace的权限,否则会出现页面无法访问新增API的问题。