# @carbonorm/postcss-modules 中文文档

规范地址：https://npmcn.com/package/%40carbonorm/postcss-modules/

版本：6\.0\.2
npm 元数据更新时间：2023-07-28T02:25:47.511Z
中文译文更新时间：2026-11-09T08:42:31.551Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40carbonorm/postcss-modules
原文对照：https://npmcn.com/package/%40carbonorm/postcss-modules/?lang=original
项目主页：https://github.com/CarbonORM/postcss-modules#readme
源码仓库：https://github.com/CarbonORM/postcss-modules

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：36.3 kB，21 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：postcss ^8\.0\.0
- 首次发布：2023-07-28T02:23:05.563Z
- 最新版本发布：2023-07-28T02:25:47.306Z
- 近 30 天下载量：3418（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

在所有地方使用 CSS 模块的 PostCSS 插件

## 安装

```sh
npm install @carbonorm/postcss-modules
```

也可以使用：`pnpm add @carbonorm/postcss-modules`、`yarn add @carbonorm/postcss-modules`、`bun add @carbonorm/postcss-modules`

## README

# 邮政模块

A 类 [邮政](https://github.com/postcss/postcss) 要使用的插件 [CSS 模块](https://github.com/css-modules/css-modules) 到处都是 不仅在客户一方.

## 这是什么?

例如,您拥有以下CSS:

```css
/* styles.css */
:global .page {
    padding: 20px;
}

.title {
    composes: title from "./mixins.css";
    color: green;
}

.article {
    font-size: 16px;
}

/* mixins.css */
.title {
    color: black;
    font-size: 40px;
}

.title:hover {
    color: red;
}
```

转变之后,它会变成这样:

```css
._title_116zl_1 {
    color: black;
    font-size: 40px;
}

._title_116zl_1:hover {
    color: red;
}

.page {
    padding: 20px;
}

._title_xkpkl_5 {
    color: green;
}

._article_xkpkl_10 {
    font-size: 16px;
}
```

插件会给您一个 JSON 对象,用于转换类 :

```json
{
    "title": "_title_xkpkl_5 _title_116zl_1",
    "article": "_article_xkpkl_10"
}
```

## 使用量

### 保存导出类

默认情况下,一个带有导出类的JSON文件将放在相应的CSS旁边. 但你有自由 做你想要的一切 出口类,只是 使用该 `getJSON` 调用。 例如, 将有关类的数据保存到相应的 JSON 文件 :

```js
postcss([
    require("postcss-modules")({
        getJSON: function (cssFileName, json, outputFileName) {
            var path = require("path");
            var cssName = path.basename(cssFileName, ".css");
            var jsonFileName = path.resolve("./build/" + cssName + ".json");
            fs.writeFileSync(jsonFileName, JSON.stringify(json));
        },
    }),
]);
```

`getJSON` 也可返回 a `Promise`。 。 。 .

### 生成范围化名称

默认情况下,插件假设所有类都是本地的. 你可以改变 使用 `scopeBehaviour` 选项 :

```js
postcss([
    require("postcss-modules")({
        scopeBehaviour: "global", // can be 'global' or 'local',
    }),
]);
```

要定义全局模块的路径,请使用 `globalModulePaths` 选项. 这是一个由正则表达式定义路径的阵列:

```js
postcss([
  require('postcss-modules')({
    globalModulePaths: [/path\/to\/legacy-styles/, /another\/paths/],
  });
]);
```

要生成自定义类,请使用 `generateScopedName` 回调 :

```js
postcss([
    require("postcss-modules")({
        generateScopedName: function (name, filename, css) {
            var path = require("path");
            var i = css.indexOf("." + name);
            var line = css.substr(0, i).split(/[\r\n]/).length;
            var file = path.basename(filename, ".css");

            return "_" + file + "_" + line + "_" + name;
        },
    }),
]);
```

或者把插入的字符串传递给 `generateScopedName` 选项 (更多细节) [这里](https://github.com/webpack/loader-utils#interpolatename):

```js
postcss([
    require("postcss-modules")({
        generateScopedName: "[name]__[local]___[hash:base64:5]",
    }),
]);
```

有可能添加自定义散列以使用 `hashPrefix` 选项(如 [装弹机](https://webpack.js.org/loaders/css-loader/#hashprefix):

```js
postcss([
    require("postcss-modules")({
        generateScopedName: "[name]__[local]___[hash:base64:5]",
        hashPrefix: "prefix",
    }),
]);
```

### 导出全局

如果您需要通过 JSON 对象与本地对象一起导出全局名称,请添加 `exportGlobals` 选项 :

```js
postcss([
    require("postcss-modules")({
        exportGlobals: true,
    }),
]);
```

### 正在装入源文件

需要时可以通过自定义加载器(参见 [文件系统Lader](https://github.com/css-modules/css-modules-loader-core/blob/master/src/file-system-loader.js) 例如:

```js
postcss([
    require("postcss-modules")({
        Loader: CustomLoader,
    }),
]);
```

您也可以通过任何需要的根路径 :

```js
postcss([
  require('postcss-modules')({
    root: 'C:\\',
  });
]);
```

### 本地公约

类型 : `String | (originalClassName: string, generatedClassName: string, inputFile: string) => className: (string|string[])` 默认 : `null`

导出类名样式, 您 json 中的密钥 .

| 名称 | 类型 | 说明 |
| :-: | :-: | :-- |
| **`'camelCase'`** | `{String}` | 班名将被骆驼化,原班名不会被从当地人中移除 |
| **`'camelCaseOnly'`** | `{String}` | 班名将骆驼化,从当地人中去除原班名 |
| **`'dashes'`** | `{String}` | 只有班级名中的破折号才会被折叠 |
| **`'dashesOnly'`** | `{String}` | 班名中的达什会被骆驼化,原班名将从当地人中去掉 |
| **`'all'`** | `{String}` | 应用骆驼 Case, 破折叠, 以及圆柱形命名公约 |
| **`'none'`** | `{String}` | 只与本地人一起使用斜体命名协议 |

代替字符串,自定义函数可以生成导出类名.

### 解析路径别名

您可以重写路径 `composes/from` 使用 `resolve` 选项. 当您需要解决自定义路径的别名时,它会有所帮助.

参数:

-   `file` 我们想要解决的模块
-   `importer` ——导入我们希望解决的模块的文件

返回值: `string | null | Promise<string | null>`

```js
postcss([
    require("postcss-modules")({
        resolve: function (file, importer) {
            return path.resolve(
                path.dirname(importer),
                file.replace(/^@/, process.cwd()
            );
        },
    }),
]);
```

## 与模板的整合

该插件只将 CSS 类转换为 CSS 模块. 但您可能想要将这些 CSS 模块与您的模板相融合 . 以下是一些例子.

假设您保存了项目的 CSS 模块 `cssModules.json`数字 :

```json
{
    "title": "_title_xkpkl_5 _title_116zl_1",
    "article": "_article_xkpkl_10"
}
```

### 帕格(前贾德)

假设你有一个Pug模板 `about.jade`数字 :

```jade
h1(class=css.title) postcss-modules
article(class=css.article) A PostCSS plugin to use CSS Modules everywhere
```

发音:

```js
var jade = require("jade");
var cssModules = require("./cssModules.json");
var html = jade.compileFile("about.jade")({ css: cssModules });
console.log(html);
```

你会得到以下 HTML:

```html
<h1 class="_title_xkpkl_5 _title_116zl_1">postcss-modules</h1>
<article class="_article_xkpkl_10">
    A PostCSS plugin to use CSS Modules everywhere
</article>
```

### HTML 语言

对于 HTML 转换,我们将使用 [HTML 后页](https://github.com/posthtml/posthtml) 财务报告和审定财务报表 [PostHTML CSS 模块](https://github.com/maltsev/posthtml-css-modules)数字 :

```bash
npm install --save posthtml posthtml-css-modules
```

这是我们的模板 `about.html`数字 :

```html
<h1 css-module="title">postcss-modules</h1>
<article css-module="article">
    A PostCSS plugin to use CSS Modules everywhere
</article>
```

改变它:

```js
var fs = require("fs");
var posthtml = require("posthtml");
var posthtmlCssModules = require("posthtml-css-modules");
var template = fs.readFileSync("./about.html", "utf8");

posthtml([posthtmlCssModules("./cssModules.json")])
    .process(template)
    .then(function (result) {
        console.log(result.html);
    });
```

请检查date=中的日期值 (帮助) [后HTML的文档](https://github.com/posthtml/posthtml/blob/master/readme.md)(中文(简体) )

你会得到以下 HTML:

```html
<h1 class="_title_xkpkl_5 _title_116zl_1">postcss-modules</h1>
<article class="_article_xkpkl_10">
    A PostCSS plugin to use CSS Modules everywhere
</article>
```

## 我能看看插件吗?

当然! 看看这个 [实例](https://github.com/outpunk/postcss-modules-example)。 。 。 .

见 [邮政](https://github.com/postcss/postcss) 为您环境提供示例的文档, 不要忘记运行

```
npm install --save-dev postcss postcss-modules
```

## 发起人

-   德米特里·奥尔耶尼奥夫

## 常见问题

### @carbonorm/postcss-modules 是什么？

在所有地方使用 CSS 模块的 PostCSS 插件

### 如何安装 @carbonorm/postcss-modules？

在项目目录运行 npm install @carbonorm/postcss-modules，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：postcss（^8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @carbonorm/postcss-modules 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @carbonorm/postcss-modules 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @carbonorm/postcss-modules 可以商用吗？

@carbonorm/postcss-modules 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @carbonorm/postcss-modules 的下载量有多少？

根据 npm 官方下载统计，@carbonorm/postcss-modules 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,418 次，日均约 114 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @carbonorm/postcss-modules 还在维护吗？

最新版本 6\.0\.2 发布于 2023/07/28（3 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/07/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。