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 分支。