typescript-plugin-css-modules

这是一个用于 CSS Modules 的 TypeScript 语言服务插件。

关于此插件

此插件为 IDE 和其他使用 TypeScript 语言服务插件的工具提供类型信息。

目前，TypeScript 在编译过程中不支持插件。这意味着此插件无法：

在编译过程中提供错误信息，或
为您的项目添加 CSS 模块支持。

有关更多信息，或者要添加对此功能的支持，请参阅：https://github.com/microsoft/TypeScript/issues/16607。

如果您需要其他解决方案，这些项目可能会有帮助：

对于 Jest 支持，请参阅 https://www.npmjs.com/package/jest-css-modules-transform（多个选项之一）。
对于 Webpack 配置，请参阅 https://webpack.js.org/loaders/css-loader/#pure-css-css-modules-and-postcss 获取示例。

安装

使用 Yarn 安装：

yarn add -D typescript-plugin-css-modules

使用 npm 安装：

npm install -D typescript-plugin-css-modules

安装完成后，将此插件添加到您的 tsconfig.json 中：

{
  "compilerOptions": {
    "plugins": [{ "name": "typescript-plugin-css-modules" }]
  }
}

如果您使用的是 Visual Studio Code，请同时按照这些说明进行操作。

由于 Webpack 配置各不相同，您可能需要为此插件提供额外的选项以匹配您的项目配置。对于 Create React App 用户，此插件无需额外配置即可工作。

导入 CSS

您的 CSS 模块始终提供默认导出。

import styles from 'my.module.css';

const a = styles.myClass;
const b = styles['my_other-class'];

从版本 1.1.0 开始，您还可以对不包含连字符或下划线的类使用命名导出。您仍然可以通过默认导出访问其他类。

import styles, { myClass } from 'my.module.css';

const a = myClass;
const b = styles['my_other-class'];

选项

请注意，没有任何选项是必需的。但是，根据您的配置，您可能需要自定义这些选项。

选项	默认值	描述
`additionalData`	`undefined`	一个可选的字符串，附加到源文件的顶部。
`allowUnknownClassnames`	`false`	禁用 TypeScript 对未知类名的警告（仅适用于默认导入）。
`classnameTransform`	`"asIs"`	请参阅下面的 `classnameTransform`。
`customMatcher`	`"\\.module\\.((c\|le\|sa\|sc)ss\|styl)$"`	更改此插件处理的文件扩展名。
`customRenderer`	`false`	请参阅下面的 `customRenderer`。
`customTemplate`	`false`	请参阅下面的 `customTemplate`。
`goToDefinition`	`false`	启用跳转到定义功能。请参阅下面的 `goToDefinition`。
`noUncheckedIndexedAccess`	`false`	启用以兼容 TypeScript 的 `noUncheckedIndexedAccess`。
`namedExports`	`true`	为兼容的类名启用命名导出。
`dotenvOptions`	`{}`	提供 `dotenv` 的选项。请注意，此插件仅接受 `path` 的 `string` 值。
`postcssOptions`	`{}`	请参阅下面的 `postcssOptions`。
`rendererOptions`	`{}`	请参阅下面的 `rendererOptions`。

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "typescript-plugin-css-modules",
        "options": {
          "classnameTransform": "dashes",
          "customMatcher": "\\.m\\.css$",
          "customRenderer": "./myRenderer.js",
          "dotenvOptions": {},
          "postcssOptions": {},
          "rendererOptions": {}
        }
      }
    ]
  }
}

`classnameTransform`

实现 localsConvention css-loader 选项的行为。

可用选项有：'asIs'、'camelCase'、'camelCaseOnly'、'dashes' 和 'dashesOnly'。

`customRenderer`

customRenderer 是一个高级选项，允许您提供 CSS 渲染器。

当提供自定义渲染器时，不会使用其他渲染器。

customRenderer 的路径必须相对于项目根目录（例如 ./myRenderer.js）。

自定义渲染器本身应该是一个 JavaScript 文件。该函数将被调用，并传入三个参数：一个 css 字符串、一个 options 对象（参见 options.ts）和一个 compilerOptions 对象 - 包含在 tsconfig.json 中设置的选项。它必须是同步的，并且必须返回有效的 CSS。

