{"_id":"@amap-lbs/amap-a2ui","name":"@amap-lbs/amap-a2ui","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@amap-lbs/amap-a2ui","version":"0.1.0","description":"AMap map components, renderer, and catalog for the Google A2UI protocol","keywords":["a2ui","agent-ui","amap","lit","maps"],"author":{"name":"AMap"},"license":"MIT","type":"module","sideEffects":true,"engines":{"node":">=20.19.0"},"exports":{"./lit":{"types":"./dist/lit/index.d.ts","default":"./dist/lit/index.js"},"./lit/custom-components":{"types":"./dist/lit/custom-components/index.d.ts","default":"./dist/lit/custom-components/index.js"},"./catalog.json":"./catalog/catalog.json","./common_types.json":"./catalog/common_types.json"},"scripts":{"build":"tsc -b","consumer:check":"tsc -p ./test/external-consumer/tsconfig.json --pretty false","pack:check":"node ./scripts/check-pack.mjs && npm run consumer:check","pack:smoke":"node ./scripts/check-published-package.mjs","prepack":"npm run build && npm run schema:check","prepublishOnly":"npm run typecheck && npm test && npm run pack:check && npm run pack:smoke","schema:check":"tsx ./scripts/check-catalog.ts","schema:generate":"tsx ./scripts/generate-catalog.ts","test":"vitest run --config vitest.config.ts","test:watch":"vitest --config vitest.config.ts","typecheck":"tsc -b --pretty false"},"dependencies":{"@a2ui/lit":"0.10.3","@a2ui/web_core":"0.10.6","@amap/amap-jsapi-loader":"1.0.1","@lit/context":"1.1.6","dompurify":"3.4.14","lit":"3.3.3","markdown-it":"14.2.0","zod":"3.25.76"},"devDependencies":{"@amap/amap-jsapi-types":"0.0.15","@types/markdown-it":"14.2.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_id":"@amap-lbs/amap-a2ui@0.1.0","_integrity":"sha512-V7YSEXiqe6RQcA5Kpjj9WOpKUbiShigH5AlgxAoTk3S6mQJk+/df8AfGZvSeIk3gK4HF98erAFy1RnvJS21nmA==","_resolved":"/tmp/amap-a2ui-release.JUq6WK/amap-lbs-amap-a2ui-0.1.0.tgz","_from":"file:/tmp/amap-a2ui-release.JUq6WK/amap-lbs-amap-a2ui-0.1.0.tgz","_nodeVersion":"22.14.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-V7YSEXiqe6RQcA5Kpjj9WOpKUbiShigH5AlgxAoTk3S6mQJk+/df8AfGZvSeIk3gK4HF98erAFy1RnvJS21nmA==","shasum":"1668a173438918d7eeeb79b6f9b8bb5d96f98c91","tarball":"https://registry.npmjs.org/@amap-lbs/amap-a2ui/-/amap-a2ui-0.1.0.tgz","fileCount":34,"unpackedSize":352503,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHaDI+YjrtP4FSd+VynUd+w3vF03jMrcnuDGb1JQR3HIAiEAvd1vIGj+z3d1tSlC3yVyxcUet+n2erkoLWaK6RqrBbg="}]},"_npmUser":{"name":"amap-lbs-op","email":"amap-lbs-op@service.alibaba.com"},"directories":{},"maintainers":[{"name":"amap-lbs-op","email":"amap-lbs-op@service.alibaba.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/amap-a2ui_0.1.0_1788163568999_0.6634486861882143"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:06:08.773Z","0.1.0":"2026-08-31T08:06:09.121Z","modified":"2026-08-31T08:06:09.503Z"},"maintainers":[{"name":"amap-lbs-op","email":"amap-lbs-op@service.alibaba.com"}],"description":"AMap map components, renderer, and catalog for the Google A2UI protocol","keywords":["a2ui","agent-ui","amap","lit","maps"],"author":{"name":"AMap"},"license":"MIT","readme":"# @amap-lbs/amap-a2ui\n\n面向 A2UI v0.9.1 的高德地图 Lit 组件与 Renderer。\n\n> 当前为实验性 `0.1.x` 版本，API 和 Catalog 在首个稳定版本前可能调整。\n\n## 主要功能\n\n| 能力                  | 说明                                                                       |\n| --------------------- | -------------------------------------------------------------------------- |\n| `AmapMap`             | 渲染 GCJ02 地图中心、Marker 和预计算路线；Marker 点击产生标准 Action       |\n| `AmapPoiCard`         | 展示 POI 名称、地址、分类、评分、距离和标签，并支持详情、路线 Action       |\n| `AmapTemporalHeatmap` | 通过宿主授权的 `datasetRef` 展示时序点热力图，支持筛选、时间轴、播放和图例 |\n| `AmapA2UIRenderer`    | 处理 A2UI 消息、管理 Surface，并把组件 Action 转交宿主                     |\n| Runtime Catalog       | 向 Agent、校验器和宿主应用提供一致的组件能力描述                           |\n\n组件库只负责渲染。POI 搜索、地址解析、坐标转换、路线计算、数据授权和 Action 执行由宿主应用负责。\n\n## 安装\n\n```bash\nnpm install @amap-lbs/amap-a2ui\n```\n\n包使用 ESM，要求 Node.js 20.19+ 和现代浏览器。真实地图渲染需要高德 Web JSAPI 浏览器 Key。\n\n本包参考 `@amap-lbs/amap-gui`，以 MIT 许可证通过公共 npm registry 分发编译后的 JavaScript、类型声明与 Catalog。源码仓库保持私有，发布包不包含 TypeScript 源码或 source map；仓库是否公开与 npm 产物采用何种许可证是两个独立事项。\n\n## 快速开始\n\n在页面中准备 A2UI Surface：\n\n```html\n<a2ui-amap-providers>\n  <a2ui-surface id=\"map-surface\"></a2ui-surface>\n</a2ui-amap-providers>\n```\n\n配置 JSAPI、处理 A2UI 消息并挂载 Surface：\n\n```ts\nimport {\n  AmapA2UIRenderer,\n  configureAmap,\n  registerAmapA2UIElements,\n} from \"@amap-lbs/amap-a2ui/lit\";\n\ntype A2uiSurfaceElement = HTMLElement & { surface?: unknown };\n\nconfigureAmap({\n  key: import.meta.env.VITE_AMAP_KEY,\n  securityJsCode: import.meta.env.VITE_AMAP_SECURITY_JS_CODE,\n});\n\nregisterAmapA2UIElements();\n\nconst renderer = new AmapA2UIRenderer({\n  onAction(action) {\n    // 生产环境应把 Action 发回服务端重新鉴权和执行。\n    console.log(\"A2UI Action\", action);\n  },\n});\n\nrenderer.processMessages(messages);\n\nconst surface = renderer.getSurface(\"map-search-001\");\nif (!surface) {\n  throw new Error(\"找不到 Surface map-search-001\");\n}\n\nconst surfaceElement =\n  document.querySelector<A2uiSurfaceElement>(\"#map-surface\");\nif (!surfaceElement) {\n  throw new Error(\"找不到 #map-surface\");\n}\n\nsurfaceElement.surface = surface;\n\nwindow.addEventListener(\"pagehide\", () => renderer.dispose(), { once: true });\n```\n\n`configureAmap()` 必须在第一张地图挂载前执行。导入 `@amap-lbs/amap-a2ui/lit` 时会尝试自动注册元素；显式调用 `registerAmapA2UIElements()` 是幂等的，并且可以安全地用于 SSR 初始化代码。\n\n`surface` 和 `temporalHeatmapDataProvider` 都是对象属性，不能通过 HTML attribute 或 `setAttribute()` 传递。Lit 模板中必须使用 `.surface=${surface}` 和 `.temporalHeatmapDataProvider=${provider}` 属性绑定。\n\n在单页应用中替换或卸载界面时，先让 `<a2ui-surface>` 离开 DOM，再调用 `renderer.dispose()`。`dispose()` 可重复调用，但调用后不能再用同一个 Renderer 处理消息。\n\n## A2UI 输入约定\n\n每个 Surface 必须：\n\n- 使用 `version: \"v0.9.1\"`；\n- 使用 Catalog `a2ui://amap/maps/v0.1`；\n- 包含 ID 为 `root` 的入口组件；\n- 使用由可信数据源确认的 GCJ02 坐标；\n- 不包含 API Key、Token、Cookie、Authorization、脚本或宿主配置。\n\n典型的新建消息由 `createSurface`、`updateComponents` 和 `updateDataModel` 组成，并在三条消息中使用相同的 `surfaceId`。\n\n## 组件说明\n\n### AmapMap\n\n必填 `center` 和 `zoom`，可选 `viewMode`、`pitch`、`rotation`、`fitView`、`markers` 和 `routes`。\n\n- Marker 使用稳定 ID、标题和 GCJ02 位置。\n- Route 使用宿主预计算的 GCJ02 路径。\n- 组件不会搜索地点、计算路线或转换坐标。\n- Marker 点击产生 `amap.marker.select`。\n\n### AmapPoiCard\n\n必填 `poiId`、`name` 和 `location`，可选地址、分类、评分、距离和标签。\n\n- 配置 `onDetails` 后显示“查看详情”。\n- 配置 `onNavigate` 后显示“去这里”。\n- 对应 Action 为 `amap.poi.details` 和 `amap.poi.navigate`。\n- 组件只展示传入数据，不会根据 POI ID 再次查询。\n\n### AmapTemporalHeatmap\n\n必填不透明 `datasetRef`，可选度量、时间、筛选、播放速度、半径、渐变、比例、控件和图例。\n\n热力图需要宿主配置 Loca 2 或 `AMap.HeatMap`，并注入可信 Provider：\n\n```ts\nimport {\n  configureAmap,\n  type TemporalHeatmapDataProvider,\n} from \"@amap-lbs/amap-a2ui/lit\";\n\nconfigureAmap({\n  key: import.meta.env.VITE_AMAP_KEY,\n  plugins: [\"AMap.HeatMap\"],\n  Loca: { version: \"2.0.0\" },\n});\n\n// 以下三个数据读取函数由宿主实现，并负责鉴权与数据校验。\nconst provider: TemporalHeatmapDataProvider = {\n  async getMetadata(datasetRef, signal) {\n    // 鉴权并返回与 datasetRef 对应的元数据。\n    return loadMetadata(datasetRef, signal);\n  },\n  async getPositions(datasetRef, signal) {\n    // 返回交错排列的 GCJ02 [lng, lat, lng, lat, ...]。\n    return loadPositions(datasetRef, signal);\n  },\n  async getFrame(datasetRef, frameKey, signal) {\n    // 返回与 pointCount 等长的 Float32Array。\n    return loadFrame(datasetRef, frameKey, signal);\n  },\n};\n\nconst providers = document.querySelector(\"a2ui-amap-providers\");\nif (providers) {\n  providers.temporalHeatmapDataProvider = provider;\n}\n```\n\nA2UI 消息只携带 `datasetRef` 和选择参数。数据地址、Authorization、Cookie、原始点和逐帧数组应保留在可信宿主中。\n\n`getPositions()` 返回交错排列的 `[lng, lat, lng, lat, ...]`，数组长度必须等于 `metadata.pointCount * 2`；每个数据帧的 `values.length` 必须等于 `metadata.pointCount`。返回的 `metadata.datasetRef` 和 `frameKey` 也必须与请求值一致。\n\n## Action 处理\n\n`onAction` 收到的是用户意图，不是可信地点事实。服务端应根据自己保存的索引联合校验：\n\n```text\nsurfaceId + sourceComponentId + actionName + poiId\n```\n\n不要直接信任浏览器 Action 附带的坐标、地址、路线或其他业务字段。\n\n## 公开入口\n\n- `@amap-lbs/amap-a2ui/lit`：配置、注册、Provider、Renderer、运行时 Catalog 和公开类型。\n- `@amap-lbs/amap-a2ui/lit/custom-components`：地图组件 API、元素和运行时 Schema。\n- `@amap-lbs/amap-a2ui/catalog.json`：Catalog JSON。\n- `@amap-lbs/amap-a2ui/common_types.json`：Catalog 外部 `$ref` 使用的 A2UI v0.9 公共类型。\n\n校验 Catalog 时必须同时加载 `catalog.json` 和 `common_types.json`，并以相邻文件的方式解析 `./common_types.json` 引用。\n\nVite 等构建工具可以直接导入 Catalog：\n\n```ts\nimport catalog from \"@amap-lbs/amap-a2ui/catalog.json\";\n```\n\n原生 Node.js ESM 使用：\n\n```ts\nimport catalog from \"@amap-lbs/amap-a2ui/catalog.json\" with { type: \"json\" };\n```\n\n## 样式\n\n组件使用 Shadow DOM，不要求额外导入 CSS。宿主可以通过 CSS 自定义属性调整常用外观：\n\n```css\na2ui-amap-map {\n  --amap-a2ui-map-height: 420px;\n  --amap-a2ui-map-radius: 16px;\n}\n\na2ui-amap-poi-card {\n  --amap-a2ui-card-radius: 16px;\n  --amap-a2ui-font-family: system-ui, sans-serif;\n}\n\na2ui-amap-temporal-heatmap {\n  --amap-a2ui-heatmap-height: 520px;\n  --amap-a2ui-heatmap-accent: #087646;\n}\n```\n\n## 常见问题\n\n### 地图提示未配置 Key\n\n确认 `configureAmap()` 在地图挂载前执行，并检查 Key 类型、域名白名单和可选安全码。\n\n### `getSurface()` 返回 `undefined`\n\n检查三条消息的 `surfaceId`、协议版本、Catalog ID 和 `root` 组件是否一致、完整。\n\n### 热力图提示缺少 Provider\n\n确认 Surface 被 `<a2ui-amap-providers>` 包裹，且已经设置 `temporalHeatmapDataProvider`。Provider 返回的坐标系、点数量和帧长度必须与元数据一致。\n\n### POI 卡片没有按钮\n\n只有提供 `onDetails` 或 `onNavigate` 时，对应按钮才会显示。\n\n## 安全边界\n\n- 浏览器 Key 只通过 `configureAmap()` 配置，并限制可信域名。\n- Web Service Key、模型 Key 和数据源凭证只保留在服务端。\n- POI、坐标和路线必须来自可信地图或业务工具。\n- Renderer 前仍应执行消息和业务校验。\n- Action 和 `datasetRef` 必须在服务端重新鉴权。\n\n## License\n\n高德自有实现按 [MIT License](LICENSE) 分发。A2UI 衍生内容及其他第三方材料仍适用各自的许可证，参见 `THIRD_PARTY_NOTICES.md` 和 `THIRD_PARTY_LICENSES.md`。\n","readmeFilename":"README.md","_rev":"1-a7b29752355d2f8830ad1ab489d9c468"}