编写规则

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

本指南演示了如何创建检查文本图层内容以确保它们不包含“Lorem Ipsum”占位符文本的助手规则。它最后描述了如何使用助手配置来进化规则以禁止使用任何字符串。

💡 确保您已按照入门指南操作。如果您想按照本指南操作，您需要一个可以编辑、重建并查看 Sketch 中的更改结果的本地助手项目。

添加自定义规则

如果您只对入门项目进行了最小程度的更改，那么您应该会发现示例Hello World规则在src/index.ts文件中定义，该文件位于助手定义旁边。

开始将Hello World规则修改为禁止在文本内容中使用 Lorem Ipsum 的规则。您可以随意用以下内容替换src/index.ts的内容。

import {
  AssistantPackage,
  RuleDefinition,
} from '@sketch-hq/sketch-assistant-types'

const textNoLoremIpsum: RuleDefinition = {
  rule: async (context) => {
    // Rule logic will go here
  },
  name: 'sketch-assistant-template/text-no-lorem-ipsum',
  title: 'Text should not contain lorem ipsum',
  description:
    'Reports a violation when text layers contain lorem ipsum placeholder',
}

const assistant: AssistantPackage = async () => {
  return {
    name: 'sketch-assistant-template',
    rules: [textNoLoremIpsum],
    config: {
      rules: {
        'sketch-assistant-template/text-no-lorem-ipsum': {
          active: true,
        },
      },
    },
  }
}

export default assistant

一些需要注意的地方

  • 规则的name是其在助手生态系统中的唯一标识符，因此按照惯例，我们用父助手的名称加上/作为前缀。
  • 通过将其包含在助手的rules数组中，将规则添加到助手包中。
  • 规则默认情况下不处于活动状态，必须在助手的配置对象中明确启用它们。

实现规则逻辑

规则逻辑是在定义为规则定义对象中rule属性的函数中实现的。到目前为止，我们只定义了一个空的匿名异步函数。

async (context) => {
  // Rule logic will go here
}

在绝大多数情况下，您可以仅使用通过context参数传递的API来实现您的规则。但是您并不局限于此 API，可以随意使用辅助函数、npm 模块或任何其他需要完成任务的内容。

让我们添加禁止文本图层中使用lorem ipsum的逻辑。我们将使用适用于许多规则的标准迭代、测试、报告模式。

  1. 迭代 Sketch 文档的对象
  2. 测试对象是否满足某些条件
  3. 如果是，则报告它
async (context) => {
  const { utils } = context
  // Iterate
  for (const layer of utils.objects.text) {
    const value = layer.attributedString.string
    // Test
    if (value.toLowerCase().includes('lorem ipsum')) {
      // Report
      utils.report(`Layer “${layer.name}” contains “lorem ipsum”`, layer)
    }
  }
}

💡 如果您还没有这样做，现在可能是一个好时机来运行npm run package-tarball并在 Sketch 中测试您的工作。

一些需要注意的地方

  • 我们使用utils.objects.text工具迭代文档中的所有文本图层对象。
  • 我们使用utils.report工具向 Sketch 报告问题。至少报告必须包含一条消息，然后可选地包含一个或多个与问题相关的 Sketch 文档对象。
  • 如果您使用的是 Visual Studio Code，您应该会注意到规则工具和 Sketch 文档对象的丰富智能感知和 TypeScript 编译器提示。

创建可配置的规则

目前，该规则被硬编码为查找lorem ipsum字符串。通过将其推广为接受一个选项，我们使其可配置，并且一旦发布，助手将对 Sketch 用户更有用。

以下是新的、推广后的规则函数：

async (context) => {
  const { utils } = context

  // Get a configuration option named "pattern"
  const pattern = utils.getOption('pattern')
  if (typeof pattern !== 'string') throw Error()

  // Iterate
  for (const layer of utils.objects.text) {
    const value = layer.attributedString.string
    // Test
    if (value.includes(pattern)) {
      // Report
      utils.report(`Layer “${layer.name}” contains “${pattern}”`, layer)
    }
  }
}

这里需要注意的几点

  • 我们使用utils.getOption工具从助手的当前配置中提取当前规则的命名选项。
  • 规则用于逻辑而不是意见，因此它们应该避免对默认配置值进行硬编码。出于这个原因，如果配置选项没有正确的数据类型，我们将抛出错误。抛出这样的错误也可以方便地缩小类型以满足 TypeScript 编译器。

我们还没有完全完成，因为虽然我们的规则现在可以配置，但我们还没有实际配置它。我们通过向助手配置添加pattern选项的值来做到这一点。

在下面，我们定义了新的推广后的规则并将其命名为text-disallow，并将pattern设置为Type something。这将产生有趣的副作用，即对添加到画布中并保留默认复制的任何文本图层报告问题，这通常表明工作粗心大意。

import {
  AssistantPackage,
  RuleDefinition,
} from '@sketch-hq/sketch-assistant-types'

const textDisallow: RuleDefinition = {
  rule: async (context) => {
    // Copy and paste from above
  },
  name: 'sketch-assistant-template/text-disallow',
  title: (config) => `Text should not contain "${config.pattern}"`,
  description:
    'Reports a violation when text layers contain a configurable text pattern',
}

const assistant: AssistantPackage = async () => {
  return {
    name: 'sketch-assistant-template',
    rules: [textDisallow],
    config: {
      rules: {
        'sketch-assistant-template/text-disallow': {
          active: true,
          pattern: 'Type something',
        },
      },
    },
  }
}

export default assistant

💡 如果您觉得在没有console.log这样的熟悉功能的情况下，在 Sketch 中测试您的助手很受限制，那么请阅读我们的运行和测试助手指南。它将讨论如何在 Node 中测试您的助手或从命令行运行它。

👉 下一步可以包括扩展助手或深入研究API 参考.