Eoxelements

🚀 EOxElements

EOxElements 是由 EOX 精心打造的一套地理空間用戶界面（UI）元素的 Web 組件集合，為地理空間相關的 Web 應用開發提供了豐富且實用的組件。

🚀 快速開始

若要使用 EOxElements 中的各個元素，請查看元素子文件夾中的 README 文件以獲取詳細描述和文檔。

打包工具（Vite、Webpack 等）

npm install @eox/<element>

import "@eox/<element>"
<eox-element></eox-element>

腳本標籤引入

<eox-element></eox-element>

<script type="module">
import "@eox/<element>" from "https://cdn.skypack.dev/@eox/<element>"
</script>

✨ 主要特性

• 該集合包含多種不同狀態的元素，可滿足不同開發階段的需求。
• 提供詳細的文檔和交互式示例，方便開發者使用。
• 支持多種引入方式，如通過打包工具或腳本標籤引入。

📚 詳細文檔

請訪問 這裡 獲取描述、API 文檔和交互式示例。

📦 元素說明

元素狀態

• ⭕️ Alpha 元素：正在開發中，可能會有頻繁的重大變更。
• 🟡 Beta 元素：大部分已打磨完善，可投入使用，但仍可能存在重大變更。
• ✅ 穩定 元素：已審核、有文檔記錄且 API 完整。

元素列表

🔧 開發說明

分支命名規範

受 這篇文章 的啟發，請將你的分支命名為 <element>/<changetype>/<name>，例如：

main
map/feature/new-feature
map/fix/some-fix
chart/feature/new-feature
chart/fix/some-fix
[...]

初始設置

為了正確使用 npm 工作區和所有元素，請使用 Node.js >= 20.9.0 LTS。 安裝所有根目錄和元素的依賴項：

npm install

一般建議從根級別執行所有操作，而不是從單個元素文件夾執行。例如，如果你想構建一個元素，請使用：

npm run build -w @eox/<element-name>

更多信息請參考 npm 工作區文檔。

開發服務器

啟動 Storybook 開發服務器：

npm start

這將在本地主機（端口 6006）上打開 Storybook 服務器，可用於開發多個元素狀態。編輯相應元素的 *.stories.js 文件，以創建和處理元素的多個狀態。

類型生成

生成所有類型輸出：

npm run types:generate:all

測試服務器

你可以使用 Cypress 測試 GUI 運行單個測試。它通過組件測試和結合多個元素的端到端（E2E）測試，為每個元素提供一系列配置選項。

組件測試

npm run cypress
--> 選擇組件測試
--> 選擇瀏覽器
--> 選擇測試用例

端到端測試

端到端（E2E）測試使用元素的打包版本。為了能夠對特定元素運行 E2E 測試，你需要先使用 build 或 watch（每次更改時重新構建）命令構建該元素：

npm run watch -w <element>

若要構建/監視所有元素，可使用：

npm run watch:all

選定的元素構建完成後，你可以在 Cypress GUI 中運行相應的測試：

npm run cypress
--> 選擇端到端測試
--> 選擇瀏覽器
--> 選擇測試用例

運行自動化測試

自動化測試（組件測試和 E2E 測試）由每次向主分支提交 PR 時觸發的 GitHub 操作執行。你可以通過以下命令在本地觸發它們：

npm run test:all // 組件測試和 E2E 測試
npm run test:component // 僅組件測試
npm run test:e2e // 僅 E2E 測試

請記住，在運行 E2E 測試之前，按照上述說明構建/監視所有組件。

常用命令

格式化所有元素：

npm run format:all

檢查/修復所有元素的代碼：

npm run lint:all
npm run lint:fix:all

類型檢查：

npm run types:generate:all
npm run typecheck

如果你使用的是 VS Code，並且智能感知功能顯示的錯誤與 CLI 類型檢查不同，你可以設置以下配置：

"typescript.tsdk": "./node_modules/typescript/lib",
"typescript.enablePromptUseWorkspaceTsdk": true,

如果某些功能無法正常工作，有時清理整個設置並刪除所有 node 模塊以重新開始會有所幫助：

npm run clean
--> 刪除所有 node_module 文件夾
npm install

引導新元素

本質上，你只需要在 中創建一個新的子文件夾。此外，建議在 preview.js（將所有元素導入 Storybook 的集中位置）和 release-please-config.json（用於自動化發佈）中添加相應的條目。更多建議如下：

• 新元素首選的語言是 JS + JSDoc（用於 TypeScript 類型檢查）。
• 首選的打包工具是 Vite。
• 組件測試（通過 Cypress 完成）應僅測試特定元素，其他內容最好進行模擬。
• 如果需要，像 lit 這樣的 Web 組件創建框架會很有用。

一些事情由根“系統”處理：

• 測試（集中式 Cypress 設置，自動在 elements 子文件夾中查找 *.cy.js 文件）。
• 代碼檢查和格式化（根 package.json 中的腳本 - 見上文部分）。
• Storybook（集中式 Storybook 設置，自動在 elements 子文件夾中查找 *.stories.js 文件）。

📄 舊版本說明

本項目的主分支包含 EOxElements 的 v2 版本。如需（舊版）v1 EOxElements，請查看 v1 分支。