@yituengine/keymap 1.0.0

package/docs/guide/menu.md

@@ -0,0 +1,101 @@
+# 右键菜单
+
+`KeyMap` 会在初始化时注册一个默认 `Menu`。SDK 自己创建菜单 DOM，并挂载到 `viewer.container` 下；业务项目只需要配置菜单项，不需要手写右键菜单 DOM。
+
+## 基础用法
+
+```ts
+import { eventType } from '@yituengine/keymap';
+
+const menu = new eventType.Menu();
+
+menu.addItem({
+  id: 'copy-coordinate',
+  label: '复制坐标',
+  order: 10,
+  show: (context) => Boolean(context.coordinate),
+  onClick(context) {
+    if (!context.coordinate) return;
+    const { lng, lat, alt } = context.coordinate;
+    navigator.clipboard.writeText(`${lng},${lat},${alt}`);
+  },
+});
+
+map.on(menu);
+```
+
+右键命中地球表面时，`context.coordinate` 和 `context.cartesian` 会有值，SDK 会临时显示一个右键锚点图标。右键天空时仍会显示菜单，但坐标为空。
+
+## 批量添加和删除
+
+```ts
+menu.addItem([
+  {
+    id: 'zoom-picked',
+    label: '定位到对象',
+    order: 20,
+    show: (context) => Boolean(context.specObj?.zoomTo),
+    onClick(context) {
+      context.specObj?.zoomTo?.();
+    },
+  },
+  {
+    id: 'remove-picked',
+    label: (context) => `删除 ${context.specObj?.name ?? '对象'}`,
+    order: 30,
+    disabled: (context) => !context.specObj?.destroy,
+    onClick(context) {
+      context.specObj?.destroy?.();
+    },
+  },
+]);
+
+menu.removeItem(['zoom-picked', 'remove-picked']);
+menu.clearItems();
+```
+
+`addItem()` 使用相同 `id` 时会覆盖旧菜单项。`removeItem()` 支持单个 id 或 id 数组。
+
+## MenuContext
+
+菜单项的 `label`、`show`、`disabled` 和 `onClick` 都会收到同一个上下文：
+
+| 字段         | 说明                                              |
+| ------------ | ------------------------------------------------- |
+| `event`      | Cesium 右键事件。                                 |
+| `coordinate` | WGS84 经纬高，右键天空时为 `null`。               |
+| `cartesian`  | Cesium `Cartesian3`，右键天空时为 `null`。        |
+| `map`        | 当前 `KeyMap` 实例。                              |
+| `menu`       | SDK 创建或复用的菜单 DOM 元素。                   |
+| `specObj`    | 命中的 SDK 资产，如图形、图层登记资产或测量对象。 |
+| `pickedObj`  | Cesium 原始 pick 结果。                           |
+
+## 显示和禁用
+
+`show` 决定菜单项是否渲染，`disabled` 决定菜单项是否可点击：
+
+```ts
+menu.addItem({
+  id: 'edit-picked',
+  label: '编辑对象',
+  show: (context) => Boolean(context.specObj?.showHandler),
+  disabled: (context) => context.map.Status.isMeasure,
+  onClick(context) {
+    context.specObj?.showHandler?.();
+  },
+});
+```
+
+`show` 是同步判断函数，不支持异步请求。需要异步权限或状态时，建议先在业务侧缓存状态，再让 `show` 读取缓存。
+
+## 默认控制点删除
+
+编辑模式下，SDK 的默认交互会给控制点提供“删除节点”菜单项。折线删除后至少保留 2 个节点，多边形删除后会同步更新面、描边、中点、中心点和 `onChanged` 回调。
+
+## 生命周期
+
+```ts
+map.off(menu);
+```
+
+`destroy()` 会隐藏菜单、销毁右键锚点、移除 Cesium 事件和 SDK 自建的菜单 DOM。

package/docs/guide/quick-start.md

