插件捆绑目录

插件是一个或多个脚本的集合。每个脚本定义一个或多个以某种方式扩展Sketch的命令。

在磁盘上，插件是具有.sketchplugin文件扩展名的文件夹，包含文件和子文件夹。

严格来说，插件实际上是一个OS X软件包，被安排为OS X软件包。

包是Finder向用户呈现的任何目录，就好像它是单个文件一样（您可以使用Finder中的“ 显示包内容”命令查看内部）。

一个包是一个具有标准化层次结构的目录，该目录包含可执行代码和该代码使用的资源。

Sketch插件不允许本机编译代码，但我们确实使用标准包布局（例如，资源位于包中的资源/文件夹中），特定于插件的文件位于Sketch /目录中。

插件捆绑文件夹结构

Bundles包含一个manifest.json文件，一个或多个.cocoascript文件（包含用CocoaScript或JavaScript编写的脚本），它们实现Plugins菜单中显示的命令以及任意数量的共享库脚本和资源文件。

这是一个例子：

mrwalker.sketchplugin
  Contents/
    Sketch/
      manifest.json
      shared.js
      Select Circles.cocoascript
      Select Rectangles.cocoascript
    Resources/
      Screenshot.png
      Icon.png

最关键的文件是manifest.json文件，它告诉Sketch其他所有内容。

表现

清单是一个JSON文件，其中包含有关插件，其命令和资源的元数据。

它描述了诸如全名，描述和作者姓名等内容。它列出了插件定义的任何命令的名称，并告诉Sketch调用相应的菜单项以及将它们放入哪个菜单。

这是一个例子：

{
  "name": "Select Shapes",
  "description": "Plugins to select and deselect shapes",
  "author": "Joe Bloggs",
  "homepage": "https://github.com/example/sketchplugins",
  "version": "1.0",
  "identifier": "com.example.sketch.shape-plugins",
  "appcast": "https://excellent.sketchplugin.com/excellent-plugin-appcast.xml",
  "compatibleVersion": "3",
  "bundleVersion": 1,
  "commands": [
    {
      "name": "All",
      "identifier": "all",
      "shortcut": "ctrl shift a",
      "script": "shared.js",
      "handler": "selectAll"
    },
    {
      "name": "Circles",
      "identifier": "circles",
      "script": "Select Circles.cocoascript"
    },
    {
      "name": "Rectangles",
      "identifier": "rectangles",
      "script": "Select Rectangles.cocoascript"
    }
  ],
  "menu": {
    "items": ["all", "circles", "rectangles"]
  }
}

这个插件被称为“选择形状”。它定义了三个命令“全部”，“圆”和“矩形”，它们将被放置在“选择形状”菜单中。

这个插件可以通过Sketch进行更新。Sketch将在指定的位置下载文件appcast并使用它来确定是否有更新。

将此文件进一步解压缩，以下是支持的密钥及其用途：

name

这个插件的名称。默认情况下，它将用作插件菜单命令出现的子菜单的名称。

description

描述此插件的命令（或命令）所做的字符串。

author

指定插件作者的字符串。

authorEmail

指定如何通过电子邮件与插件作者联系的可选字符串。

homagepa

可选字符串，指定用户在线资源以查找更多信息或为插件提供反馈。

version

例如，一个字符串，指定插件的语义版本。1.0``1.1.1

identifier

一个字符串，指定插件的唯一标识符。

例如，强烈建议使用反向域语法com.example.sketch.shape-plugins。

Sketch在内部使用该字符串来跟踪插件，为其存储设置等。

appcast

指定appcast文件的URL的字符串。appcast文件包含有关插件更新的信息，例如可用更新的版本以及可从中下载更新的位置。Sketch下载此文件以确定是否有可用的插件更新。

compatibleVersion 和 maxCompatibleVersion

一个字符串，指定版本素描在其中作者已测试了插件，例如3，3.1，3.2.2。

目前（Sketch3.4）这是一个可选键，但我们可以在插件页面的某个时刻将它用作过滤选项。

它在内部使用BCCompareVersions函数来分割字符串.，然后比较每个组件的整数值。

