清单

清单是一个 JSON 文件，它提供有关插件的信息，例如作者、描述、图标以及从哪里获取最新更新。它还会告诉 Sketch 如何运行插件以及它如何集成到“插件”菜单中。

提示：使用 JSON 架构验证您的 manifest.json。

示例清单

以下示例 manifest.json 文件用于名为“选择形状”的插件，并定义了三个命令——“全部”、“圆形”和“矩形”。这些命令可以通过 Sketch 中的“插件”>“选择形状”菜单访问。

{
  "name": "Select Shapes",
  "description": "Quickly select all or just specific shape types",
  "author": "Bob Ross",
  "homepage": "https://github.com/example/select-shapes",
  "version": "1.0",
  "identifier": "com.example.sketch.plugin.select-shapes",
  "appcast": "https://example.com/select-shapes-plugin-appcast.xml",
  "compatibleVersion": "52.1",
  "commands": [
    {
      "name": "All",
      "identifier": "all",
      "shortcut": "ctrl shift a",
      "script": "shared.js",
      "handler": "selectAll"
    },
    {
      "name": "Circles",
      "identifier": "circles",
      "script": "circles.js"
    },
    {
      "name": "Rectangles",
      "identifier": "rectangles",
      "script": "rectangles.js"
    }
  ],
  "menu": {
    "items": ["all", "circles", "rectangles"]
  }
}

成员

`appcast`

插件“更新 JSON 文件”的 URL，其中包含有关最新插件版本的信息，包括下载最新更新的 URL。Sketch 会自动检查此文件是否有更新，并在有更新可用时通知用户。

`author`

提供插件作者的姓名。

`authorEmail`

指定如何通过电子邮件联系插件作者。这是可选的。

`bundleVersion`

指定插件包的元数据结构和文件布局的版本。这是可选的，默认为 1。目前不支持其他版本。

`compatibleVersion`

定义运行插件所需的 Sketch 的最低版本。此字符串必须使用语义化版本控制。请注意，Sketch 不会使用它来确定兼容性，你应该仅供自己参考使用。

"compatibleVersion": "52.1"

`commands`

一个对象数组，定义了插件提供的所有命令。

例如，以下示例命令定义说明，当从 Sketch 中调用 Select all 命令时，将调用 script.js 中的 selectAll JS 函数。

"commands": [
  {
    "name": "Select all",
    "identifier": "select-all",
    "shortcut": "ctrl shift a",
    "script": "select-all.js",
    "handler": "selectAll"
  }
]

// select-all.js
function selectAll() {
  // ... plugin code to select all
}

命令字段	描述
`identifier`	定义插件包内命令的唯一标识符。
`name`	提供命令的名称，该名称用于“插件”菜单中。
`shortcut`	为命令提供默认键盘快捷键，例如 `ctrl shift t`。有关可能值的参考，请参见下表。
`script`	指定插件包的“Sketch”文件夹中实现命令的脚本的相对路径。
`handler`	指定要使用命令调用的函数的名称。该函数应在脚本的顶层声明，并接受一个包含当前文档和选择等信息（例如 `context`）的参数。如果省略此字段，插件将默认使用名为 `onRun` 的处理程序。或者，如果您使用的是 `skpm` 工具，则可以 `export` 该函数而不是声明它，或者省略此字段并使用 `export default` 声明处理程序
`handlers`	如果需要更细粒度的控制，请使用 `handlers` 字段而不是 `handler`，有关深入文档，请参见下文

快捷键值

可以使用以下任何键的组合以及任何常规字符来设置命令快捷键。

请注意，快捷键必须至少包含一个修饰键，“Command”、“Option”、“Control”或“Shift”。与预定义的 Sketch 快捷键（例如 cmd s）匹配的值将被忽略。

确保在不同的国际键盘布局下测试您的快捷键。某些字符可能要求用户按修饰键。例如，快捷键 shift / 在西班牙语键盘布局下不起作用。而在美国键盘上，正斜杠 / 有一个专用的键，而在西班牙语键盘上，它需要按 shift 7。

