地图能力

platform:map 让插件在当前项目的公共地图上打点、画线、画面、监听交互、注册右键菜单。清单声明 platform:map 权限，代码里 await ctx.capabilities.get('platform:map') 获取并判空。四个宿主都可获取，但调用时要求全局地图已就绪。

fh2-plugin-sdk 是插件开发 SDK；下文模块名用于说明，实际导入路径保留生成工程配置。模块名不表示已发布的 npm 包名。

const map = await ctx.capabilities.get('platform:map')
if (!map) {
  ctx.logger.warn('全局地图不可用，跳过标注')
  return
}

所有坐标使用 { lng, lat, height }，height 必填（可传 0）。

方法清单

方法	输入重点	返回
`addMarker`	`position`；可选 `icon/label/color/visible/clampToGround`	元素句柄
`addBillboard`	`position/image`；可选 `width/height/visible/clampToGround`	元素句柄
`addLabel`	`position/text`；可选 `color/fontSize/visible/clampToGround`	元素句柄
`addPolyline`	`points`；可选 `color/width/dashed/visible/clampToGround`	元素句柄
`addPolygon`	`points`；可选 `fillColor/fillOpacity/outlineColor/outlineWidth/visible/clampToGround`	元素句柄
`recenter`	`{ points, padding? }`	`Promise<void>`；空 points 无效果
`onClick`	`(event) => void`	可释放订阅
`onHover`	`(event) => void`	可释放订阅
`registerContextMenuItem`	`{ id, label, group?, onTrigger }`	可释放注册

元素句柄有 id、update(partialInput)、dispose()。默认样式：Marker 红色；Billboard 32×32；Label 白色 16 px；Polyline 蓝色、3 px 实线；Polygon 蓝色、0.25 透明度、2 px 轮廓。clampToGround 缺省 false。

交互事件：

点击/悬停事件字段为 { id, kind, position }，kind 取 marker|billboard|label|polyline|polygon；悬停事件多一个 hovering: boolean。

只会报告本插件创建的元素；当前实现中事件的 position 固定为 null，需要点击位置时改用右键菜单。

右键菜单触发入参是 { position: GeoPoint | null }：指向天空或拾取失败时为 null。菜单 id 是插件内局部 ID，宿主按插件隔离，不会与其他插件冲突。

生命周期与已知限制

每个图元、订阅、菜单注册都要保存句柄，不用时 dispose()；宿主卸载时插件运行时会兜底清理。

addPolygon 的填充面与闭合轮廓由同一个句柄管理，更新和释放保持同步。

右键菜单只出现在主地图，子地图上没有。

recenter 的 padding 会换算成视口比例，不是精确像素边距。

地图未就绪、切换项目或离开项目时，创建/回中可能失败，必须捕获错误。

图片 URL 能否显示还受资源可达性和 CSP/CORS 影响。

集成片段

先按第一个前端插件建立可运行工程。下面不是完整的 fh2-plugin.json，不可整份替换：将 permissions 去重合并到现有清单，保留现有宿主扩展、界面声明/注册和入口。权限不会触发激活；清单若只有 extensions: []，activate() 不会执行。

合并到 fh2-plugin.json 的字段：

{
  "permissions": ["platform:map", "platform:clipboard"]
}

下面的 definePlugin 只示范入口逻辑组织，不是可直接替换完整工程的入口；保留生成工程的 SDK 导入路径，将能力逻辑合入已有 activate 和业务收尾，保留原有扩展贡献与界面注册。图元操作还要求公共地图已就绪。

// plugin.ts
import { definePlugin } from 'fh2-plugin-sdk'

export default definePlugin({
  async activate (ctx) {
    const [map, clipboard] = await Promise.all([
      ctx.capabilities.get('platform:map'),
      ctx.capabilities.get('platform:clipboard'),
    ])
    if (!map) {
      ctx.logger.warn('全局地图不可用，跳过事件标注')
      return
    }

    const start = { lng: 114.0579, lat: 22.5431, height: 35 }
    const end = { lng: 114.0612, lat: 22.5458, height: 35 }
    const marker = await map.addMarker({
      position: start,
      label: '事件起点',
      color: '#f5222d',
    })
    const route = await map.addPolyline({
      points: [start, end],
      color: '#1677ff',
      width: 4,
    })
    const area = await map.addPolygon({
      points: [
        { lng: 114.056, lat: 22.542, height: 0 },
        { lng: 114.060, lat: 22.542, height: 0 },
        { lng: 114.060, lat: 22.546, height: 0 },
      ],
      fillColor: '#f5222d',
      fillOpacity: 0.18,
      clampToGround: true,
    })
    await map.recenter({ points: [start, end], padding: 48 })

    const clickSubscription = await map.onClick(({ id, kind }) => {
      ctx.logger.info('点击插件图元', { id, kind })
    })
    const menu = await map.registerContextMenuItem({
      id: 'copy-coordinate',
      label: '复制经纬度',
      group: { id: 'incident', label: '事件工具' },
      async onTrigger ({ position }) {
        if (!position || !clipboard) return
        await clipboard.writeText({ text: `${position.lat},${position.lng}` })
      },
    })

    return {
      async dispose () {
        await menu.dispose()
        await clickSubscription.dispose()
        await Promise.all([marker.dispose(), route.dispose(), area.dispose()])
      },
    }
  },
})

常见问题

现象	原因与处理
`addMarker` 报错	地图未就绪或已卸载；捕获错误并提供无地图降级
点击事件里 `position` 是 `null`	当前实现如此；需要位置时用右键菜单回调
收到了别的插件的点击	不会发生——事件只报告本插件登记的图元
图元没消失	保存并调用句柄的 `dispose()`；`dispose()` 幂等可重复调用
海拔高度渲染不对	分清贴地（`clampToGround: true`）与绝对高度两种模式，`height` 是海拔不是离地高

方法清单#

生命周期与已知限制#

集成片段#

常见问题#

方法清单

生命周期与已知限制

集成片段

常见问题