API 参考18 分钟阅读 · MARKDOWN ↗

加载、缓存与诊断参考

动态加载、优先级、overrides、缓存、样式和运行时观察。

选择加载层级

完整生命周期使用 wu.mount。wu.prefetch 提前请求已注册应用资源，wu.use 加载通过 exports 发布的组件。WuLoader 是独立加载器，不替代 core 的目录、sandbox 或 grants。

Overrides 和检查工具属于宿主。指标衡量观察到的某段过程，不保证浏览器已完成绘制。完整流程请参阅应用加载和诊断。

wu.use

加载另一应用声明的组件 export。

wu.use("app.component"): Promise<unknown>

参数： 精确名称 app.component；提供方 manifest 必须声明 wu.exports。
返回值： 存在时为 default export，否则为模块 namespace。
错误： 应用/export 缺失、目录穿越、无效 URL 或导入失败会拒绝。
权限： 宿主；加载组件在消费方 realm 内执行代码。
清理： 使用组件的 renderer 实例负责管理 cleanup。

const ProductCard = await wu.use('catalog.ProductCard');

运行时存在此方法，但 WuCore 声明缺失。它不会在不同框架之间转换组件。

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

wu.prefetchAll

请求预加载全部已注册应用。

wu.prefetchAll(options?): Promise<void> | (() => void)

参数： 与 prefetch 相同的触发选项。
返回值： 即时 Promise 或延迟触发器 cleanup。
错误： 预加载是向浏览器发出请求，不确认 renderer 能挂载。
权限： 宿主 API，scoped facade 不暴露。
清理： 选择延迟触发器时保存 cleanup。

await wu.prefetchAll({ on: 'immediate' });

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

new WuLoader

创建具备缓存和进行中请求去重的代码与组件 loader。

new WuLoader({ maxCacheSize?, cacheTTL? }?): WuLoader

参数： maxCacheSize 限制条目数量，默认 50；cacheTTL 单位毫秒，默认 1800000。
返回值： 包含 loadApp、loadComponent、preload、isAvailable 和 clearCache 的实例。
错误： 创建不会注册应用或执行生命周期。
权限： 宿主 API，scoped facade 不暴露。
清理： loader.clearCache() 释放缓存条目。

import { WuLoader } from 'wu-framework';
const loader = new WuLoader({ maxCacheSize: 20, cacheTTL: 60000 });

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

WuLoader.loadApp

下载入口代码文本，供加载流程使用。

loader.loadApp(appUrl, manifest?): Promise<string>

参数： 基础 URL 和带可选 entry 的 manifest。
返回值： 代码字符串；不执行 mount，也不注册应用。
错误： Fetch 失败、无效响应或 entry 解析失败会拒绝。
权限： 宿主，受环境网络访问限制。
清理： clearCache(base) 丢弃供后续读取复用的缓存。

const code = await loader.loadApp('/apps/catalog', { entry: 'entry.js' });

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

WuLoader.loadComponent

导入限制在应用基础目录内的组件。

loader.loadComponent(appUrl, componentPath): Promise<unknown>

参数： 基础地址和组件相对路径；不允许绝对 URL 或目录穿越。
返回值： default export 或导入 namespace。
错误： 路径超出基础目录或导入失败时拒绝。
权限： 模块在同一上下文执行代码，不是 scoped RPC。
清理： 原生 import 保留模块缓存。

const card = await loader.loadComponent('/apps/catalog', 'components/card.js');

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

WuLoader.preload

为应用列表提前下载代码。

loader.preload(appConfigs: WuAppConfig[]): Promise<void>

参数： 包含 name 和 url 的配置数组。
返回值： 预加载遍历完成的 Promise。
错误： 预加载逐个捕获应用失败；挂载前检查可用性。
权限： 宿主 API，scoped facade 不暴露。
清理： 不挂载 renderers；clearCache 释放缓存文本。

await loader.preload([{ name: 'catalog', url: '/apps/catalog' }]);

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

WuLoader.isAvailable

查询 URL 是否正确响应 HEAD。

loader.isAvailable(url): Promise<boolean>

参数： 待检查 URL。
返回值： 布尔值，网络错误转换为 false。
错误： 服务器拒绝 HEAD 时，即使 GET 可用也可能返回 false。
权限： 宿主网络访问。
清理： 不创建订阅或持久进程。

