从 WebExtensions API JSONSchema 生成 WebIDL 定义

在 toolkit/components/extensions/webidl-api 中，一个名为 GenerateWebIDLBindings.py 的 Python 脚本用于根据现有的 JSONSchema 数据生成 WebExtensions API 命名空间的 WebIDL 定义。

示例：如何执行 GenerateWebIDLBindings.py

例如，以下 shell 命令生成（或如果已存在则重新生成）runtime API 命名空间的 webidl 绑定

$ export SCRIPT_DIR="toolkit/components/extensions/webidl-api"
$ mach python $SCRIPT_DIR/GenerateWebIDLBindings.py -- runtime

此命令将生成一个名为 dom/webidl/ExtensionRuntime.webidl 的 .webdil 文件。

警告

此 Python 脚本使用 mozilla-central mach 命令的一部分 Python 库，因此必须使用 mach python 执行，并且必须传递给 GenerateWebIDLBindings.py 脚本的任何命令行选项都应在结束 mach python 自己的命令行选项的 -- 之后传递。

• 如果已存在同名的 webidl 文件，Python 脚本将询问确认并提供打印更改差异（或者如果内容完全相同则继续而不更改现有的 webidl 文件）的机会。

$ mach python $SCRIPT_DIR/GenerateWebIDLBindings.py -- runtime

Generating webidl definition for 'runtime' => dom/webidl/ExtensionRuntime.webidl
Found existing dom/webidl/ExtensionRuntime.webidl.

(Run again with --overwrite-existing to allow overwriting it automatically)

Overwrite dom/webidl/ExtensionRuntime.webidl? (Yes/No/Diff)
D
--- ExtensionRuntime.webidl--existing
+++ ExtensionRuntime.webidl--updated
@@ -24,6 +24,9 @@
 [Exposed=(ServiceWorker), LegacyNoInterfaceObject]
 interface ExtensionRuntime {
   // API methods.
+
+  [Throws, WebExtensionStub="Async"]
+  any myNewMethod(boolean aBoolParam, optional Function callback);

   [Throws, WebExtensionStub="Async"]
   any openOptionsPage(optional Function callback);


Overwrite dom/webidl/ExtensionRuntime.webidl? (Yes/No/Diff)

• 按照惯例，每个 WebExtensions API WebIDL 绑定都应与名为 ExtensionMyNamespace.h 和 ExtensionMyNamespace.cpp 的 C++ 文件配对，并位于 toolkit/components/extensions/webidl-api 中。

  • 如果没有找到预期名称的文件，Python 脚本将生成初始样板文件并将其存储在预期的 mozilla-central 目录中。

  • Firefox 开发人员负责根据需要填充此初始样板，并在 WebExtensions API JSONSchema 更改导致 webidl 定义更改时应用必要的更改（如果有）。

ExtensionWebIDL.conf 配置文件

待办

• 提及“webidl 生成”脚本配置文件在处理特殊情况（例如映射类型和方法存根）中的作用。

• 关于仅限桌面的 API 和仅在 Android 上部分可用的 API 命名空间的说明。

WebExtensionStub WebIDL 扩展属性

待办

• 提及 WebIDL 定义中使用的特殊 webidl 扩展属性。