ui-to-vue

UI To Vue

將 UI 設計稿截圖批次轉換為 Vue 3 Composition API 元件程式碼。

使用時機

• 使用者提供了一個包含設計稿截圖或導出圖檔的目錄。
• 目標應用程式為 Vue 3。
• 使用者希望初步產生頁面元件、共用元件以及 Router 路由設定。
• 使用者指定使用 Vant、Element Plus 或 Ant Design Vue 作為元件庫。

不適用時機

• 使用者只有單張截圖，且需要量身打造的單一元件。
• 目標專案不是 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。

轉換模式

• 頁面分組：當相關截圖代表列表、詳情、表單、載入中（loading）或空狀態（empty）時，將它們合併為一個頁面元件。
• 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 的原始素材。
• 未經授權，請勿在包含客戶私密資料的設計稿上執行此流程。
• 在可重複的自動化工作流程中，請鎖定轉換工具的版本，避免使用 @latest。
• 在 commit 送出程式碼前，請先審查產生的 Vue 程式碼。
• 切勿將 .ui-to-vue.config.json、API Key、產生的金鑰或客戶截圖 commit 至版本控制系統。

產出審查檢查清單

• [ ] 頁面元件已於 views/ 或指定的輸出目錄下產生。
• [ ] 重複出現的 UI 區域僅在明確有重用需求時，才抽離至 components/。
• [ ] 路由產出符合目標專案的 Router 風格。
• [ ] 產生的元件一致性地使用了指定要求的 UI 庫。
• [ ] 產生的 CSS 單位符合設計基準。
• [ ] 程式碼通過專案的 Formatter、Linter、型別檢查器及 Build 建置流程。
• [ ] 占位文案、Mock 資料及產生的資產已在 commit 前完成審查。

疑難排解

問題	排查步驟
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