bundleVersion

元数据包的布局版本。如果排除，则假定值为1。

这只是我们面向未来的机制。如果将来我们看到bundleVersion> 1的插件，我们就会知道我们可以以不同的方式处理元数据中的其他值。

现在可以忽略它。

disableCocoaScriptPreprocessor

这是一个高级设置，默认为false。设置true为时，它将禁用CocoaScript自己的预处理器。这样，您就可以使用诸如browserify或ES6模块语法的构建系统来开发您的插件。

将此选项设置为true执行以下操作：

• 禁用@import支持，您必须手动处理您的导入
• 禁用括号语法（即[obj msg:]：），则只能使用点语法

commands

插件定义的一组命令。

数组中的每个项目都是一个字典，用于指定命令的名称，快捷方式和其他属性。有关更多详细信息，请参阅插件命令。

menu

描述此插件中命令的菜单布局的字典。

请参阅插件菜单以获取有关该词典内容的更多详细信息，以及如何构建每个插件的菜单。

插件命令

插件定义一个或多个用户执行的命令。

清单中的命令数组描述了这些。数组中的每个条目都是一个字典，具有以下属性：

name

命令的显示名称。该值在插件菜单中使用。

identifier

一个字符串，用于指定插件捆绑中命令的唯一标识符。这用于一致地将命令映射到操作，而不考虑命令名称的变化。

shortcut

一个可选的字符串，指定了该命令的默认快捷键，例如：ctrl t，cmd t，ctrl shift t。

script

Sketch实现此命令的脚本的插件包文件夹内的相对路径。

handler

用脚本调用此命令的函数的名称。该函数必须采用单个context参数，这是一个带有当前文档和选择项等键的字典。如果未指定，则该命令预期为onRun：

var onRun = function (context) {
  var doc = context.document;
  var selection = context.selection;
  …
}

插件菜单

当它加载插件时，Sketch为它创建一个菜单，并使用清单文件中“菜单”字典中的信息填充该菜单。

该字典可以包含以下键。

title

指定用于子菜单的标题的字符串。

items

这是一个列出要包含在菜单中的项目的数组。

它可以包含两种类型的项目：

• 一个给出命令标识符的字符串
• 描述子菜单的字典（包含“标题”和“项目”）

isRoot

默认情况下，此字典中列出的菜单项将显示在菜单中，其名称由标题键指定。

如果指定了isRoot键，并且值为true，则这些项目将插入到插件菜单的根级别，而不是插入到子文件夹中。在这种情况下，标题密钥将被忽略。

这个键在子菜单中被忽略。

菜单示例

这是一个例子。它在名为“My Plugin Menu”的菜单中定义了三个命令。菜单的前两项对应于插件的两个命令，但第三项是名为“My Plugin Submenu”的子菜单。这个子菜单中有一个项目（插件命令的第三个项目）：

{
  "menu": {
    "title": "My Plugin Menu",
    "items": [
      "command1-identifier",
      "command2-identifier",
      {
        "title": "My Plugin Submenu",
        "items": ["command3-identifier"]
      }
    ]
  }
}

处理程序

插件命令由处理程序实现。

这些只是生活在.cocoascriptPlugin包中的一个文件中的JavaScript函数，它包含一个包含某个上下文的参数。

这里有一个简单的例子：

var doMyCommand = function(context) {
  context.document.currentPage().deselectAllLayers()
}

在清单文件中，您可以指定一个描述插件定义的每个命令的字典。

在这本词典中，脚本和处理程序键告诉Sketch要查看哪个脚本文件，以及要运行哪个处理程序。

您可以自由地将每个命令实现放入其自己的脚本文件中，或将它们全部放入单个文件中。

您必须为每个命令指定脚本密钥。

如果将每个命令放入其自己的脚本文件中，则可以省略处理程序密钥。在这种情况下，Sketch将默认调用onRun处理程序。

如果将多个命令处理程序放入同一个脚本文件中，则需要为每个脚本文件使用处理程序密钥，因为它们不能全部使用onRun处理程序！

原文：https://developer.sketchapp.com/guides/plugin-bundles/