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. 前端插件

前端工程结构

这一页讲插件工程里每个目录放什么、哪些文件是工具生成的、代码依赖只能朝哪个方向走。新建工程后对照这页看一遍,后面就不会把文件放错位置。

前置条件#

已用 fh2-plugin create 创建工程(模板选 frontend-basic,或使用能力工程 capability-fullstack 中的前端插件)。
依赖已安装,项目根目录有 fh2-plugin.json 和 rsbuild.config.ts。
SDK 与工具链的环境要求见环境准备。

推荐布局#

exp_example/
├── fh2-plugin.json                # 插件清单(你维护)
├── package.json
├── rsbuild.config.ts
├── public/                        # 图标等静态资源(可选)
├── src/
│   ├── plugin.ts                  # 唯一入口代码
│   ├── generated/
│   │   └── plugin-types.ts        # generate 生成,不要手改
│   ├── hosts/
│   │   └── <host>/activate.ts     # 每个宿主页面一份激活逻辑
│   ├── shared/                    # 数据结构、纯函数、请求封装(跨宿主复用)
│   └── views/
│       └── <view-id>/
│           ├── contract.ts        # 界面契约(入口和界面共用)
│           ├── index.ts           # 默认导出 defineView(...)
│           ├── mount.ts           # 挂载/卸载逻辑
│           └── Panel.vue          # Vue 组件
└── dist/                          # build 生成,不要手改
如果用的是默认的能力工程模板(capability-fullstack),工作区根会多出 packages.json,插件分属 <capabilityId>/frontend/<插件ID>/ 和 <capabilityId>/backend/<插件ID>/,能力目录里还有 capabilities.json 和 mock/。每个插件内部的结构与上图相同。

依赖方向#

一个方向,不能反:
src/plugin.ts(入口)
   └─> src/hosts/<host>/activate.ts
          └─> src/shared/  +  src/views/<id>/contract.ts

src/views/<id>/(界面)
   └─> Vue 组件 + contract.ts + UI 库
两条硬规则:
界面代码只依赖 Vue、契约和 UI 库,不导入宿主激活逻辑。挂载函数收到界面挂载上下文,不接收入口的 PluginContext 或能力注册表。
入口代码不导入 Vue、.vue 文件或界面的 mount 文件。Vue 相关的东西只能放 src/views/。
为什么这样分:入口与界面通过类型化通道传数据,避免把业务权限与 UI 依赖混在一起。界面自带 Vue 3,在宿主同一 JavaScript 运行域执行,ShadowRoot 只隔离 UI/CSS,不是 JavaScript 沙箱;不接收 PluginContext 不等于无法访问浏览器网络。入口安装网络护栏,界面不安装,作者应把业务网络与能力调用留在入口,不通过界面绕过受管通道或修改宿主 DOM / 全局状态。安全边界是安装审核与代码审核(见平台架构)。构建会检查入口与界面的依赖边界,但不是浏览器安全隔离。

构建配置#

模板已生成 rsbuild.config.ts,一般不需要改。下面只说明配置结构,不要按示意模块名改写生成文件的导入路径:
fh2-plugin-toolchain 是插件开发工具链;下文模块名用于说明,实际导入路径保留生成工程配置。模块名不表示已发布的 npm 包名。
// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { pluginVue } from '@rsbuild/plugin-vue'
import { fh2Plugin } from 'fh2-plugin-toolchain/rsbuild'

export default defineConfig({
  plugins: [
    pluginVue(),
    fh2Plugin({
      manifestPath: './fh2-plugin.json',
      pluginEntry: './src/plugin.ts',
      typesOutDir: './src/generated',
      validateOnBuild: true,
    }),
  ],
  output: { distPath: { root: 'dist' } },
})
注意:必须用 fh2-plugin build 构建,不能直接跑 rsbuild build。fh2Plugin() 会拒绝脱离工具链的构建,因为清单改写、入口产物这些步骤由工具链负责。

谁维护哪个文件#

路径谁生成规则
fh2-plugin.json你只写源清单允许的字段,见插件清单
src/**你业务代码都在这里
src/generated/plugin-types.tsfh2-plugin generate改清单后重新生成;不要手改
dist/fh2-plugin.jsonfh2-plugin build含 hash 路径和构建字段
dist/plugin.*.jsfh2-plugin build入口产物(单个 ESM 文件)
dist/views/*fh2-plugin build每个界面一个独立 bundle 和配套 CSS
业务代码只从 src/ 和依赖包导入,永远不要从 dist/ 导入。

日常命令与预期#

预期:dist/ 只在构建成功后才更新;入口是单个 ESM 文件;每个界面按界面 ID 独立打包。generate --check 失败就跑一次 generate;构建报"入口包含 Vue"就把相关依赖挪进 src/views/。

常见问题#

现象原因与处理
直接 rsbuild build 被拒绝必须经 fh2-plugin build,构建上下文由工具链提供
构建报"入口包含 Vue"Vue 组件、样式只能放 src/views/,入口代码不要 import 它们
改了清单但类型没变化重新跑 pnpm run generate;src/generated/ 不会自动更新
generate --check 一直失败说明类型文件与清单不同步,跑一次 pnpm run generate 覆盖旧文件
引用了 dist/ 里的文件业务代码只能从 src/ 和依赖包导入;dist/ 是产物不是源码
能力工程里找不到后端产物后端插件在 <capabilityId>/backend/<插件ID>/ 下独立构建,产物在其自身 dist/;纯前端插件没有后端目录也能正常构建
修改于 2026-10-22 03:39:49
上一页
前端插件深度指南
下一页
插件清单(fh2-plugin.json)
Built with