@wuipkg/stitch-converter

一个面向 Stitch 导出原型页的 CLI 包，用于把 raw*.html 转换为：

• Vue 单文件组件
• 转换报告

它按 targetWidth / sourceWidth 的公式做单位换算，适合配合 amfe-flexible + postcss-pxtorem 一类项目使用，并支持将字体、图片等外部资源本地化。

安装

环境要求：Node.js >= 20

pnpm add -D @wuipkg/stitch-converter

CLI

# 单文件转换，默认输出 Vue（`both` 预留给未来多目标）
npx stitch-converter --input raw.html --out-dir src/views/home

# 批量转换当前目录下匹配的文件
npx stitch-converter --glob "raw*.html" --out-dir raw-previews

# 指定输出文件基名（仅 --input 单文件模式有效）
npx stitch-converter --input raw.html --out-dir src/views/index --output-name index.vue

# 只输出 Vue SFC，不输出 HTML
npx stitch-converter --input raw.html --out-dir src/views/home --output vue

# 先清空资源目录再重新下载（偶发需求，不改配置）
npx stitch-converter --input raw.html --out-dir src/views/home --clean-assets

# 覆盖配置文件中的换算宽度
npx stitch-converter --input raw.html --out-dir src/views/home --source-width 375 --target-width 750

# 启用转换报告输出
npx stitch-converter --input raw.html --out-dir src/views/home --report

--out-dir 为必填参数；sourceWidth / targetWidth 推荐放到项目根目录的 stitch-converter.config.ts、stitch-converter.config.mts 或 stitch-converter.config.mjs 中。

运行期参数

| 参数 | 类型 | 说明 | |---|---|---| | --input | string | 单个输入文件路径，与 --glob 二选一 | | --glob | string | Glob 模式，匹配当前工作目录下的文件（不递归子目录） | | --out-dir | string | 输出目录，必填 | | --output | vue \| both | 控制输出目标；当前 both 与 vue 行为一致，预留给未来多目标输出 | | --output-name | string | 指定输出基名，仅 --input 单文件模式有效。传 index 或 index.vue 均输出 index.* 系列文件 | | --report | boolean | 是否输出 *.report.json，可用 --no-report 关闭 | | --clean-assets | boolean | 先清空本次输出对应的 *.assets 目录，再重新下载字体/图片资源 | | --source-width | number | 覆盖配置文件中的 sourceWidth | | --target-width | number | 覆盖配置文件中的 targetWidth |

注意：--glob 仅扫描当前工作目录（process.cwd()）下的直接子文件，不支持递归匹配，请勿使用 "raw/**/*.html" 这类路径。

项目配置

在项目根目录创建 stitch-converter.config.ts：

import { defineConfig } from '@wuipkg/stitch-converter'

export default defineConfig({
  sourceWidth: 390,
  targetWidth: 750,
  output: 'both',       // 'vue' | 'both'
  outputName: 'index.vue',
  report: true,
  rootFontSize: '20px', // 仅用于 Vue 输出；页面本身没有显式根字号时可作为默认值
  fontAliases: {
    'font-noto-serif': ['Noto Serif SC', 'serif'], // 显式映射未声明在 Tailwind 配置内的特殊字体类
  },
  assets: {
    downloadFonts: true,        // 默认 true
    downloadFullFonts: false,   // 默认 false；设为 true 下载包含完整字符集的字体包，而非只含 text= 指定字符的子集
    downloadImages: true,       // 默认 true
    cleanOutputAssetDir: false, // 默认 false；设为 true 等同于每次都加 --clean-assets
  },
  materialSymbols: {
    linkOpticalSizeToFontSize: true,
  },
  format: {
    command: 'pnpm exec prettier --write {vueFiles} {reportFiles}',
  },
})

如果你更偏好原生 ESM 文件，也可以继续使用 stitch-converter.config.mjs，直接默认导出一个对象即可。

优先级：CLI 参数 > 配置文件 > 内置默认值。outDir 始终需要在运行时显式传入。

配置字段默认值

| 字段 | 默认值 | 说明 | |---|---|---| | sourceWidth | undefined | 未设置时不做换算 | | targetWidth | undefined | 未设置时不做换算 | | output | 'both' | | | outputName | '' | 空时按输入文件名推导 | | report | false | | | rootFontSize | undefined | 仅影响 Vue 根节点；px/rem 会按宽度换算，其它值保持原样 | | fontAliases | undefined | 将特定的 font-* 工具类映射到实际字体的回退列表；键名要求为完整的类名，且不能是保留字重或任意值类 | | assets.downloadFonts | true | | | assets.downloadFullFonts | false | 设为 true 时移除 Google Fonts URL 中的 text= 参数，下载包含完整字符集的字体文件 | | assets.downloadImages | true | | | assets.cleanOutputAssetDir | false | | | materialSymbols.linkOpticalSizeToFontSize | false | | | format | null | 未配置则跳过格式化 |

format.command 占位符

| 占位符 | 说明 | |---|---| | {outDir} | 输出目录的绝对路径 | | {vueFile} / {vueFiles} | 本次写出的所有 .vue 文件路径，空格拼接（同义） | | {reportFile} / {reportFiles} | 本次写出的所有 .report.json 文件路径，空格拼接（同义） | | {generatedFiles} | 以上所有文件路径，空格拼接 |

materialSymbols.linkOpticalSizeToFontSize

开启后，会按 raw 视觉字号给 Material Symbols 图标补 opsz，并限制在 Google 官方建议的 20..48 区间内。

内置别名

转换时会自动注入以下工具类别名，无需手动配置：

| 别名 | 展开值（示例：sourceWidth=390, targetWidth=750） | 说明 | |---|---|---| | text-body-md | text-[30.77px]/[46.15px] | 按换算比例缩放的正文字号/行高，随 sourceWidth/targetWidth 变化 | | pb-safe | pb-[env(safe-area-inset-bottom)] | iOS 安全区底部内边距 |

输出

每个输入文件会生成（视 output 配置而定）：

• *.vue — Vue SFC（output: 'vue' 或 'both'；当前 both 仍只输出 Vue）
• *.report.json — 转换报告（report: true 时输出）
• *.assets/* — 本地化的字体 / 图片资源

提示：建议将生成的 *.assets 文件夹与对应的 .vue 代码置于同级目录，并一并加入版本控制（Git），以确保团队协作和最终产物构建时能正常加载相关的字体与图片资源。

当前支持

• 尺寸、字号、默认行高、间距、圆角、阴影、模糊的精准原子化
• 页面内联 tailwind.config 中 colors、fontFamily、borderRadius 等 theme token 的展开
• Tailwind 默认色板颜色原子化
• 简单自定义样式类内联
• 图片资源本地化：img/srcset/style/url(...)
• Material Symbols helper 收敛到页面级 scoped 样式，避免污染全局图标基线
• Material Symbols 变量轴改写为 CSS 变量，并支持按图标字号联动 opsz
• Vue SFC 输出