tdesign-miniprogram-rpx2px

将 tdesign-miniprogram 包产物中的 rpx 单位在用户工程侧统一转换为 px。零依赖、提供 CLI / Node API / Gulp 流插件三种用法。

背景

tdesign-miniprogram 源码使用 750 设计稿（2rpx = 1px），样式默认以 rpx 为单位编写，且部分组件（如 grid / skeleton 等）会在运行时通过 JS 动态拼接含 rpx 的样式字符串。

如果你希望在自己的小程序工程里把 tdesign-miniprogram 这个 npm 包产物的 rpx 全部改成 px（例如适配某些不识别 rpx 的渲染场景，或与主工程统一单位），可以使用本工具。

不修改 tdesign-miniprogram 源码，所有处理只发生在 node_modules / miniprogram_npm 这一层产物上。

默认转换比例 1rpx = 0.5px（与 2rpx = 1px 等价），可通过 --ratio 自定义。

项目结构

tdesign-miniprogram-rpx2px/
├── package.json              # name=tdesign-miniprogram-rpx2px, bin: rpx2px / tdesign-miniprogram-rpx2px
├── README.md                 # 完整使用文档（安装/CLI/Node API/Gulp 三种用法）
├── CHANGELOG.md
├── LICENSE                   # MIT
├── .gitignore
├── .npmignore                # 排除 __tests__ 等开发文件
├── bin/
│   └── rpx2px.js             # CLI 入口（含 shebang 与可执行权限）
├── lib/
│   ├── index.js              # 主入口，聚合 core / runner / gulp
│   ├── index.d.ts            # TypeScript 类型声明
│   ├── core.js               # 转换核心：transformText/Css/Wxml/Script/ByExt
│   ├── runner.js             # 目录批处理：transformDirectory
│   └── gulp.js               # Gulp 流插件
└── __tests__/
    └── rpx2px.test.js        # 25 个用例（Node 内置 assert）

安装

npm i -D tdesign-miniprogram-rpx2px
# 或
pnpm add -D tdesign-miniprogram-rpx2px
# 或
yarn add -D tdesign-miniprogram-rpx2px

也可不安装直接 npx：

npx tdesign-miniprogram-rpx2px

工作范围

| 类型 | 处理策略 | | --- | --- | | .wxss / .css / .less | 替换样式中所有 <num>rpx | | .wxml / .html | 替换 attribute 值（含 {{ ... }} 表达式中的字符串字面量） | | .wxs / .js / .cjs / .mjs / .ts / .json | 仅替换字符串字面量内部的 rpx；标识符、注释、变量名一律不动 |

特别地，模板字符串中 ${expr}rpx 会被改写为 ${(expr) * ratio}px，正确处理 grid / skeleton 这类运行时动态拼接的场景：

// before
return `margin-bottom:-${gutter}rpx; margin-right:-${gutter}rpx`;
// after (ratio = 0.5)
return `margin-bottom:-${(gutter) * 0.5}px; margin-right:-${(gutter) * 0.5}px`;

边界处理：

• 不影响 px / rem / em / % 等其它单位
• 不误伤 rpxFoo / myRpx / rpx2px 等标识符（要求 rpx 右侧不是字母数字下划线）
• 注释中的 5rpx 不会被替换
• calc(-1 * 32rpx) 中的负号原样保留：calc(-1 * 16px)

用法一：CLI（推荐）

# 默认目录：<cwd>/miniprogram_npm/tdesign-miniprogram
npx tdesign-miniprogram-rpx2px

# 指定其它目录（原生小程序工程一般是 miniprogram_npm/tdesign-miniprogram；
# 使用 npm/构建工具的工程则一般是 node_modules/tdesign-miniprogram/miniprogram_dist）
npx tdesign-miniprogram-rpx2px ./node_modules/tdesign-miniprogram/miniprogram_dist

# 自定义比例（设计稿比例为 1：1 时）
npx tdesign-miniprogram-rpx2px --ratio=1

# 仅打印将变更的文件，不写入
npx tdesign-miniprogram-rpx2px --dry-run

# 仅处理 wxss、wxml
npx tdesign-miniprogram-rpx2px --ext=wxss,wxml

完整选项：

