规则和报告项目

我们将在 2023 年晚些时候停用助手功能 - 但您仍然可以在旧版本的 Sketch 或使用命令行界面使用它。 了解更多

以易于理解的方式命名您的规则，并通过选择最合适的术语来充分利用助手与 Sketch 用户界面的深度集成。

以下是一些关于如何命名规则以及如何使用您的规则和报告的文档中报告的问题来提供有用上下文的最佳实践。 这有助于使用 Sketch 的设计师和扩展您的助手的其他创建者。

规则名称

验证事物的规则应遵循命名约定 {thing}-{what-is-checked}。 查看 Sketch Core Assistant 规则 以获取示例，包括

名称 描述
groups-max-layers 组中的图层数量不应超过设定值。
groups-no-empty 组不应为空。
groups-no-similar 类似的组应为符号。

规则标题

的 title 属性 RuleDefinition 类型，显示在 Sketch 结果表的标题中。

Assistant rule titles

  • 描述规则强制执行的预期，例如页面名称应以表情符号开头。
  • 尽可能保持简短。
  • 如果可能，请包含实际的选项值，以便完全传达规则的期望，例如组中的图层数量不应超过 {maxLayers} 个。 有两种方法可以在规则标题中包含配置
    • 通过将 title 设置为函数将选项值插入字符串中，有关更多信息，请参阅 RuleDefinition。
    • 或者在配置规则时提供自定义 ruleTitle，请参阅 命名约定助手 以获取示例。

规则描述

的 description 属性 RuleDefinition 类型，显示为规则标题上的工具提示。

Assistant rule descriptions

  • 描述规则存在的原因以及它试图解决什么问题。

报告项目

报告消息是传递给 utils.report 函数的第一个参数，显示为单个报告项目的工具提示。

Assistant report messages

  • 描述文档的某个方面如何偏离规则标题中提出的预期。
  • 像规则标题一样，考虑从文档和助手配置中插入值以提供丰富的上下文信息。
  • 尽可能将一个或多个相关的 Sketch 文档对象与消息相关联，方法是将它们也传递给 utils.report。
    • 通过单击报告项目一次，可以选择相关的 Sketch 文档对象。
    • 仅当通过自动多选可以更快地解决问题时，才报告多个文档对象（请注意，来自不同页面的多个报告的文档对象只会选择当前页面上的对象）。

助手主页

当 发布 您的助手时，我们建议您在您的 package.json 中设置 homepage 值。

当用户从 Sketch 中单击以了解有关助手或单个规则的更多信息时，Sketch 会将用户引导到主页，因此它是扩展您的理由以及详细说明规则选项的好地方。

从规则单击时，Sketch 会将规则 name 附加到主页 URL 的片段，允许用户深度链接到页面上存在的特定于规则的文档。

具有名为 @sketch-hq/sketch-core-assistant/groups-max-layers 的规则和名为 https://www.example.com/ 的主页 URL 的示例单击链接 URL

https://www.example.com/#@sketch-hq/sketch-core-assistant/groups-max-layers

抛出 JavaScript 错误

从规则函数手动抛出的错误的内容也是向用户公开的内容的一部分，因为错误详细信息可以复制到粘贴板。

Assistant rule errors

当您的规则遇到一些条件导致它无法继续执行时，您可能需要考虑手动抛出规则错误。 例如，当选项丢失或不在正确的格式中，或者可能是由于 Sketch 文档 version 不兼容导致的。

if (typeof context.utils.getOption('pattern') !== 'string') {
  throw Error('Missing pattern option')
}

if (context.file.original.contents.meta.version < 131) {
  throw Error('Unsupported document version')
}

💡 有关助手错误的更多信息，请阅读我们的 错误处理 指南。