界面与状态

插件的可视部分叫界面：一个独立的 Vue 3 bundle，负责画 UI 和响应用户操作。这一页讲界面怎么声明、怎么和入口代码交换状态、怎么挂载和清理。核心结论先记住：界面拿不到 ctx（上下文对象），它需要的一切数据都通过界面契约向入口要。

前置条件

清单 views 里已声明界面 ID 和 ./views/<id>.js 入口（见插件清单）。

入口代码能拿到对应宿主的生成类型。

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

三件套的结构

每个界面在 src/views/<view-id>/ 下有三个文件，职责固定：

src/views/counter-panel/
├── contract.ts   # 契约：状态形状 + 方法签名，入口和界面都 import 它
├── index.ts      # 默认导出 defineView(...)，宿主加载的入口
├── mount.ts      # mount 函数：建订阅、挂 Vue、返回 dispose
└── Panel.vue     # 纯 UI 组件

第一步：定义契约

契约是入口与界面之间的通信通道的"说明书"：

// src/views/counter-panel/contract.ts —— 入口和界面都 import 这个文件
import { definePluginView } from 'fh2-plugin-sdk'

export interface CounterState {
  readonly count: number
}

interface CounterContract {
  state: CounterState
  methods: {
    increment: () => CounterState
  }
}

export const counterView = definePluginView<CounterContract>('counter-panel')

契约的类型约束：

state 和方法参数、返回值必须能跨边界传输（可序列化的普通值，加上 Blob、Date、Map 等少数类型）。函数、DOM 节点、Vue 响应式对象都不行。

每个方法最多一个参数。

方法名不能用保留名：state、dispose、then、catch、finally、constructor、prototype、__proto__。

第二步：入口提供状态和方法

状态由入口持有，用 createViewState 创建：

// src/hosts/cockpit/activate.ts（节选）
import { createViewState } from 'fh2-plugin-sdk'
import { counterView } from '../../views/counter-panel/contract'
import type { CounterState } from '../../views/counter-panel/contract'

const state = createViewState<CounterState>({ count: 0 })

await counterView.handle(ctx, {
  state, // 要求有 subscribe 方法；createViewState 直接满足
  methods: {
    increment: () => {
      state.update(current => ({ count: current.count + 1 }))
      return state.get()
    },
  },
})

createViewState 返回四个方法：

方法	作用
`get()`	读当前值
`update(fn)`	传 `current => 新值`；`fn` 返回新对象（不可变更新）。返回原对象时不会通知订阅者
`map(fn)`	把完整状态映射成某个界面需要的形状
`subscribe(fn)`	订阅；注册时会立即收到一次当前值

第三步：界面挂载

界面的默认导出必须是 defineView(...) 返回的函数，宿主加载 bundle 后调用它的 mount：

// src/views/counter-panel/index.ts
export { default } from './mount'

// src/views/counter-panel/mount.ts
import { createApp, reactive } from 'vue'
import { defineView } from 'fh2-plugin-sdk'
import CounterPanel from './Panel.vue'
import { counterView } from './contract'

export default defineView({
  mount (ctx) {
    // ctx 里有：viewId、mountElement、styleTarget、overlayElement、port、locale、direction、theme
    const state = reactive({ count: 0 })

    // 通过 port 连回入口；方法调用全部返回 Promise
    const client = counterView.client(ctx.port)
    const subscription = client.state.subscribe(next => { state.count = next.count })

    const app = createApp(CounterPanel, {
      state,
      onIncrement: () => client.increment(),
    })
    app.mount(ctx.mountElement)

    return {
      dispose () {
        subscription.dispose()
        client.dispose()
        app.unmount()
      },
    }
  },
})

打开界面时，client.state.subscribe 会先收到一次最新状态，所以界面不会闪空白。关闭时 dispose 负责停订阅、断通道、卸 Vue 应用。

两个容易踩的 DOM 规则

浮层组件（Modal、Select 下拉、Teleport）挂到 ctx.overlayElement，不要挂 document.body。它是平台准备的浮层容器，会随界面一起清理。

CSS-in-JS 挂到 ctx.styleTarget。界面的 DOM 容器由宿主根据运行条件决定，styleTarget 指向当前界面正确的样式容器。

需要区分实例时：initialState

同一个界面 ID 有时需要按"内容身份"区分实例（比如两个不同任务的详情面板）。做法：在契约类型里加 initialState 字段（值必须是 JSON 安全的），入口用 counterView.get(ctx, initialState) 生成带身份的界面句柄。身份相同会复用已打开的界面，身份不同会重新挂载。

日常命令与预期

预期：构建后每个界面是 dist/views/ 下的独立 bundle；界面打开立即显示最新状态；关闭后订阅、通道、Vue 应用全部释放。

常见问题

现象	原因与处理
界面一片空白	三处 ID 要一致：清单 `views` 的键、`definePluginView('...')` 的参数、默认导出是否为 `defineView(...)` 的函数
报 `VIEW_LOAD_FAILED`	默认导出不是函数。`defineView({ mount ... })` 的返回值才是默认导出
点了按钮界面没反应	入口忘了先 `counterView.handle(ctx, ...)` 再提交扩展；或方法名两边不一致
状态变了但界面不更新	`update` 里返回了原对象（就地修改），平台按相同值跳过通知；改成返回新对象
跨边界方法调用报 `PLUGIN_VALUE_INVALID`	契约里传了函数、DOM、Vue 响应式对象或能力句柄；改成只传满足 `PluginValue` 的数据
弹层被裁剪或关闭界面后残影残留	浮层挂到了 `document.body`；改挂 `ctx.overlayElement`

前置条件#

三件套的结构#

第一步：定义契约#

第二步：入口提供状态和方法#

第三步：界面挂载#

两个容易踩的 DOM 规则#

需要区分实例时：initialState#

日常命令与预期#

常见问题#