const available = await loader.isAvailable('/apps/catalog/entry.js');

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

WuLoader.clearCache

丢弃 loader 缓存的文本和记录。

loader.clearCache(pattern?): void

参数： 可选模式；无模式时清空 loader 缓存。
返回值： void。
错误： 不使浏览器 ESM 缓存失效。
权限： 宿主 API，scoped facade 不暴露。
清理： 不创建订阅或持久进程。

loader.clearCache('catalog');

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

WuLoader.getStats

查询 loader 缓存和进行中的 imports。

loader.getStats(): object

参数： 无参数。
返回值： 指标对象。
错误： 不代表应用挂载状态。
权限： 宿主 API，scoped facade 不暴露。
清理： 不创建订阅或持久进程。

console.log(loader.getStats());

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

wu.override

配置开发用 URL 替换。

wu.override(name, url, options?): void

参数： name 和已授权 URL；options.maxAge/path 配置 override 持久化。
返回值： void
错误： 系统验证域名和配置；override 不会自动 remount。
权限： 宿主 API，scoped facade 不暴露。
清理： 共享会话前移除开发 overrides。

wu.override('catalog', 'http://localhost:4101');

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

wu.removeOverride

移除 URL 替换。

wu.removeOverride(name): void

参数： 精确应用名称。
返回值： void
错误： 系统验证域名和配置；override 不会自动 remount。
权限： 宿主 API，scoped facade 不暴露。
清理： 共享会话前移除开发 overrides。

wu.removeOverride('catalog');

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

wu.getOverrides

查询活动 URL 替换。

wu.getOverrides(): Record<string,string>

参数： 无参数。
返回值： Record<string,string>
错误： 系统验证域名和配置；override 不会自动 remount。
权限： 宿主 API，scoped facade 不暴露。
清理： 共享会话前移除开发 overrides。

console.log(wu.getOverrides());

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

wu.clearOverrides

移除全部活动替换。

wu.clearOverrides(): void

参数： 无参数。
返回值： void
错误： 系统验证域名和配置；override 不会自动 remount。
权限： 宿主 API，scoped facade 不暴露。
清理： 共享会话前移除开发 overrides。

wu.clearOverrides();

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

normalizeStyleMode

规范化样式配置别名。

normalizeStyleMode(mode): string | undefined

参数： 模式字符串或 undefined。
返回值： none→isolated；own-only→fully-isolated；其他值不验证直接传递。
错误： 本身不验证 manifest 是否允许该模式。
权限： 纯函数，不授予权限。
清理： 不创建订阅或持久进程。

import { normalizeStyleMode } from 'wu-framework';
console.log(normalizeStyleMode('own-only'));

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

resolveDomOwnership

解析显式所有权及 nativeShadow/framework 别名。

resolveDomOwnership(options?): "wu" | "app" | "light"

参数： domOwnership 优先，其次 nativeShadow；Lit 默认选择 app。
返回值： 实际生效的所有权。
错误： 不创建 Shadow DOM，也不验证 renderer 是否实现其边界。
权限： 配置函数，不是安全控制。
清理： 不创建订阅或持久进程。

import { resolveDomOwnership } from 'wu-framework';
console.log(resolveDomOwnership({ framework: 'lit' }));

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

wu.tagStyleAsApp

为 CSS bridge 将 style/link 样式表归属到应用。

wu.tagStyleAsApp(element, appName): void

参数： style/link 元素和应用名称。
返回值： void。
错误： 归属标记不能替代 manifest 的 styleMode。
权限： 宿主 API，scoped facade 不暴露。
清理： 所属者结束时移除样式表。

const style = document.createElement('style');
style.textContent = ':host { color: var(--accent); }';
wu.tagStyleAsApp(style, 'catalog');
document.head.append(style);

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

new WuCache

创建带 TTL 和可选存储的 LRU 缓存。

new WuCache(options?): WuCache

参数： maxSize 单位 MB；maxItems；TTL 单位 ms；persistent，以及 memory/localStorage/sessionStorage 类型的 storage。
返回值： 缓存实例。
错误： 条目过大或操作限额可能阻止存储。
权限： 宿主；不要用持久存储作为授权。
清理： cache.clear() 释放条目和持久 namespace。

import { WuCache } from 'wu-framework';
const cache = new WuCache({ maxSize: 2, maxItems: 20, defaultTTL: 60000, storage: 'memory' });

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

