1. 消息宿主
插件化手册
  • FH2 插件开发手册
    • 产品简介
    • 典型场景
    • 发版说明
    • 快速开始
      • 快速开始总览
      • 第一个插件
      • 后端插件
      • 全栈闭环
    • AI辅助开发
      • AI 开发 Skill
      • 安装与复验
      • 第一个工程
      • 真实需求示例:现场问题上报
      • 改造已有工程
      • 调试与交付
    • 开发指南
      • 开发指南
      • 基础概念
        • 基础概念总览
        • 什么是插件开发
        • 平台架构
        • 前端宿主、扩展点与能力
        • 后端运行时、入口与权限
        • 开发流程
        • 安全与隔离
        • 支持范围与问题反馈
      • 开发指南
        • 开发指南总览
        • 前端插件
          • 前端插件深度指南
          • 前端工程结构
          • 插件清单(fh2-plugin.json)
          • 入口与生命周期
          • 界面与状态
          • 多宿主插件
          • 跨宿主通信服务
          • HTTP、WebSocket 与事件
          • 存储、Blob 与定时器
          • 工具链与本地调试页面
        • 后端插件
          • 后端开发深度指南
          • 后端插件的结构
          • 后端源清单 fh2-plugin.json
          • HTTP 接口处理函数
          • 消息订阅与事件处理函数
          • ctx 与能力注入
          • 数据存储与缓存
          • 流程编排
          • 触发方式
          • 连接外部系统
          • 流程编排练习(DAG)
        • 前后端协作
          • 前后端协作总览
          • 前后端共享契约
          • 端到端幂等
          • 事件、通知与状态
          • 统一错误模型
          • 链路标识与诊断日志
        • 完整练习
          • 环境准备
          • 第一个前端插件
          • 第一个后端插件
          • 第一个全栈插件
      • 能力总览
        • 能力地图
        • 能力可用性矩阵
        • 前端能力
          • 平台通用能力
            • 平台通用能力总览
            • 基础运行时:HTTP、事件、WebSocket 与存储
            • 导航、位置与通知
            • 弹窗、音频与剪贴板
            • 地图能力
            • 项目设备能力
            • WPMZ 与航线预览
            • 受控对象上传
          • 项目宿主
            • 项目宿主总览
            • 项目上下文
            • 项目侧边栏入口
            • 项目插件路由
            • 项目工作区
          • 消息宿主
            • 消息宿主总览
            • 消息告警弹层
            • 消息导航与通知
          • 计划库宿主
            • 计划库宿主总览
            • 计划库表单上下文
            • 计划库表单扩展
            • 校验、提交与 `biz_ext`
          • 驾驶舱
            • 驾驶舱插件能力总览
            • 驾驶舱扩展点
            • 上下文与遥测
            • 相机、检测与 AI
            • 场景几何与直播指针
            • 飞控、云台与任务
            • 驾驶舱平台事件
        • 后端能力
          • 后端能力地图
          • 后端能力总览
          • 配置、受管出网与集成连接
          • 事件与流程
          • 飞行任务与违停巡逻
          • 数据存储
          • 媒体与前端通知
          • 资源租约
          • 作业、目标轨迹与视频处理
      • 调试与测试
        • 调试与测试总览
        • 快速入门排错
        • 本地开发
        • Web IDE:打开工程与保存改动
        • 工作流编辑器:节点、接线与交付
        • 知识与 MCP:先判断需要哪一层事实
        • 前端本地调试
        • 后端运行时与流程调试
        • 模拟数据与测试数据
        • 集成测试与 E2E
        • 日志与链路追踪
        • 常见问题排查
      • 完整示例
        • 示例与案例总览
        • 项目侧边栏与工作区
        • 消息告警卡片
        • 计划表单任务清单
        • 驾驶舱动作与左侧面板
        • 最小后端插件
        • 最小全栈插件
        • 多宿主插件实战
        • 事故快处
        • 交通抓拍
        • 违停巡逻完整案例
      • 构建发布与安全
        • 构建、发布与安全
        • 质量门禁
        • 行业包构建与打包
        • 能力版本发布
        • 安装、升级与回滚
        • 安全基线
      • API参考
        • API 参考总览
        • 前端
          • 前端 API 参考
          • 前端插件清单结构
          • 前端 SDK API
          • 前端扩展点目录
          • 前端能力目录
          • 前端平台事件目录
          • 跨宿主通信服务 API
          • 工具链命令行参考(`fh2-plugin`)
        • 后端
          • 后端 API 参考
          • 后端插件源清单
          • 后端 HTTP 接口参考
          • 后端事件消费参考
          • 后端脚本上下文(`ctx`)
          • 后端数据存储
          • 流程编排语言
          • 流程触发器参考
          • 后端能力目录
          • 后端 HTTP API
        • 共享契约
          • 共享契约参考
          • 类型与契约目录
          • 错误模型
          • 版本兼容性
      • 附录
        • 错误码
        • 术语表
        • 常见问题
  1. 消息宿主

