https://github.com/minko-fe/postcss-pxtorem
A postcss plugin that converts px to rem. px 转 rem 的 postcss 插件
https://github.com/minko-fe/postcss-pxtorem
css postcss postcss-pxtorem px2rem pxtorem
Last synced: 18 days ago
JSON representation
A postcss plugin that converts px to rem. px 转 rem 的 postcss 插件
- Host: GitHub
- URL: https://github.com/minko-fe/postcss-pxtorem
- Owner: minko-fe
- License: mit
- Created: 2022-08-19T14:58:51.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-30T08:31:19.000Z (over 2 years ago)
- Last Synced: 2025-10-25T03:28:22.695Z (9 months ago)
- Topics: css, postcss, postcss-pxtorem, px2rem, pxtorem
- Language: TypeScript
- Homepage: https://hemengke1997.github.io/postcss-pxtorem/
- Size: 775 KB
- Stars: 66
- Watchers: 3
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README-zh.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING-en.md
- License: LICENSE
Awesome Lists containing this project
README
# postcss-pxtorem
![npm][npm-img]
**中文** | [English](./README.md)
> [PostCSS](https://github.com/ai/postcss) 插件，可以从像素单位生成 rem 单位
**如果你不需要以下新特性，可以使用官方库：[postcss-pxtorem](https://github.com/cuth/postcss-pxtorem)**
## [新特性](#-关于新特性)
- 在样式文件中动态重写覆盖任意 `postcss-pxtorem` 支持的选项
- 在样式文件中动态禁用转化rem
- **兼容vite，_解决了vite build后px转rem失败的问题_**
## 安装
```bash
npm install postcss @minko-fe/postcss-pxtorem -D
```
## 使用
> 像素是最容易使用的单位。它们的唯一问题是，它们不能让浏览器改变默认的 16 号字体大小。postcss-pxtorem 将每一个 px 值转换为你所选择的属性中的 rem，以便让浏览器设置字体大小。
### postcss.config.js
#### example
```js
// postcss.config.js
import pxtorom from '@minko-fe/postcss-pxtorem'
export default {
plugins: [
pxtorom({
rootValue: 16,
selectorBlackList: ['some-class'],
propList: ['*'],
atRules: ['media'],
// ...
}),
],
}
```
### options
| Name | Type | Default | Description |
| ----------------- | ------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| rootValue | `number` \| `((input: Input) => number)` | 16 | 代表根元素的字体大小或根据 [`input`](https://api.postcss.org/Input.html) 参数返回根元素的字体大小 |
| unitToConvert | `string` | `px` | 需要转化的单位，默认 `px` |
| unitPrecision | `number` | 5 | 小数点后精度 |
| propList | `string[]` | `['*']` | 可以从 px 改变为 rem 的属性，参考：[propList](#propList) |
| selectorBlackList | `(string \| RegExp)[]` | [] | 忽略的选择器，保留为 px。参考：[selectorBlackList](#selectorBlackList) |
| replace | `boolean` | true | 直接在 css 规则上替换值而不是添加备用 |
| atRules | `boolean` \| `string[]` | false | 允许`at-rules`中转换 rem。参考 [At-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule) |
| minPixelValue | `number` | 0 | 最小的 px 转化值（小于这个值的不转化） |
| exclude | `string` \| `RegExp` \| `((filePath: string) => boolean)` \| `null` | null | 忽略的文件路径。参考：[exclude](#exclude) |
| include | `string` \| `RegExp` \| `((filePath: string) => boolean)` \| `null` | null | 包括的文件路径，与 `exclude` 相反，优先级低于 `exclude` |
| disable | `boolean` | false | 关闭插件，可用于动态禁用插件 |
| convertUnit | `ConvertUnit` \| `ConvertUnit[]` \| false | false | 插件处理的最后阶段转换单位 |
#### propList
- 值需要完全匹配
- 使用通配符 `*` 来启用所有属性. Example: `['*']`
- 在一个词的开头或结尾使用 `*`. (`['*position*']` will match `background-position-y`)
- 使用 `!` 不匹配一个属性. Example: `['*', '!letter-spacing']`
- 组合 `!` 与 `*`. Example: `['*', '!font*']`
#### selectorBlackList
- 如果值是字符串，它会检查选择器是否包含字符串.
- `['body']` will match `.body-class`
- 如果值是正则，它会检查选择器是否与正则相匹配.
- `[/^body$/]` will match `body` but not `.body`
#### exclude
- 如果值是字符串，它检查文件路径是否包含字符串
- `'exclude'` will match `\project\postcss-pxtorem\exclude\path`
- 如果值是正则，它将检查文件路径是否与正则相匹配
- `/exclude/i` will match `\project\postcss-pxtorem\exclude\path`
- 如果值是函数，你可以使用排除函数返回 true，文件将被忽略
- 回调将传递文件路径作为一个参数，它应该返回一个 boolean
- `function (file) { return file.includes('exclude') }`
## 关于新特性
### 在 css 中，动态设置插件选项
#### 整个文件禁用转换
```css
/* pxtorem?disable=true */
.rule {
font-size: 15px; // 15px
}
```
#### 设置 rootValue
```css
/* pxtorem?rootValue=32 */
.rule {
font-size: 30px; // 0.9375rem
}
```
以上只是简单的栗子，你可以在 css 文件中设置任意 `postcss-pxtorem` 支持的选项
聪明的你，或许已经看出来了，`/* pxtorem?disable=true */` 很像浏览器 url query？
没错。关于规范，只需参考：[query-string](https://github.com/sindresorhus/query-string)
#### 完整例子
```css
/* pxtorem?disable=false&rootValue=32&propList[]=*&replace=false&selectorBlackList[]=/some-class/i */
```
### 在 css 中，动态禁用转换
```css
.rule {
/* pxtorem-disable-next-line */
font-size: 15px; // 15px
}
```
如果你写 `15PX`（只要不是 `px`），插件也会忽略，因为 `unitToConvert` 默认是 `px`
如果你希望使用 `PX` 忽略并且希望最后得到的单位是 `px`，你可以这样
```js
// postcss.config.js
import pxtorem from '@minko-fe/postcss-pxtorem'
export default {
plugins: [
pxtorem({
convertUnit: {
source: /px$/i,
target: 'px',
},
}),
],
}
```
## 搭配[modern-flexible](https://github.com/hemengke1997/modern-flexible)使用
### example
#### 入口函数
```ts
import { flexible } from 'modern-flexible'
flexible({
rootValue: 16,
distinctDevice: [
{ isDevice: (clientWidth) => clientWidth < 750, UIWidth: 375, deviceWidthRange: [375, 750] },
{ isDevice: (clientWidth) => clientWidth >= 750, UIWidth: 1920, deviceWidthRange: [1080, 1920] },
],
})
```
## ❤️ 感谢
[postcss-pxtorem](https://github.com/cuth/postcss-pxtorem)
[@tcstory/postcss-px-to-viewport](https://github.com/tcstory/postcss-px-to-viewport)
## 相关
转换 px 至 viewport 的 postcss 插件 [postcss-pxtoviewport](https://github.com/hemengke1997/postcss-pxtoviewport)
## 支持
**如果这个仓库帮了你的忙，请右上角star，感谢！～ 😎**
## License
MIT
[npm-img]: https://img.shields.io/npm/v/%40minko-fe/postcss-pxtorem.svg