用途:为 Navara(maplibre/navara)的 navara_three 示例目录新增或修改示例页面时提供约定,包括创建新示例、编辑已有示例、注册到画廊等场景。
主要能力与约定:
- 先阅读 .claude/skills/navara-usage/SKILL.md 及对应主题参考文件,流程文档为 web/navara_three/example/README.md。
- 代码风格优先使用本技能的样板,而非 README 中过时的模板(后者使用 addDefaultAtmosphereLayers() 和内联数据)。
- 理念:示例中不把 API 藏在抽象里,直接调用 view.addLayer()、layer.on("featureUpdated", ...)、layer.update();一个示例只演示一个功能。
- 两条示例轨道:开发/演示示例放在 pages/<name>/ 或 pages/<category>/<name>/;精选画廊放在 pages/examples/<section>/<name>/,需设计批准,且需 meta.ts。
- 文件结构:非简单示例拆为 main.ts(薄入口)与 run.ts(实际逻辑);极小示例可全部内联在 main.ts 并使用顶层 await。
- 画廊示例的 main.ts 是展示主体,data.ts 存放体积较大的内联数据,UI 使用 example/helpers/button.ts 的 addButton,且必须调用 initializeExample(view)。
- 视觉约定:中性灰度底图、每种状态一个鲜明强调色、网格/挤出使用光照、动画按墙钟时间推进、相机角度多样化。
- 共享辅助:constants.ts、control.ts、panel.ts、button.ts、initialize.ts、keys.ts。
使用方式:创建目录并编写 main.ts(画廊轨道还需 run.ts 与 meta.ts),运行 cargo make dev 或 pnpm --filter @navaramap/three dev 预览,使用 pnpm navara_three screenshots <page> 生成截图,提交前运行 pnpm run build:example、pnpm run format、pnpm run lint、pnpm run test。
限制:画廊示例仅在被明确要求且已确定位置时添加,不得为开发/调试或“覆盖度”主动添加;外部数据集需通过 AttributionPlugin 标注来源;WASM 与 TS 源码不同步时需重建。