module.exports = (css, { fileName, logger }) => {
  try {
    // ...在这里处理您的 css。

    // `string`
    return renderedCss;
  } catch (error) {
    logger.error(error.message);
  }
};

如果您想返回源映射，可以从导出的函数返回一个对象。

module.exports = (css, { fileName, logger }) => {
  try {
    // ...在这里处理您的 css。

    return {
      // `string`
      css: renderedCss,
      // `RawSourceMap`
      sourceMap: sourceMap,
    };
  } catch (error) {
    logger.error(error.message);
  }
};

您可以在我们的测试固件中找到自定义渲染器的示例（customRenderer.js）。

提供内部 logger 用于调试。

如果您使用 Webpack，请注意 Less 和 Sass 原生不支持波浪线（~）导入。

对于 Sass 用户：从 v3 开始，已实现自定义导入器来解决此问题。

对于 Less 用户：此包导出了一个启用波浪线导入的自定义渲染器：less-plugin-aliases。

`customTemplate`

customTemplate 是一个高级选项，允许您为生成的 TypeScript 声明提供模板。

提供自定义模板时，其输出将用作虚拟声明（*.d.ts）文件。

customTemplate 的路径必须相对于项目根目录（例如 ./customTemplate.js）。

自定义渲染器本身应该是一个 JavaScript 文件。该函数将被调用，并传入两个参数：一个 dts 字符串和一个 options 对象（参见 options.ts）。它必须是同步的，并且必须返回有效的 TypeScript 声明（如 .d.ts 文件中所示）。

module.exports = (dts, { classes, fileName, logger }) => {
  try {
    // ...在这里生成您的模板。
    return customTemplate;
  } catch (error) {
    logger.error(error.message);
  }
};

你可以在我们的测试固件中找到一个自定义模板示例（customTemplate.js）。

提供内部logger用于调试。

classes对象代表从CSS模块中提取的所有类名。如果你想为CSS类添加自定义表示，可以使用它们。

`goToDefinition`

这允许像Visual Studio Code这样的编辑器跳转到类名的定义（文件和行）。

这是实验性的，可能并不总是按预期工作。它当前支持CSS/PostCSS、Less和Sass。如果发现有什么不起作用，请提出问题。

`postcssOptions`

选项	默认值	描述
`useConfig`	`false`	设置为`true`以从你的PostCSS配置加载插件。
`excludePlugins`	`false`	仅支持同步插件。使用此选项设置要排除的异步插件数组（例如`['postcss-mixins']`）

`rendererOptions`

选项	默认值	描述
`less`	`{}`	设置Less的渲染器选项。
`sass`	`{}`	设置Sass的渲染器选项。
`stylus`	`{}`	设置Stylus的渲染器选项。

为方便起见，Sass的loadPaths是扩展而不是替换。默认值是当前文件的路径和'node_modules'。

Visual Studio Code

替代用法

如果你没有使用任何插件选项，你可以简单地将此插件添加到设置中的"typescript.tsserver.pluginPaths"。使用这种方法无法提供插件选项。

{
  "typescript.tsserver.pluginPaths": ["typescript-plugin-css-modules"]
}

自定义定义

注意：如果你使用的是react-scripts@2.1.x或更高版本，Create React App用户可以跳过此部分。

如果你的项目还没有CSS模块的全局声明，你需要添加这些声明以帮助TypeScript在构建过程中理解导入的CSS的一般形状。

你可以自行决定存储全局声明的位置。一个例子可能看起来像：./src/custom.d.ts。

以下是一个你可以复制或修改的示例（你只需要为项目中使用的扩展名添加声明）。如果你使用customMatcher，你需要修改这个。

declare module '*.module.css' {
  const classes: { [key: string]: string };
  export default classes;
}

declare module '*.module.scss' {
  const classes: { [key: string]: string };
  export default classes;
}

declare module '*.module.sass' {
  const classes: { [key: string]: string };
  export default classes;
}

declare module '*.module.less' {
  const classes: { [key: string]: string };
  export default classes;
}

declare module '*.module.styl' {
  const classes: { [key: string]: string };
  export default classes;
}