ui-to-vue

用途

ui-to-vue 用于将 UI 设计截图或设计导出图批量转换为 Vue 3 Composition API 组件代码。它适合在用户提供一组按模块和页面状态组织的设计截图、目标应用为 Vue 3、并希望先得到一版页面组件、共享组件和路由接线的场景下使用。

主要能力

• 页面分组：当相关截图分别代表列表、详情、表单、加载或空状态时，将它们合并为一个页面组件。
• UI 库映射：在可行的情况下，将原生视觉元素映射到 Vant、Element Plus 或 Ant Design Vue 组件。
• 切图优先级：优先使用页面级资源，其次是模块级资源，最后是全局共享资源。
• 组件提取：当重复的 UI 区域出现多次时，将其提取为共享组件。

使用方式

输入目录应按模块和页面状态组织截图，例如：

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。

通过 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。

适用场景

• 用户提供按模块和页面状态分组的截图目录。
• 目标应用为 Vue 3。
• 用户希望生成第一版页面组件、共享组件和路由接线。
• 用户指定 Vant、Element Plus 或 Ant Design Vue 作为组件库。

限制与注意事项

不适用的情况：

• 用户只有一张截图，且想要定制组件。
• 目标项目不是 Vue。
• 设计需要详细的交互逻辑、数据流或无障碍审查。
• 截图包含无法发送到外部模型 API 的私有客户数据。

安全与隐私：

• 将设计截图视为可能被发送到外部模型 API 的源材料。
• 未经许可，不要对私有客户设计运行此流程。
• 在可重复的工作流中固定转换器版本，而不是使用 @latest。
• 提交生成的 Vue 代码前先进行审查。
• 不要提交 .ui-to-vue.config.json、API 密钥、生成的机密或客户截图。

输出审查清单：

• 页面组件已生成在 views/ 或所选输出目录下。
• 仅在复用明确时，才将重复 UI 区域提取到 components/。
• 路由输出与目标项目的路由风格兼容。
• 生成的组件一致使用所请求的 UI 库。
• 生成的 CSS 单位与设计基线匹配。
• 代码通过项目的格式化、lint、类型检查和构建。
• 提交前审查占位文案、模拟数据和生成的资源。

故障排查：

问题	检查项
401 或认证错误	确认运行命令的 shell 中已设置 DASHSCOPE_API_KEY
command not found: ui-to-vue	使用 npx ui-to-vue-converter@1.0.2 形式或全局安装该包
切图被忽略	确认资源目录名称受支持，并嵌套在匹配的页面或模块下
组件忽略所请求的 UI 库	使用显式 --ui 值重新运行，并检查生成的导入
生成的布局尺寸看起来不对	确认截图导出宽度与目标库基线匹配

参考：npm 包 ui-to-vue-converter。