Importer<sync>

一个实现自定义 Sass 加载逻辑的对象，用于 @use 规则 和 @import 规则。它可以传递给 importers 或 importer。

鼓励仅将文件重定向到磁盘上的导入器使用 FileImporter 接口。

解析加载

这是使用自定义导入器解析加载的过程

  • 编译器遇到 @use "db:foo/bar/baz"。
  • 它使用 "db:foo/bar/baz" 调用 canonicalize。
  • canonicalize 返回 new URL("db:foo/bar/baz/_index.scss")。
  • 如果编译器已经使用此规范 URL 加载了样式表，则它会重新使用现有的模块。
  • 否则，它使用 new URL("db:foo/bar/baz/_index.scss") 调用 load。
  • load 返回一个 ImporterResult，编译器将其用作模块的内容。

有关使用多个导入器和加载路径解析加载的方式的更多详细信息，请参阅 importers。

示例

sass.compile('style.scss', {
  // An importer for URLs like `bgcolor:orange` that generates a
  // stylesheet with the given background color.
  importers: [{
    canonicalize(url) {
      if (!url.startsWith('bgcolor:')) return null;
      return new URL(url);
    },
    load(canonicalUrl) {
      return {
        contents: `body {background-color: ${canonicalUrl.pathname}}`,
        syntax: 'scss'
      };
    }
  }]
});

类型参数

层次结构

  • 导入器

属性

nonCanonicalScheme？

方法

canonicalize load

属性

可选 nonCanonicalScheme

nonCanonicalScheme?: string | string[]

一个 URL 方案或一组方案（不带 :），该导入器承诺永远不会将其用于 canonicalize 返回的 URL。如果它确实返回了使用其中一个方案的 URL，则为错误。

如果设置了此项，则对具有非规范方案的 URL 调用 canonicalize 时，如果已知，则会将 containingUrl 传递给它。

这些方案可能仅包含小写 ASCII 字母、ASCII 数字、+、- 和 .。它们不能为空。

方法

canonicalize

  • 如果此导入器识别 url，则返回其规范格式。

    如果 Sass 已经使用返回的规范 URL 加载了样式表，则它会重新使用现有的解析树（以及 @use 的加载模块）。这意味着导入器**必须确保**相同的规范 URL 始终引用相同的样式表，即使跨不同的导入器也是如此。因此，鼓励导入器使用唯一的 URL 方案来区分彼此。

    尽可能地，自定义导入器应以与内置文件系统导入器相同的方式规范化 URL

    • 导入器应通过在 URL 的基本名称前添加前缀 _，以及在 URL 还没有这些扩展名之一的情况下添加扩展名 .sass 和 .scss 来查找样式表。例如，如果 URL 为 foo/bar/baz，则导入器将查找

      • foo/bar/baz.sass
      • foo/bar/baz.scss
      • foo/bar/_baz.sass
      • foo/bar/_baz.scss

      如果 URL 为 foo/bar/baz.scss，则导入器将仅查找

      • foo/bar/baz.scss
      • foo/bar/_baz.scss

      如果导入器在多个这些 URL 中找到样式表，则它应该抛出一个异常，指示 URL 模棱两可。请注意，如果显式指定了扩展名，则允许存在具有相反扩展名的样式表。

    • 如果所有可能的路径均无效，则导入器应在 URL 后跟 /index 上执行相同的解析。在上面的示例中，它将查找

      • foo/bar/baz/index.sass
      • foo/bar/baz/index.scss
      • foo/bar/baz/_index.sass
      • foo/bar/baz/_index.scss

      如上所述，如果导入器在多个这些 URL 中找到样式表，则它应该抛出一个异常，指示导入模棱两可。

    如果没有找到样式表，则导入器应返回 null。

    使用相同的 URL 多次调用 canonicalize 必须返回相同的结果。使用先前对 canonicalize 的调用返回的 URL 调用 canonicalize 必须返回该 URL。

    从导入器加载的样式表中的相对路径，通过解析相对于包含它的样式表的规范化URL来处理，并将该URL传递回导入器的 canonicalize 方法。例如，假设“解析加载”示例 上面返回了一个包含 @use "mixins" 的样式表。

    • 编译器会解析相对于当前样式表的规范化URL db:foo/bar/baz/_index.scss 的URL mixins，得到 db:foo/bar/baz/mixins。
    • 它使用 "db:foo/bar/baz/mixins" 调用 canonicalize。
    • canonicalize 返回 new URL("db:foo/bar/baz/_mixins.scss")。

    因此，当使用相对于先前调用 canonicalize 返回的URL调用时，canonicalize 必须返回有意义的结果。

    抛出异常

    任何 - 如果此导入器识别 url 但确定它无效，则可能会抛出 Sass 将包装的异常。如果异常对象具有 message 属性，则将其用作包装异常的消息；否则，将使用异常对象的 toString()。这意味着导入器可以安全地抛出纯字符串。

    参数

    • url: string

      加载的URL。由于这可能是相对路径，因此它表示为字符串而不是URL对象。

    • context: CanonicalizeContext

    返回 PromiseOr<null | URL, sync>

    如果此导入器识别 url，则为绝对URL，否则为 null。如果返回 null，则其他导入器或 加载路径可能会处理加载。

    这也可以返回一个 Promise，但如果这样做，则导入器可能只能传递给 compileAsync 和 compileStringAsync，而不是 compile 或 compileString。

load

  • 加载给定 canonicalUrl 的 Sass 文本，如果此导入器找不到它引用的样式表，则返回 null。

    抛出异常

    任何 - 如果此导入器在 url 处找到样式表，但由于某种原因加载失败，或者 url 与此导入器唯一关联但未引用真实样式表，则导入器可能会抛出 Sass 将包装的异常。如果异常对象具有 message 属性，则将其用作包装异常的消息；否则，将使用异常对象的 toString()。这意味着导入器可以安全地抛出纯字符串。

    参数

    • canonicalUrl: URL

      要加载的样式表的规范化URL。这保证来自对 canonicalize 的调用，尽管并非每次对 canonicalize 的调用都会导致对 load 的调用。

    返回 PromiseOr<null | ImporterResult, sync>

    如果可以加载，则为 canonicalUrl 处样式表的内容，如果不能加载，则为 null。

    这也可以返回一个 Promise，但如果这样做，则导入器可能只能传递给 compileAsync 和 compileStringAsync，而不是 compile 或 compileString。