消息告警弹层

message.alert-popups 让插件在消息中心插入自己的告警卡片:高优先级、常驻、不自动折叠。典型用法是订阅业务消息,收到告警时把卡片亮出来。这是扩展点,在清单 extensions 里声明(不需要额外权限),运行时用 ctx.extensions.contribute() 提交。
fh2-plugin-sdk 是插件开发 SDK;下文模块名用于说明,实际导入路径保留生成工程配置。模块名不表示已发布的 npm 包名。

字段清单#

字段层说明
visible代码 state,默认 false是否显示卡片;false 关闭已显示的卡片
render()代码 method,必填返回卡片内容的界面
宿主行为:卡片按高优先级插入原生消息中心队列,不自动消失(duration: 0),内容宽 343 px、最大高度约一屏,超出部分内部滚动。多个插件的卡片可并存,排序由宿主决定,插件不能指定 z-index。

可照抄示例#

fh2-plugin.json:
{
  "id": "exp_weather_alert",
  "name": "天气告警",
  "version": "1.0.0",
  "entry": "./plugin.js",
  "permissions": ["platform:websocket", "platform:http"],
  "extensions": [
    {
      "id": "weather-popup",
      "point": "message.alert-popups"
    }
  ],
  "views": {
    "weather-card": { "entry": "./views/weather-card.js" }
  }
}
// plugin.ts
import {
  createViewState,
  definePlugin,
  definePluginView,
} from 'fh2-plugin-sdk'

interface WeatherCardContract {
  state: { alertId: string; title: string; detail: string }
  methods: {
    acknowledge(): void
    close(): void
  }
}
const weatherCard = definePluginView<WeatherCardContract>('weather-card')

export default definePlugin({
  async activate (ctx) {
    if (ctx.host.id !== 'message') return
    const state = createViewState<WeatherCardContract['state']>({
      alertId: '',
      title: '',
      detail: '',
    })
    let popup: {
      update(patch: { visible?: boolean }): Promise<void>
    } | undefined

    async function hide () {
      await popup?.update({ visible: false })
    }
    await weatherCard.handle(ctx, {
      state,
      methods: {
        async acknowledge () {
          // 处理回执由插件自己的后端接口完成
          const { alertId } = state.get()
          await ctx.apiCall(`/weather-alerts/${encodeURIComponent(alertId)}/ack`, {
            method: 'POST',
            body: { result: 'acknowledged' },
            idempotencyKey: `weather-ack-${alertId}`,
          })
          await hide()
        },
        close: hide,
      },
    })

    popup = await ctx.extensions.contribute('weather-popup', {
      visible: false,
      render: () => weatherCard.get(ctx),
    })
    const wsSubscription = await ctx.ws.onBizCode<{
      id: string
      title: string
      detail: string
    }>('weather_alert', async ({ data }) => {
      state.update(() => ({
        alertId: data.id,
        title: data.title,
        detail: data.detail,
      }))
      await popup?.update({ visible: true })
    })

    return {
      async dispose () {
        await hide()
        await wsSubscription.dispose()
      },
    }
  },
})

注意事项#

相同扩展不重复开卡:visible 从 false 切到 true 才创建卡片,重复置 true 不会开第二张。
用户手动关闭卡片后,扩展的 visible 可能仍是 true;业务要再次显示时,先显式置 false 再置 true。
宿主不会把消息内容传给 render();告警数据由入口代码通过界面状态提供(示例里是 WebSocket 订阅)。
消息宿主卸载时会先关闭所有插件卡片,再销毁页面。
更多完整示例见消息告警示例。

常见问题#

现象原因与处理
收到消息但没开卡确认已 contribute 且 visible 置了 true;重复置 true 不会重复开卡
用户关掉卡片后再也打不开手动关闭不会同步扩展状态;先 false 再 true
卡片内容太长被截断内容区超出最大高度会内部滚动;不需要滚动则压缩内容
回执失败保留卡片并显示可重试状态;回执只依赖你自己的后端接口
修改于 2026-10-22 07:06:54
上一页
消息宿主总览
下一页
消息导航与通知
Built with