组合与权限参考

版本、变更与要求见 Framework 3.2 与 CLI 1.0。

本参考汇集宿主配置身份和权限的 API。示例使用从 wu-framework 导入的 wu；名为 manifests 的对象通过 new WuManifest() 创建。

分发版本与调用对象

singleton 具有宿主权限。生命周期收到的 context.wu facade 只授予 manifest 申请与宿主 grants 的交集。principal 角色控制界面访问；服务器数据授权必须在服务器验证。

为已注册应用准备 wrapper

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<WuAppConfig>): WuApp

• name 和 config.url；container 接受字符串选择器，从 3.2 起也接受 HTMLElement。其他字段属于宿主。
• **返回：**延迟到 mount() 才注册的 WuApp。
• **错误：**挂载会传播 manifest、权限、加载和容器故障。
• **权限：**wrapper 保留 host 配置和 grants，并通过 core 注册。
• 清理： unmount 移除 renderer；wrapper 的 destroy 不清理所有 manifest 注册。

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()。

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)。

wu.setPrincipal({ roles: ['catalog-reader'] });

参考：src/core/wu-core.js.

wu.getPrincipal

读取宿主当前使用的 principal。

wu.getPrincipal(): object | null

• 参数： 无参数。
• 返回值： principal 引用或 null。
• 错误： 不验证会话，也不查询服务器。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 不创建需要释放的资源。

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 不提供。
• 清理： 不创建需要释放的资源。

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<void>

• 参数： context 由 core 提供；不能根据名称自行创建 facade。
• 返回值： 冻结的 facade，包含事件、RPC、契约和受限 store。
• 错误： teardown 后为 WU_APP_SCOPE_REVOKED；访问未获 grant 的资源时为 WU_CAPABILITY_DENIED。
• 权限： manifest.wu.permissions 与 config.grants 的交集；不暴露 init、destroy 或全局管理。
• 清理： 在 unmount 中释放自己的工作，之后不要复用 facade。

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。

import { WuManifest } from 'wu-framework';
const manifests = new WuManifest();

参考：src/core/wu-manifest.js.

WuManifest.load

从应用基础 URL 下载并规范化 wu.json。

manifests.load(appUrl, { expectedName? }?): Promise<object>

• 参数： appUrl：公开基础地址；expectedName 绑定注册身份。
• 返回值： 规范化 manifest；真实 404 使用默认 manifest。
• 错误： WU_MANIFEST_LOAD_FAILED、WU_MANIFEST_INVALID 和 WU_MANIFEST_NAME_MISMATCH；网络错误、HTML 或 500 不会触发默认值。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 需要丢弃读取结果时使用 clearCache(base)。

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 不提供。
• 清理： 不创建需要释放的资源。

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 不提供。
• 清理： 不创建需要释放的资源。

const manifest = manifests.create('catalog', { entry: 'entry.js' });

参考：src/core/wu-manifest.js.

WuManifest.clearCache

丢弃已存储 manifests，以便重新下载。

manifests.clearCache(pattern?): void

• 参数： 字符串形式的正则表达式；不提供模式则清空此实例全部缓存。
• 返回值： void。
• 错误： 无效 RegExp 模式会警告且不删除条目；不改变 core 已编译注册。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 不创建需要释放的资源。

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 可能抛出。
• 权限： 仅宿主；各桥接必须显式启用。
• 清理： 不创建需要释放的资源。

wu.compatibility.configure({ profile: 'strict', warnings: 'once' });

参考：src/core/wu-compatibility.js.

wu.compatibility.getConfig

查询实际生效的配置档与迁移桥接。

wu.compatibility.getConfig(): object

• 参数： 无参数。
• 返回值： 兼容性配置。
• 错误： 不能证明某个消费者正在使用桥接。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 不创建需要释放的资源。

console.log(wu.compatibility.getConfig());

参考：src/core/wu-compatibility.js.

wu.compatibility.getMigrationReport

读取累积的兼容性使用警告。

wu.compatibility.getMigrationReport(): object[]

• 参数： 无参数。
• 返回值： 包含代码、消息、计数和时间的条目。
• 错误： 只记录已埋点的使用，不是应用静态分析。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 不创建需要释放的资源。

console.table(wu.compatibility.getMigrationReport());

参考：src/core/wu-compatibility.js.

wu.compatibility.clearMigrationReport

重置迁移警告记录。

wu.compatibility.clearMigrationReport(): void

• 参数： 无参数。
• 返回值： void。
• 错误： 不更改兼容性选项。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 不创建需要释放的资源。

wu.compatibility.clearMigrationReport();

参考：src/core/wu-compatibility.js.

WuApp.mount

挂载 wrapper 的身份，并记住选择器。

widget.mount(target?: string | HTMLElement): Promise<WuApp>

• 参数： 可选选择器；省略时使用 config.container。
• 返回值： Promise
• 错误： 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。
• 权限： wrapper 所属 core 的权限。
• 清理： 配对调用 widget.unmount()。

await widget.mount('#widget-slot');

参考：src/core/wu-app.js.

WuApp.unmount

释放 wrapper 引用，或保留 keep-alive。

widget.unmount(options?: { force?: boolean; keepAlive?: boolean }): Promise<WuApp>

• 参数： force 完全移除；keepAlive 保留 DOM。
• 返回值： Promise
• 错误： 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。
• 权限： wrapper 所属 core 的权限。
• 清理： 适用时调用 renderer 的 unmount。

await widget.unmount({ force: true });

参考：src/core/wu-app.js.

WuApp.hide

隐藏 wrapper 保留的实例。

widget.hide(): Promise<WuApp>

• 参数： 无参数；需要已挂载实例。
• 返回值： Promise
• 错误： 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。
• 权限： wrapper 所属 core 的权限。
• 清理： deactivate 应暂停自身 timers。

await widget.hide();

参考：src/core/wu-app.js.

WuApp.show

重新激活 wrapper 的 keep-alive 实例。

widget.show(): Promise<WuApp>

• 参数： 无参数；需要隐藏状态。
• 返回值： Promise
• 错误： 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。
• 权限： wrapper 所属 core 的权限。
• 清理： 最后仍需 unmount。

await widget.show();

参考：src/core/wu-app.js.

WuApp.remount

强制卸载，并在所选目标重新挂载。

widget.remount(target?: string | HTMLElement): Promise<WuApp>

• 参数： 可选选择器；保留上次目标。
• 返回值： Promise
• 错误： 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。
• 权限： wrapper 所属 core 的权限。
• 清理： 销毁前一个 renderer。

await widget.remount('#widget-slot');

参考：src/core/wu-app.js.

WuApp.reload

清空可用的 loader/manifest 缓存并重新挂载。

widget.reload(): Promise<WuApp>

• 参数： 无参数；使用记住的目标。
• 返回值： Promise
• 错误： 传播注册/挂载失败；缺少可见性方法时警告，不执行挂载。
• 权限： wrapper 所属 core 的权限。
• 清理： 不使浏览器原生 ESM import 缓存失效。

await widget.reload();

参考：src/core/wu-app.js.

WuApp.verify

检查 slot 的注册、挂载和 ShadowRoot。

widget.verify(): Promise<object>

• 参数： 无参数；hasContent 统计 ShadowRoot 子节点。
• 返回值： Promise