tdesign-miniprogram-rpx2px [dir] [options]

  --ratio=<number>           转换比例（默认 0.5）
  --precision=<number>       数字精度（默认 6）
  --unit=<string>            目标单位（默认 px）
  --ext=<list>               仅处理的扩展名，逗号分隔
                             （默认 wxss,less,wxml,wxs,js,ts）
  --include=<list>           仅包含的相对子路径前缀，逗号分隔
  --exclude=<list>           排除的相对子路径前缀，逗号分隔
  --dry-run                  仅打印将变更的文件，不写入
  --quiet                    安静模式，仅打印汇总
  -h, --help                 显示帮助
  -v, --version              显示版本

集成到 npm scripts

在你的 package.json 中：

{
  "scripts": {
    // 原生小程序工程
    "rpx2px": "tdesign-miniprogram-rpx2px miniprogram_npm/tdesign-miniprogram",
    // 在每次安装/同步组件库后自动执行
    "postinstall": "npm run rpx2px"
  }
}

用法二：Node API

const {
  transformByExt,
  transformCss,
  transformWxml,
  transformScript,
  transformDirectory,
} = require('tdesign-miniprogram-rpx2px');

// 1) 字符串级转换
transformCss('.a{padding:32rpx}');                          // → '.a{padding:16px}'
transformByExt('width: 32rpx', '.wxss', { ratio: 0.5 });    // → 'width: 16px'

// 2) 目录批处理（与 CLI 等价）
const result = transformDirectory({
  dir: require('path').resolve('miniprogram_npm/tdesign-miniprogram'),
  ratio: 0.5,
  dryRun: false,
});
console.log(result);
// { scanned, changed, skipped, changedFiles }

TypeScript 类型已内置（lib/index.d.ts）。

用法三：Gulp 流插件

可直接挂在 vinyl 流上，与任何 gulp pipeline 协同工作：

const gulp = require('gulp');
const rpx2pxStream = require('tdesign-miniprogram-rpx2px/lib/gulp');
// 也可：const { gulp: rpx2pxStream } = require('tdesign-miniprogram-rpx2px');

gulp.task('rpx2px', () =>
  gulp
    .src('miniprogram_npm/tdesign-miniprogram/**', {
      base: 'miniprogram_npm/tdesign-miniprogram',
    })
    .pipe(rpx2pxStream({ ratio: 0.5 }))
    .pipe(gulp.dest('miniprogram_npm/tdesign-miniprogram')),
);

选项：

interface Rpx2pxGulpOptions {
  ratio?: number;        // 默认 0.5
  precision?: number;    // 默认 6
  unitTo?: string;       // 默认 'px'
  extensions?: string[]; // 默认 ['wxss','less','wxml','wxs','js','ts']
  transform?: (ctx: { value: number; raw: string; ratio: number; unitTo: string }) => string | void;
}

工作机制

1. 扫描目标目录下匹配扩展名的文件
2. 按文件类型派发到不同的转换器：
   • 样式文件（.wxss / .css / .less）：直接全局替换 <num>rpx
   • WXML / HTML：同上
   • 脚本文件（.js / .cjs / .mjs / .wxs / .ts / .json）：先剥离注释，仅在字符串字面量内部替换；模板字符串中 ${expr}rpx 改写为 ${(expr) * ratio}px
3. 内容若有变更则写回（--dry-run 时仅打印）

FAQ

Q：会修改 tdesign-miniprogram 源码吗？ 不会。本工具只在你工程侧的 miniprogram_npm/tdesign-miniprogram（或 node_modules/tdesign-miniprogram/...）这种产物上运行。

Q：pnpm install 之后还要再跑一次吗？ 是。建议在 postinstall 或构建管线中调用 CLI，确保产物里的 rpx 总是已被转换。

Q：${gutter}rpx 这种动态拼接为什么改写为乘以 ratio？ 因为 gutter 的运行时数值是用 rpx 设计的，要想视觉等价于 px，必须乘以 ratio（默认 0.5）。如果保留 ${gutter}px，运行时尺寸就翻倍了。

Q：会破坏 var(--token, 32rpx) 这种默认值吗？ 不会，默认值中的 32rpx 会被同等替换为 16px。

License

MIT