ui-to-vue

UI To Vue

将 UI 设计图截图批量转换为 Vue 3 Composition API 组件代码。

适用场景

• 用户提供了一整套按模块和页面状态分类的设计图截图或导出图。
• 目标项目为 Vue 3。
• 用户希望一键生成页面组件、公共组件以及路由关联的初版代码。
• 用户指定使用 Vant、Element Plus 或 Ant Design Vue 作为 UI 组件库。

不适用场景

• 用户只有一张截图，需要专门定制单个组件。
• 目标项目不是 Vue。
• 界面需要复杂的交互逻辑、数据流或无障碍（accessibility）审查。
• 截图包含内部敏感客户数据，无法发送给外部模型 API。

输入目录规范

建议采用按模块与页面状态归类的截图目录结构：

screenshots/
|-- HomePage/
|   |-- List/
|   |   |-- HomePage-List-Default@3x.png
|   |   `-- cut-images/
|   |-- cut-images/
|   `-- HomePage-Default@3x.png
`-- cut-images/

支持的切图目录名称包括 assets、icons、sprites、cut、images 和 cut-images。

转换策略

• 页面归类：将展示列表、详情、表单、加载中或空状态等相关的截图组合合并为一个页面组件。
• UI 库映射：在可行的情况下，尽量将原生视觉元素精准映射到 Vant、Element Plus 或 Ant Design Vue 的对应组件。
• 切图优先级：优先提取并使用页面级资源，其次是模块级资源，最后是全局共享资源。
• 抽离公共组件：当同类 UI 区域重复出现超过一次时，自动提取为公共组件。

CLI 命令行用法

推荐使用 npx 执行转换器，无需依赖全局安装即可开箱即用：

export DASHSCOPE_API_KEY=your_key
npx ui-to-vue-converter@1.0.2 --input ./screenshots --ui vant --output ./src

桌面端 UI 库使用示例：

npx ui-to-vue-converter@1.0.2 --input ./designs --ui element-plus --output ./src
npx ui-to-vue-converter@1.0.2 --input ./designs --ui antd-vue --output ./src

如果已经全局安装了该包，可以直接使用 ui-to-vue 命令：

npm install -g ui-to-vue-converter@1.0.2
ui-to-vue --input ./screenshots --ui vant --output ./src

参数选项

参数	说明	默认值
--input	设计图目录路径	./screenshots
--ui	指定 UI 库：vant、element-plus 或 antd-vue	vant
--output	产出代码目录	./src
--config	配置文件路径	./.ui-to-vue.config.json

API Key 配置

转换器支持从配置文件或环境变量中读取 DashScope 凭证。代码仓库中推荐优先采用环境变量配置：

export DASHSCOPE_API_KEY=your_key

如果需要使用本地配置文件，请确保不要提交到版本控制：

{
  "apiKey": "your_dashscope_key",
  "input": "./designs",
  "ui": "vant",
  "output": "./src"
}

.ui-to-vue.config.json

安全与隐私提示

• 请把设计图截图视为可能会发送给外部模型 API 处理的素材。
• 未经授权，请勿在包含客户私有设计稿的项目中运行此流程。
• 在要求可复现的工作流中锁定转换器版本（Pin version），避免直接使用 @latest。
• 在提交代码前，请仔细人工复核生成的 Vue 代码。
• 严禁提交 .ui-to-vue.config.json、API Key、密钥、生成的敏感信息或客户设计截图。

生成代码复核 Checklist

• [ ] 页面组件已成功生成在 views/ 或指定的输出目录下。
• [ ] 重复 UI 区域提取到 components/ 的前提是复用关系明确。
• [ ] 路由配置代码与目标项目的 Router 规范保持兼容。
• [ ] 生成的组件全量且一致地使用了指定的 UI 库。
• [ ] 生成的 CSS 单位与设计基准保持一致。
• [ ] 代码流畅通过了项目的 Formatter、Linter、类型检查及 Build 构建。
• [ ] 在 Commit 代码前，已对占位文案、Mock 数据和生成的资源文件完成人工核对。

FAQ 与 Troubleshooting

常见问题	排查建议
报 401 或鉴权错误	检查运行命令的当前 Shell 环境中是否已正确配置环境变量 DASHSCOPE_API_KEY。
提示 command not found: ui-to-vue	请使用 npx ui-to-vue-converter@1.0.2 方式运行，或重新将其全局安装。
切图资源未被成功读取	确认切图目录命名在支持范围内，且准确嵌套在对应的页面或模块路径下。
组件没有使用指定的 UI 库	重新运行并显式指定 --ui 参数，同时检查生成代码的 Import 引用。
布局生成的尺寸/比例不对	检查导出的截图宽度尺寸是否与目标 UI 库的标准基准宽度对齐。

参考资源

• npm 包：ui-to-vue-converter