# 组合与权限参考 实例、principals、manifests、facades 和 wrappers 的约定，含参数与分发差异。 版本、变更与要求见 [Framework 3.2 与 CLI 1.0](/zh-cn/docs/guides/releases/)。 本参考汇集宿主配置身份和权限的 API。示例使用从 `wu-framework` 导入的 `wu`；名为 `manifests` 的对象通过 `new WuManifest()` 创建。 ## 分发版本与调用对象 singleton 具有宿主权限。生命周期收到的 `context.wu` facade 只授予 manifest 申请与宿主 grants 的交集。principal 角色控制界面访问；服务器数据授权必须在服务器验证。 ## 为已注册应用准备 wrapper ```js import { wu, WuManifest } from 'wu-framework'; const manifests = new WuManifest(); await wu.init({ apps: [{ name: 'widget', url: '/apps/widget' }] }); const widget = wu.app('widget', { url: '/apps/widget', container: '#widget-slot', }); await widget.mount(); ``` 目标必须存在于文档中。wrapper 条目描述运行时方法；WuApp 的 TypeScript 声明只列出其中一部分。创建另一个 wrapper 不会替换现有注册的 grants。 ## wu.app 创建可复用对象，保存微应用的身份和配置。 `wu.app(name: string, config: Partial): WuApp` - name 和 config.url；container 接受字符串选择器，从 3.2 起也接受 HTMLElement。其他字段属于宿主。 - **返回：**延迟到 `mount()` 才注册的 WuApp。 - **错误：**挂载会传播 manifest、权限、加载和容器故障。 - **权限：**wrapper 保留 host 配置和 grants，并通过 core 注册。 - **清理：** unmount 移除 renderer；wrapper 的 destroy 不清理所有 manifest 注册。 ```js const catalog = wu.app('catalog', { url: '/apps/catalog', container: '#catalog-slot', }); console.log(catalog.info); ``` 参考：`src/index.js`. ## new WuCore 创建具有独立 store 或显式注入 store 的实例。 `new WuCore(options?): WuCore` - **参数：** store、storeBufferSize 和 compatibility 可选。 - **返回值：** 独立实例；导入的 wu 仍是 singleton。 - **错误：** 不启动应用；传播选项/compatibility 错误。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 移除实例时 await runtime.destroy()。 ```js import { WuCore, WuStore } from 'wu-framework'; const runtime = new WuCore({ store: new WuStore(512) }); ``` 参考：`src/core/wu-core.js`. ## wu.setPrincipal 设置挂载访问控制使用的 principal。 `wu.setPrincipal(principal | null): object | null` - **参数：** role、roles，以及 mount:catalog 或 mount:* 等 permissions；null 结束身份。 - **返回值：** 相同 principal 或 null；投影到 auth.principal 并报告变更。 - **错误：** store 写入失败不会回滚 principal。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 会话结束时调用 wu.setPrincipal(null)。 ```js wu.setPrincipal({ roles: ['catalog-reader'] }); ``` 参考：`src/core/wu-core.js`. ## wu.getPrincipal 读取宿主当前使用的 principal。 `wu.getPrincipal(): object | null` - **参数：** 无参数。 - **返回值：** principal 引用或 null。 - **错误：** 不验证会话，也不查询服务器。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 不创建需要释放的资源。 ```js console.log(wu.getPrincipal()?.roles); ``` 参考：`src/core/wu-core.js`. ## wu.can 检查 principal 是否满足应用角色要求。 `wu.can(appName: string): boolean` - **参数：** 注册名称；读取 manifest 规范化后的 roles。 - **返回值：** 布尔值；没有 roles 的应用视为公开。 - **错误：** 不检查入口是否存在，也不授予 store/bus capabilities。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 不创建需要释放的资源。 ```js if (wu.can('catalog')) await wu.mount('catalog', '#catalog-slot'); ``` 参考：`src/core/wu-core.js`. ## context.wu 为每个生命周期提供可撤销的应用权限。 `mount(container, context: { appName, wu: WuAppFacade }): void | Promise` - **参数：** context 由 core 提供；不能根据名称自行创建 facade。 - **返回值：** 冻结的 facade，包含事件、RPC、契约和受限 store。 - **错误：** teardown 后为 WU_APP_SCOPE_REVOKED；访问未获 grant 的资源时为 WU_CAPABILITY_DENIED。 - **权限：** manifest.wu.permissions 与 config.grants 的交集；不暴露 init、destroy 或全局管理。 - **清理：** 在 unmount 中释放自己的工作，之后不要复用 facade。 ```js wu.define('catalog', { mount(container, { wu: appWu }) { container.textContent = String(appWu.store.get('catalog.count') ?? 0); }, }); ``` 参考：`src/core/wu-core.js`. ## new WuManifest 创建具有独立缓存的 manifest 读取器和验证器。 `new WuManifest(): WuManifest` - **参数：** 无必填参数。 - **返回值：** 支持 load、validate、create 和 clearCache 的实例。 - **错误：** 不授予权限，也不在 core 注册应用。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** clearCache() 丢弃缓存的 manifests。 ```js import { WuManifest } from 'wu-framework'; const manifests = new WuManifest(); ``` 参考：`src/core/wu-manifest.js`. ## WuManifest.load 从应用基础 URL 下载并规范化 wu.json。 `manifests.load(appUrl, { expectedName? }?): Promise` - **参数：** appUrl：公开基础地址；expectedName 绑定注册身份。 - **返回值：** 规范化 manifest；真实 404 使用默认 manifest。 - **错误：** WU_MANIFEST_LOAD_FAILED、WU_MANIFEST_INVALID 和 WU_MANIFEST_NAME_MISMATCH；网络错误、HTML 或 500 不会触发默认值。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 需要丢弃读取结果时使用 clearCache(base)。 ```js const manifest = await manifests.load('/apps/catalog', { expectedName: 'catalog' }); ``` 参考：`src/core/wu-manifest.js`. ## WuManifest.validate 验证声明的结构、限制、路径和权限，但不授予权限。 `manifests.validate(manifest, { expectedName? }?): object` - **参数：** 自有数据对象；对象形式声明必须包含 resource。 - **返回值：** 包含冻结快照的规范化 manifest。 - **错误：** WU_MANIFEST_INVALID，或身份与 expectedName 不同。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 不创建需要释放的资源。 ```js const manifest = manifests.validate({ name: 'catalog', entry: 'entry.js', wu: { permissions: [] } }); ``` 参考：`src/core/wu-manifest.js`. ## WuManifest.create 根据身份和声明式配置生成 manifest。 `manifests.create(name, config?): object` - **参数：** name；config.entry（默认 index.js）、exports、imports、permissions、roles、metadata、styleMode、version 和 folder。wu.routes 不允许非空 routes。 - **返回值：** 已构造并验证的 manifest。 - **错误：** 与 validate 相同的结构限制。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 不创建需要释放的资源。 ```js const manifest = manifests.create('catalog', { entry: 'entry.js' }); ``` 参考：`src/core/wu-manifest.js`. ## WuManifest.clearCache 丢弃已存储 manifests，以便重新下载。 `manifests.clearCache(pattern?): void` - **参数：** 字符串形式的正则表达式；不提供模式则清空此实例全部缓存。 - **返回值：** void。 - **错误：** 无效 RegExp 模式会警告且不删除条目；不改变 core 已编译注册。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 不创建需要释放的资源。 ```js manifests.clearCache('/apps/catalog'); ``` 参考：`src/core/wu-manifest.js`. ## wu.compatibility.configure 配置 strict 与 compat-v2 配置档之间有限的迁移桥接。 `wu.compatibility.configure(config): WuCompatibility` - **参数：** profile、warnings 和 ai/plugins/apps/sync 选项；不是额外沙箱。 - **返回值：** 同一实例。 - **错误：** 未知配置或 feature 可能抛出。 - **权限：** 仅宿主；各桥接必须显式启用。 - **清理：** 不创建需要释放的资源。 ```js wu.compatibility.configure({ profile: 'strict', warnings: 'once' }); ``` 参考：`src/core/wu-compatibility.js`. ## wu.compatibility.getConfig 查询实际生效的配置档与迁移桥接。 `wu.compatibility.getConfig(): object` - **参数：** 无参数。 - **返回值：** 兼容性配置。 - **错误：** 不能证明某个消费者正在使用桥接。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 不创建需要释放的资源。 ```js console.log(wu.compatibility.getConfig()); ``` 参考：`src/core/wu-compatibility.js`. ## wu.compatibility.getMigrationReport 读取累积的兼容性使用警告。 `wu.compatibility.getMigrationReport(): object[]` - **参数：** 无参数。 - **返回值：** 包含代码、消息、计数和时间的条目。 - **错误：** 只记录已埋点的使用，不是应用静态分析。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 不创建需要释放的资源。 ```js console.table(wu.compatibility.getMigrationReport()); ``` 参考：`src/core/wu-compatibility.js`. ## wu.compatibility.clearMigrationReport 重置迁移警告记录。 `wu.compatibility.clearMigrationReport(): void` - **参数：** 无参数。 - **返回值：** void。 - **错误：** 不更改兼容性选项。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 不创建需要释放的资源。 ```js wu.compatibility.clearMigrationReport(); ``` 参考：`src/core/wu-compatibility.js`. ## WuApp.mount 挂载 wrapper 的身份，并记住选择器。 `widget.mount(target?: string | HTMLElement): Promise` - **参数：** 可选选择器；省略时使用 config.container。 - **返回值：** Promise - **错误：** 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。 - **权限：** wrapper 所属 core 的权限。 - **清理：** 配对调用 widget.unmount()。 ```js await widget.mount('#widget-slot'); ``` 参考：`src/core/wu-app.js`. ## WuApp.unmount 释放 wrapper 引用，或保留 keep-alive。 `widget.unmount(options?: { force?: boolean; keepAlive?: boolean }): Promise` - **参数：** force 完全移除；keepAlive 保留 DOM。 - **返回值：** Promise - **错误：** 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。 - **权限：** wrapper 所属 core 的权限。 - **清理：** 适用时调用 renderer 的 unmount。 ```js await widget.unmount({ force: true }); ``` 参考：`src/core/wu-app.js`. ## WuApp.hide 隐藏 wrapper 保留的实例。 `widget.hide(): Promise` - **参数：** 无参数；需要已挂载实例。 - **返回值：** Promise - **错误：** 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。 - **权限：** wrapper 所属 core 的权限。 - **清理：** deactivate 应暂停自身 timers。 ```js await widget.hide(); ``` 参考：`src/core/wu-app.js`. ## WuApp.show 重新激活 wrapper 的 keep-alive 实例。 `widget.show(): Promise` - **参数：** 无参数；需要隐藏状态。 - **返回值：** Promise - **错误：** 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。 - **权限：** wrapper 所属 core 的权限。 - **清理：** 最后仍需 unmount。 ```js await widget.show(); ``` 参考：`src/core/wu-app.js`. ## WuApp.remount 强制卸载，并在所选目标重新挂载。 `widget.remount(target?: string | HTMLElement): Promise` - **参数：** 可选选择器；保留上次目标。 - **返回值：** Promise - **错误：** 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。 - **权限：** wrapper 所属 core 的权限。 - **清理：** 销毁前一个 renderer。 ```js await widget.remount('#widget-slot'); ``` 参考：`src/core/wu-app.js`. ## WuApp.reload 清空可用的 loader/manifest 缓存并重新挂载。 `widget.reload(): Promise` - **参数：** 无参数；使用记住的目标。 - **返回值：** Promise - **错误：** 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。 - **权限：** wrapper 所属 core 的权限。 - **清理：** 不使浏览器原生 ESM import 缓存失效。 ```js await widget.reload(); ``` 参考：`src/core/wu-app.js`. ## WuApp.verify 检查 slot 的注册、挂载和 ShadowRoot。 `widget.verify(): Promise` - **参数：** 无参数；hasContent 统计 ShadowRoot 子节点。 - **返回值：** Promise - **错误：** 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。 - **权限：** wrapper 所属 core 的权限。 - **清理：** 只读操作；不能保证 light DOM renderer 有内容。 ```js console.log(await widget.verify()); ``` 参考：`src/core/wu-app.js`. ## WuApp.destroy 卸载并从公开应用映射中删除名称。 `widget.destroy(): Promise` - **参数：** 无参数。 - **返回值：** Promise - **错误：** 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。 - **权限：** wrapper 所属 core 的权限。 - **清理：** 不删除所有 manifest 注册；不能作为通用身份替换机制。 ```js await widget.destroy(); ``` 参考：`src/core/wu-app.js`. ## WuApp.info / isMounted / isHidden 查询 wrapper 的身份、选择器和状态。 `widget.info; widget.isMounted; widget.isHidden` - **参数：** 它们是 getters，不是函数。 - **返回值：** info 为对象；isMounted/isHidden 为状态值。 - **错误：** 不能替代 renderer 内容检查。 - **权限：** 仅宿主；应用 facade 不提供。 - **清理：** 不创建需要释放的资源。 ```js console.log(widget.info, widget.isMounted, widget.isHidden); ``` 参考：`src/core/wu-app.js`. 参阅[监督、恢复与 replay](/zh-cn/docs/framework/runtime-reliability/)，了解 `superviseApp`、`createReplaySession` 和 scoped 方法 `reportError`、`now`、`random`。 首个 provider 拥有合同名称。在所有者撤销合同或卸载之前，其他应用或尝试替换应用合同的 host 会收到 `WU_CAPABILITY_OWNED`。同一所有者可替换其实现。当存在 `shape` 时，远程 ports 仅暴露其中声明的方法。