消息导航与通知

消息宿主提供两个宿主级能力：platform:navigation（页面跳转）和 platform:notification（顶部提示）。典型场景：告警卡片上点"查看"跳到驾驶舱，并给用户一个成功提示。清单声明对应权限，代码里 await ctx.capabilities.get(...) 获取并判空。

能力状态

能力	状态	API
`platform:navigation`	消息宿主可用	`open(url, { target })`、`back()`
`platform:notification`	消息宿主可用	`show({ key, message, intent, durationMs? })`
`platform:location`	消息宿主不可用	不要在消息页依赖路由感知

行为要点：

open 由主应用统一校验：空 URL 和可执行协议（javascript: 等）被拒绝；target 只能是 self 或 blank。

消息宿主的 back() 直接走浏览器历史。

notification.show 的 intent 支持 info|success|warning|error；durationMs 未传时用宿主默认时长。当前不消费 key 做同 key 覆盖，不要依赖。

可照抄示例

fh2-plugin.json（节选）：

{
  "permissions": ["platform:navigation", "platform:notification"],
  "extensions": [
    { "id": "dispatch-popup", "point": "message.alert-popups" }
  ]
}

// plugin.ts（节选）
export async function activateMessage (ctx) {
  const [navigation, notification] = await Promise.all([
    ctx.capabilities.get('platform:navigation'),
    ctx.capabilities.get('platform:notification'),
  ])

  async function openDispatchedFlight (input: {
    organizationId: string
    projectId: string
    droneSn: string
  }) {
    if (!navigation) throw new Error('当前页面不支持导航')
    const search = new URLSearchParams({
      drone_sn: input.droneSn,
      source: 'dispatch-popup',
    })
    const url = `/organization/${encodeURIComponent(input.organizationId)}`
      + `/project/${encodeURIComponent(input.projectId)}`
      + `/cockpit?${search.toString()}`

    await navigation.open(url, { target: 'blank' })
    await notification?.show({
      key: `dispatch-${input.droneSn}`,
      message: '已在新窗口打开驾驶舱',
      intent: 'success',
      durationMs: 3000,
    })
  }

  await dispatchCardView.handle(ctx, {
    state: dispatchState,
    methods: {
      openCockpit: openDispatchedFlight,
      back: async () => {
        if (navigation) await navigation.back()
      },
    },
  })
}

示例假定 dispatchCardView、dispatchState 已按界面契约定义（见界面与状态），清单中声明了对应界面资源。

注意事项

新窗口跳转应由用户点击触发，并处理浏览器拦截和调用失败。

导航可能直接卸载消息宿主：跳转后不要继续依赖当前页面或内存状态。

长时提示保存 show() 返回的句柄，状态变化时主动 dispose()。

拿不到导航能力时隐藏跳转入口；拿不到通知能力时改用界面内反馈，不阻断已成功的业务。

不要用 window.location 或宿主路由器绕过能力，也不要把缺失的位置能力当作路由判断来源。

常见问题

现象	原因与处理
新窗口没打开	非用户手势触发被浏览器拦截；改成点击回调里调用
跳转后代码报错	宿主可能已卸载；`open` 之后不再操作当前页面状态
提示一直不消失	保存句柄并在合适时机 `dispose()`
想读取当前路由	消息宿主没有 `platform:location`；改由插件后端或消息数据携带上下文

能力状态#

可照抄示例#

注意事项#

常见问题#

能力状态

可照抄示例

注意事项

常见问题