文档变更

使用 onDocumentChange 处理程序监听 Sketch 文档中的任意变更。它提供了一种机制来监听文档中的三种基本变更事件 - 变更、删除和添加。

此 API 从 Sketch 59 开始可用，旨在作为处理特定文档变更的 操作 的可扩展且更灵活的替代方案。

🚧 我们正在提前发布此功能以收集社区的反馈，因此 API 在将来可能会更改。请告诉我们您的想法，提交问题 以获取评论、建议和错误报告，或发送电子邮件至 [email protected]。

🚀 查看 document-change-sketchplugin 以获取示例实现，或继续阅读以快速入门。

变更类型

基本文档变更类型是

• 属性变更，例如图层的 x/y 位置发生变更
• 对象添加，例如将新图层添加到画布
• 对象删除，例如删除图层

请注意，对象在图层层次结构中移动被视为从先前路径删除并在新路径重新添加 - 此类变更的 isMove 标志设置为 true。有关更多信息，请参见下面的代码示例。

清单处理程序

通过在 插件清单 中定义的新 onDocumentChanged 处理程序订阅变更。

{
  "compatibleVersion": 3,
  "bundleVersion": 1,
  "identifier": "com.sketch.plugins.document-change-example",
  "commands": [
    {
      "script": "command.js",
      "handlers": {
        "onDocumentChanged": "onDocumentChanged"
      }
    }
  ],
  "version": "1.0.0",
  "name": "Document Change",
  "description": "Sample plugin showcasing how to handle document changes such as object addition, deletions and modifications.",
  "author": "Sketch",
  "disableCocoaScriptPreprocessor": true
}

处理程序定义

与现有处理程序类似，需要定义一个 JavaScript 函数来处理传入的文档变更事件。Sketch 在文档发生变更时会重复调用该函数。

快速连续发生的变更可能会被批处理，因此您的处理程序将收到包含一组变更的参数。

function onDocumentChanged(context) {
  var changes = context.actionContext
  for (var i = 0; i < changes.length; i++) {
    var change = changes[i]
    var path = change.fullPath() // Path to the affected object or property
    var type = change.type() // Change type, see example below for values
    var obj = change.object() // Reference to the mutable object
    var isMove = change.isMove() // Whether addition/removal is associated with a move
  }
}

以下样板代码说明了处理每种变更类型（包括移动）的一种方法。

function onDocumentChanged(context) {
  var changes = context.actionContext

  for (var i = 0; i < changes.length; i++) {
    var change = changes[i]
    var type = change.type()
    var isMove = change.isMove()
    switch (type) {
      case 1:
        // Handle property change
        break
      case 2:
        if (!isMove) {
          // Handle deletion
        }
        break
      case 3:
        if (isMove) {
          // Handle move
        } else {
          // Handle addition
        }
        break
    }
  }
}