SuperAPI AI 工具集

build-with-calcite-design-system

前端与建站

查看项目

更新于 11-16 16:14

技能介绍

本技能用于在构建、集成、样式设计或审查无障碍 Web 界面时使用 Calcite Design System。Calcite 提供可复用的 UI 组件和已记录的行为,应用代码负责管理应用状态、数据与工作流;它可独立使用,也可与 Esri SDK 搭配,并可与多种前端框架集成。Calcite 组件在设计时考虑了无障碍,但应用仍需提供合适的内容和配置以支持不同用户群体。

适用前提:若应用开发需求不明确,可先使用 gather-arcgis-application-requirements 技能审查项目上下文、澄清关键未知项,再应用本技能的技术指导,并复用请求或项目中已明确的需求。创建应用的开发者需具备以下 ArcGIS 账户之一:ArcGIS Location Platform(免费),或具有 Creator、Professional、Professional Plus 用户类型的 ArcGIS Online 或 ArcGIS Enterprise。账户的用户类型、角色和权限决定可访问的资源和操作。

安装与设置:先检查应用的框架、包管理器、已安装的 Calcite 版本及当前的组件加载方式,复用现有设置与约定,仅在任务需要时更改依赖。按官方 Get started 指南选择加载方式:无包构建的页面使用 CDN,受管应用使用现有包管理器;Custom Elements 构建支持按需导入所用组件,推荐用于框架项目,需要全局注册时选择 Distribution 构建。仅查阅与应用相关的框架集成要求:React 19+ 直接支持自定义元素,React wrapper 在 Calcite 5.0 中已弃用;使用 ArcGIS Maps SDK for JavaScript 时,先核对其 Calcite 加载与版本兼容性说明,再添加导入或更改版本。按所选框架与托管方式加载样式和资源,遵循框架的 CSS 指导;Calcite 资源默认由 CDN 托管,本地托管或使用自定义 CDN 时需配置资源路径。最后在应用中验证:所用组件能注册并渲染,样式和所需资源能加载。选择受支持浏览器时参考系统要求。

文档查询:单独安装本技能不会配置 Esri 开发者文档 MCP 服务器(esri-mcp-server-for-developer-documentation)。需在客户端 MCP 设置中添加 https://developers-mcp.arcgis.com/mcp,或安装完整的 ArcGIS SDKs and APIs 插件(arcgis-sdks-and-apis-plugin)。可用 search_esri_developer_docs 工具,将 focus_area 设为 calcite-design-system 并指定 search_term 检索权威文档页;用 fetch_esri_developer_docs 工具并设置 page_url 返回文档页的完整 Markdown 内容。应明确标注未基于官方文档的建议和假设;MCP 服务器不可用时,查阅官方文档链接。

设计原则:保持用户主要工作区为焦点,次要控件只占所需空间;按工作流和需持续可见的上下文选择布局组件,不要将定位控件分散在页面各处;优先组合现有 Calcite 组件,只有当自定义组件能提供无法通过组合清晰表达的行为或交互时才创建,避免只改样式或改名的包装组件;将响应式行为与自适应行为分开,组件可自行调整尺寸或溢出,但应用可能仍需移动、隐藏或替换内容;在所有支持的尺寸下保持关键操作可用,次要操作可溢出、移入菜单或按需出现;Panel、Sheet、Dialog、Action Bar 或导航模式打开、关闭或变化时,保持当前上下文和焦点。

组件选用:calcite-shell 用于应用框架(页头、内容、Panel、Sheet、Dialog);calcite-navigation 用于应用标识、主导航、用户内容和紧凑导航操作;calcite-shell-panel 用于停靠、浮动、可折叠或可调整大小的侧边或底部区域;calcite-panel 用于有标题的相关内容、控件或状态区域;calcite-sheet 用于临时滑过 Shell 的上下文或移动端内容;calcite-dialog 用于聚焦、可移动、可调整大小或模态的工作区;calcite-action-bar 用于紧凑的相关操作组,需要时溢出;calcite-flow 用于相关视图间的分步或嵌套导航,也是主从布局的一种选择;calcite-block 用于 Panel 内可展开的相关控件组;calcite-list 用于密集的可选、可筛选或层级项目;calcite-tabs 用于应留在同一工作区的相关视图;calcite-card-group 和 calcite-card 用于浏览、目录、画廊等重复内容;calcite-tile-group 和 calcite-tile 用于紧凑的指标、选项或汇总值。

