---

name: ui-to-vue description: 当用户有 UI 截图或设计导出需要批量转换为 Vue 3 组件时使用，特别是配合 Vant、Element Plus 或 Ant Design Vue。 origin: community

UI 转 Vue

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

何时使用

• 用户提供一个设计截图或设计导出图片的目录。
• 目标应用是 Vue 3。
• 用户想要页面组件、共享组件和路由配置的初始版本。
• 用户指定 Vant、Element Plus 或 Ant Design Vue 作为组件库。

不应使用的情况

• 用户只有一张截图并想要定制组件。
• 目标项目不是 Vue。
• 设计需要详细的交互逻辑、数据流或无障碍审查。
• 截图包含不能发送到外部模型 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 密钥处理

转换器可以从配置文件或环境变量读取 DashScope 凭证。在代码仓库中推荐使用环境变量：

export DASHSCOPE_API_KEY=your_key

如果需要本地配置文件，请将其排除在版本控制之外：

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

.ui-to-vue.config.json

安全与隐私

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

输出审查清单

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

故障排除

| 问题 | 检查方法 | | --- | --- | | 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