API 模式¶

WebExtension API 通过 Javascript 向扩展程序公开的任何内容都由 API 的模式描述。API 模式的格式使用了一些与 JSON Schema 相同的语法。JSON Schema 提供了一种指定 JSON 文档约束的方法，WebExtensions 使用相同的方法来指定约束，例如传递给 API 函数的参数。但是，描述函数、命名空间等的语法都是特定于此处的。本节描述该语法。

单个 API 模式包含一个或多个命名空间中项目的结构化描述，使用如下结构

[
  {
    "namespace": "namespace1",
    // declarations for namespace 1...
  },
  {
    "namespace": "namespace2",
    // declarations for namespace 2...
  },
  // other namespaces...
]

大多数命名空间对应于扩展程序 Javascript 代码在全局 browser 下可用的对象。例如，命名空间 example 中的条目可供扩展程序 Javascript 代码作为 browser.example 上的属性访问。命名空间 "manifest" 的处理方式特殊，它描述了 WebExtension 清单的结构（即 manifest.json 文件）。清单模式将在下面详细解释。

命名空间内的声明如下所示

{
  "namespace": "namespace1",
  "types": [
    { /* type definition */ },
    ...
  ],
  "properties": {
    "NAME": { /* property definition */ },
    ...
  },
  "functions": [
    { /* function definition */ },
    ...
  ],
  "events": [
    { /* event definition */ },
    ...
  ]
}

可以在命名空间内定义的四种类型的对象是

类型：类型是一个可重用的模式片段。类型的常见用途是在一个地方定义具有特定一组类型化字段的对象，该对象在 API 的多个地方使用。
属性：属性是通过 Javascript 向扩展程序提供的固定 Javascript 值。请注意，在模式中定义属性的格式与类型、函数和事件的格式不同。下一小节将详细介绍如何创建属性。
函数和事件：这些条目分别创建函数和事件，扩展程序可以通过 Javascript 使用它们。有关如何实现它们的信息在本节后面提供。

实现固定的 Javascript 属性¶

静态属性完全通过模式向扩展程序提供 Javascript，使用如下所示的片段

[
  "namespace": "myapi",
  "properties": {
    "SOME_PROPERTY": {
     "value": 24,
     "description": "Description of my property here."
    }
  }
]

如果为特定扩展程序上下文加载了其模式中包含此片段的 WebExtension API，则该扩展程序将能够访问 browser.myapi.SOME_PROPERTY 并读取固定值 24。 value 的内容可以是任何 JSON 可序列化对象。

模式项¶

模式中各个项目的定义大多具有共同的格式

{
  "type": "SOME TYPE",
  /* type-specific parameters... */
}

特定于类型的参数将在后续部分中描述，但有一些可选属性可以出现在 API 模式中许多不同类型的项目中

description：此字符串值属性用作阅读或编辑模式的任何人的文档。
permissions：此属性是字符串数组。如果存在，则此属性出现的项目仅提供给具有数组中列出的所有权限的扩展程序。
unsupported：此属性必须是布尔值。如果为真，则其出现的项目将被忽略。通过使用此属性，模式可以定义特定 API 的预期工作方式，然后才能实现它。
deprecated：此属性必须是布尔值。如果为真，则其出现的项目的任何用法都会导致警告记录到浏览器控制台，以指示扩展程序作者他们正在使用已弃用或未完全支持的功能。

描述受约束的值¶

在许多地方，API 模式指定了某些 JSON 值（例如，清单属性 name 必须是字符串）或 Javascript 值（例如，传递给 browser.tabs.get() 的第一个参数必须是非负整数）的类型和可能内容的约束。这些项目使用 JSON Schema 定义。具体来说，这些项目是通过为 type 属性使用以下值之一来指定的：boolean、integer、number、string、array、object 或 any。有关如何在模式中定义这些项目的信息，请参阅 JSON Schema 网站上的文档和示例。