应用外壳与布局:从 calcite-shell 开始,在 header 槽放应用标识和全局导航,在 Shell 槽放次要区域,主工作区放在默认内容区。侧边区域使用 panel-start 或 panel-end,底部工作区使用 panel-bottom 或 content-bottom,导航使用 header,Dialog 使用 dialogs,Shell 拥有的 Sheet 使用 sheets。用户同时需要工具导航和详细控件时,在同一 Shell Panel 中放 Action Bar 和 Panel。地图或场景位于浮动 UI 之后时使用 content-behind,并调整覆盖层尺寸和位置以免阻挡主地图交互。

布局模式:选择支持工作流的最小布局。侧边栏与浮层:控件需常驻主工作区旁时,使用可调整大小的停靠 Shell Panel;需要覆盖工作区并按需开合时使用 display-mode=float;用 --calcite-shell-panel-min-width 和 --calcite-shell-panel-max-width 设置可调整区域的最小和最大尺寸。仪表盘与自适应网格:多个指标、配置控件和主地图或图表需同时可见时,在 Shell 内使用 CSS Grid,仪表盘面板放在 Shell 默认内容区,需移入较小布局的控件使用 Sheet。浏览与目录:使用 Navigation、Menu、Tabs、Tile Group、Card Group 和 Card;小屏幕上将桌面菜单替换为由导航操作打开的 Sheet,让 Tabs 可滚动,Card Group 随空间减少从三列变为两列再变为一列。详情与画廊:保持主地图、图像或画布主导;宽屏时把详情放在旁边的 CSS Grid Panel,小屏时在由操作打开的上下文 Sheet 中显示相同详情;框架应用中渲染一份内容模型到正确的容器,避免维护两份副本。配置与预览:以预览为主焦点,配置控件放在 Shell Panel;预览需自己的应用框架时在预览 Panel 内嵌套 Shell;保持撤销、重做、保存、发布可见,次要的添加内容操作可溢出。工作区与弹出内容:复杂可定制工作流中让用户选择辅助内容显示方式,示例用可调整大小的底部 Shell Panel 停靠,用可拖动、可调整大小的 Dialog 弹出,Sheet 可提供打开项的紧凑列表;同一工作流出现在两处时保持选中项和活动标签同步,切换位置时先隐藏一个再显示另一个,并将焦点移到对应控件。嵌套与可调整区域:嵌套 Shell 适合有多个可调整区域的密集监控或分析工作流,更多内容需容纳时可用 scale=s,但保持标题和调整控件可用,并为每个可调整区域设置最小和最大边界;不要让 Panel 小于其标题、控件或键盘交互所需空间,需考虑嵌套 Panel 的限制而非仅外层 Shell Panel。

响应式与自适应:许多 Calcite 组件已处理常见响应式行为:Action Bar 可溢出为 Action Menu,Tabs 可滚动,Shell Panel 适应可用空间,组件可调整内部间距;应先使用这些内置行为再编写断点逻辑。自适应行为在断点或容器尺寸变化时改变应用布局,可包括更改属性、在槽间移动内容、更改 CSS Grid 区域、隐藏非必要内容或将 Panel 替换为 Sheet。用 CSS 处理呈现,用 JavaScript 处理组件状态和界面变化;生产应用中,若由容器而非视口控制布局,使用框架的响应式状态或 ResizeObserver;内容不再适合时关闭或移动,且不要将焦点留在隐藏元素中。

文档入口:概览用于了解 Calcite 目的和主要文档区域;Get started 用于通过 CDN 或 npm 添加 Calcite、加载样式和资源、选择组件构建;Core concepts 用于理解自定义元素、槽、Shadow DOM、CSS 变量、组件加载、属性与特性、事件、全局配置、表单和模式;Tutorials 用于跟随教程构建应用;Components 用于查找组件并查看用法指导和 API 细节;Accessibility 用于设计与审查键盘访问、焦点、内容、颜色使用、表单和辅助技术支持;Colors and theming 用于应用颜色令牌、选择明暗模式或自定义主题;Design tokens usage 和 Design tokens reference 用于理解令牌层级、覆盖方式及完整参考;Calcite UI Icons 用于选择或集成图标;Framework integration 用于框架与 TypeScript 配置、测试运行器设置和 VS Code IntelliSense;Sample code 用于完整示例。除以上内容外,该资料未提供更多功能、收费、价格或平台信息。