WuCache.get

读取未过期条目并更新 LRU 顺序。

cache.get(key): unknown | null

参数： 条目键。
返回值： 保存值；缺失、过期或 rate limit 时为 null。
错误： null 无法区分 miss、过期或 cooldown，请查看指标。
权限： 访问所属缓存，不应用 store grants。
清理： 不创建订阅或持久进程。

const result = cache.get('catalog-result');

内存读取返回保存的引用，不像 WuStore 那样返回独立快照。

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

WuCache.set

保存值并应用空间和过期限制。

cache.set(key, value, ttl?): boolean

参数： 键、值及毫秒 TTL；由于使用 ||，ttl=0 会采用 defaultTTL。
返回值： 存储成功为 true；大小、错误或 rate limit 导致 false。
错误： 捕获失败并返回 false；storage 配额可能限制持久化。
权限： 宿主；验证要持久保存的数据。
清理： delete(key) 移除一条，clear() 移除全部。

const cached = cache.set('catalog-result', { count: 12 }, 30000);

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

WuCache.delete

从内存及配置的后端存储删除条目。

cache.delete(key): void

参数： 精确键。
返回值： void
错误： 持久化取决于 storage 可用性和配额。
权限： 缓存所属者的权限。
清理： 不创建订阅或持久进程。

cache.delete('catalog-result');

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

WuCache.clear

清空此实例缓存及配置的存储。

cache.clear(): void

参数： 无参数。
返回值： void
错误： 持久化取决于 storage 可用性和配额。
权限： 缓存所属者的权限。
清理： 不创建订阅或持久进程。

cache.clear();

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

WuCache.getStats

查询 hits、misses、evictions、大小和 rate limiting。

cache.getStats(): object

参数： 无参数。
返回值： object
错误： 持久化取决于 storage 可用性和配额。
权限： 缓存所属者的权限。
清理： 不创建订阅或持久进程。

console.log(cache.getStats());

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

WuCache.getRateLimitStatus

查询操作是否处于 cooldown 及其配额。

cache.getRateLimitStatus(): object

参数： 无参数。
返回值： object
错误： 持久化取决于 storage 可用性和配额。
权限： 缓存所属者的权限。
清理： 不创建订阅或持久进程。

console.log(cache.getRateLimitStatus());

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

wu.getStats

汇总 core 各子系统状态和指标。

wu.getStats(): object

参数： 无参数。
返回值： 诊断对象。
错误： 不替代挂载测试或 HTTP 检查。
权限： 宿主 API，scoped facade 不暴露。
清理： 不创建订阅或持久进程。

console.log(wu.getStats());

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

wu.getManifestDiagnostics

读取应用间声明式依赖错误。

wu.getManifestDiagnostics(): WuManifestImportDiagnostic[]

参数： 无参数；依赖 imports preflight。
返回值： 按消费者/import/提供方组织的诊断列表。
错误： 不自动检查 bundle 全部传递 imports。
权限： 宿主 API，scoped facade 不暴露。
清理： 不创建订阅或持久进程。

console.table(wu.getManifestDiagnostics());

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

wu.showInspector

打开按需加载的可视检查器。

wu.showInspector(): Promise<{ close(): void } | null>

参数： 无参数。
返回值： close handle，未打开时为 null。
错误： chunk 加载或 DOM 环境可能阻止打开。
权限： 宿主 API，scoped facade 不暴露。
清理： close() 或 wu.hideInspector() 移除 overlay。

const inspector = await wu.showInspector();
// Al cerrar tu herramienta:
inspector?.close();

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

wu.hideInspector

若存在检查 overlay，则关闭。

wu.hideInspector(): Promise<void>

参数： 无参数。
返回值： 关闭 Promise。
错误： 不删除应用或 store 数据。
权限： 宿主 API，scoped facade 不暴露。
清理： 移除诊断界面。

await wu.hideInspector();

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

wu.performance.startMeasure

标记应用或全局耗时测量的起点。

wu.performance.startMeasure(name, appName?): void

参数： 测量名称；appName 默认为 global。
返回值： void。
错误： disabled 配置会跳过记录。
权限： 宿主 API，scoped facade 不暴露。
清理： 使用同一名称/应用调用 endMeasure。

wu.performance.startMeasure('load-catalog', 'catalog');