@@ -0,0 +1,74 @@
+# 快速开始
+
+## 安装
+
+```bash
+npm install @yituengine/keymap cesium@1.106 vue@^3.2.0
+```
+
+## 创建容器
+
+```html
+<div
+  id="map"
+  style="width: 100%; height: 100vh"
+></div>
+```
+
+`initMap(containerId)` 会通过 `document.querySelector` 查找 `#containerId`，所以容器必须在调用前已经挂载到 DOM。
+
+## 初始化地图
+
+```ts
+import { initMap } from '@yituengine/keymap';
+
+const map = initMap('map');
+if (!map) throw new Error('地图初始化失败，请检查容器 id');
+
+map.flyTo({
+  position: [113.2644, 23.1291, 3000],
+  duration: 2,
+});
+```
+
+第二个参数 `disablePopup` 可用于按业务状态临时禁用默认弹窗：
+
+```ts
+const map = initMap('map', () => isDrawing.value || isEditing.value);
+```
+
+`disablePopup` 只影响默认弹窗和部分分类 Primitive 的点击颜色处理，不会关闭图形 `onClick`、右键菜单、编辑拖拽或悬停高亮。
+
+## 添加图层和图形
+
+```ts
+import * as Cesium from 'cesium';
+import { initMap, layer, graphic } from '@yituengine/keymap';
+
+const map = initMap('map');
+if (!map) throw new Error('地图初始化失败');
+
+const businessLayer = new layer.GraphicLayer({ name: '业务图层' });
+map.addLayer(businessLayer);
+
+const point = new graphic.BillboardGraphic({
+  name: '项目位置',
+  position: Cesium.Cartesian3.fromDegrees(113.2644, 23.1291, 30),
+  image: '/icons/location.svg',
+  width: 32,
+  height: 32,
+});
+
+businessLayer.addGraphic(point);
+point.flyTo();
+```
+
+## 销毁
+
+在单页应用组件卸载时销毁地图：
+
+```ts
+map.destroy();
+```
+
+`destroy()` 会清理默认交互、图层、数据源和 Cesium Viewer。

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@yituengine/keymap",
+  "version": "1.0.0",
+  "description": "Cesium 1.106 based 3D GIS engine SDK",
+  "main": "./dist/engine.js",
+  "module": "./dist/engine.js",
+  "types": "./dist/types/main.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/main.d.ts",
+      "import": "./dist/engine.js",
+      "default": "./dist/engine.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs/guide"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "dev": "rollup -c build/rollup.config.dev.js -w",
+    "build": "rollup -c build/rollup.config.js && npm run build:types",
+    "build:types": "tsc -p tsconfig.types.json && node build/rewrite-dts-aliases.mjs",
+    "doc": "typedoc --options typedoc.json",
+    "doc:api": "typedoc --options typedoc.json",
+    "doc:check": "typedoc --options typedoc.json --treatWarningsAsErrors",
+    "prepack": "npm run build",
+    "typecheck": "tsc"
+  },
+  "devDependencies": {
+    "@rollup/plugin-alias": "^5.1.1",
+    "@rollup/plugin-babel": "^6.1.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@rollup/plugin-url": "^8.0.2",
+    "@types/lodash-es": "^4.17.12",
+    "prettier": "^3.8.1",
+    "rollup": "^4.17.2",
+    "rollup-plugin-javascript-obfuscator": "^1.0.4",
+    "rollup-plugin-obfuscator": "^1.1.0",
+    "rollup-plugin-serve": "^1.1.1",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.20",
+    "typescript": "^5.9.2",
+    "vue": "3.2.26"
+  },
+  "dependencies": {
+    "@turf/turf": "^7.3.2",
+    "cesium": "1.106",
+    "lodash-es": "^4.18.1"
+  },
+  "peerDependencies": {
+    "vue": ">=3.2.0 <4.0.0"
+  }
+}