键	值
Command (⌘)	`cmd`
Option (⌥)	`alt`
Control (⌃)	`ctrl`
Shift (⇧)	`shift`
Backspace (⌫)	`⌫` 或 `\u0008`
Tab (⇥)	`⇥` 或 `\u0009`
Return (↩)	`↩` 或 `\u000d` 或 `\u000a`
Escape (⎋)	`⎋` 或 `\u001b`
Left (←)	`←` 或 `\u001c`
Right (→)	`→` 或 `\u001d`
Up (↑)	`↑` 或 `\u001e`
Down (↓)	`↓` 或 `\u001f`
Space	`\u0020`
Delete (⌦)	`⌦` 或 `\u007f`
Home (↖)	`↖` 或 `\u2196`
End (↘)	`↘` 或 `\u2198`
Page Up (⇞)	`⇞` 或 `\u21de`
Page Down (⇟)	`⇟` 或 `\u21df`

`handlers`

一个对象，用于完全指定命令的“setup”>“run”>“tearDown”生命周期，以及使用操作。当指定时，handler 字段将被忽略。

handlers 对象有五个字段

run 当执行命令时应调用的函数（这在概念上与定义 handler 相同）
setUp 在执行命令之前要调用的函数（不要与“启动”操作混淆）
tearDown 在命令完成执行后要调用的函数（不要与“关闭”操作混淆）
onDocumentChanged 请参见文档更改页面
actions 请参见操作页面，获取深入指南

例如，以下 commands 定义将 SelectionChanged.finish 操作映射到 onSelectionChanged JS 函数，

{
  "commands": [
    {
      "name": "Selection changed",
      "identifier": "selection-changed",
      "script": "./selection-changed.js",
      "handlers": {
        "actions": {
          "SelectionChanged.finish": "onSelectionChanged"
        }
      }
    }
  ]
}

selection-changed.js 中的函数将编写为：

// selection-changed.js
function onSelection(context) {
  var doc = context.document
  var selection = context.selection
}

在 handlers 对象中引用的函数的定义方式与 handler 函数相同，即在普通插件的脚本顶层声明，或在 skpm 中使用 ES6 模块 export 语法。

`description`

提供对插件功能的总体描述。

`disableCocoaScriptPreprocessor`

CocoaScript 默认支持 @import 和方括号语法，即 [obj hello: world]。如果通过将 disableCocoaScriptPreprocessor 设置为 true 来禁用，则不再支持。

注意：要使用 ES6 语法和构建系统（如 skpm），必须将其设置为 true。

此值是可选的，默认为 false，在使用 skpm 时设置为 true。

`homepage`

指定用户可以在其中找到更多信息或提供插件反馈的网站地址。这是可选的。

`icon`

插件图标在 Sketch 中使用的路径，例如在偏好设置中。图标必须以 128x128px 的分辨率提供为 PNG 文件，并直接位于插件包的“Contents/Resources”中，或位于其子文件夹中。

`identifier`

为插件定义唯一的标识符。此值是一个使用反向域名语法的字符串。

"identifier": "com.example.sketch.plugin.select-shapes"

`maxCompatibleVersion`

定义插件支持的 Sketch 的最大版本。此字符串是可选的，如果提供，则必须使用语义化版本控制。请注意，Sketch 不会使用它来确定兼容性，你应该仅供自己参考使用。

"maxCompatibleVersion": "54"

`name`

在向用户显示时，为插件提供一个易于理解的名称，例如在插件菜单中或 Sketch 首选项中安装的插件列表。

`范围`

指定插件是否可以在没有打开的 Sketch 文档的情况下运行。

document: 默认值，在没有打开文档时禁用插件的菜单项
application: 启用插件菜单并允许在没有打开文档的情况下运行插件

"scope": "application"

`供应数据`

指定插件是否为数据提供者。如果设置为true，则在首选项窗格中显示插件的视觉指示器，其中显示了所有已安装插件的列表。

`版本`

使用语义版本控制的插件版本。这是将与更新 JSON 文件中设置的versionID进行比较的版本。如果此处的版本低于更新 JSON 文件中的版本，则表示有可用的更新。

"version": "1.0.1"

`菜单`

提供有关插件菜单布局的信息。Sketch 在加载插件时初始化菜单。

{
  "menu": {
    "title": "Select Shapes",
    "items": [
      "selectAll",
      "-",
      {
        "title": "Select…",
        "items": ["circles", "rectangles"]
      }
    ]
  }
}

成员	描述
`isRoot`	指定菜单项是在 Sketch 的插件菜单中直接创建的。默认情况下，Sketch 为插件创建一个子菜单。此值不支持子菜单。
`项目`	菜单项数组，支持的值是命令标识符、`"-"` 分隔符和定义子菜单的对象
`标题`	提供用于菜单项的可读标题。如果菜单项也设置了`isRoot`为`true`，则会忽略该值。

清单