@kkarum/framework 2.3.17 → 2.3.19

package/docs/FRAMEWORK_API.md

@@ -0,0 +1,414 @@
+# Framework API
+
+本文档记录业务开发最常复用的框架 API。除非维护框架本身，不要直接修改 `assets/framework`。
+
+## 全局入口
+
+### `FW.Entry`
+
+常用属性：
+
+| 属性 | 用途 |
+| --- | --- |
+| `bundleName` | 当前业务 bundle 名 |
+| `scene` | 当前 `FW.Scene` |
+| `resMgr` | 资源和 bundle 管理 |
+| `layerMgr` | Layer 打开、关闭、栈、队列 |
+| `uiMgr` | UI 事件、节点查找 |
+| `evtMgr` | 框架事件总线 |
+| `timeMgr` | 定时器和 update |
+| `promiseMgr` | 可取消/超时/重试 Promise |
+| `socketMgr` | Socket 连接 |
+| `objectMgr` | 对象池 |
+| `taskMgr` | 分帧任务 |
+| `languageMgr` | 多语言 |
+| `performanceMgr` | 性能采样 |
+| `utils` | 通用工具 |
+
+方法：
+
+```ts
+FW.Entry.getComponent<T>(identifier): T
+FW.Entry.getComponents<T>(identifier?): T[]
+FW.Entry.launchScene(bundleName, forceRelease?)
+FW.Entry.register({ bundleName, sceneName, depend, autoRelease })
+FW.Entry.unRegister(...)
+FW.Entry.getDepend(bundleName): string[]
+FW.Entry.update(dt)
+FW.Entry.restart()
+```
+
+## 依赖容器
+
+### `FW.Framework`
+
+```ts
+FW.Framework.register({
+  bundleName,
+  logic,
+  data,
+  config,
+  sender,
+  handle,
+});
+
+FW.Framework.unRegister(...)
+FW.Framework.getComponent<T>(ClassOrKey)
+FW.Framework.getComponents<T>(BaseClass)
+FW.Framework.addRegistry(bundleName, RegistryClass)
+FW.Framework.createRegistry(bundleName)
+FW.Framework.destroyRegistry(bundleName)
+FW.Framework.restart()
+```
+
+绑定 key 规则：`${bundleName}${FW.SystemDefine.FWBindTag.*}`。
+
+业务代码通常通过 `FW.Entry.getComponent()` 间接使用，不直接操作容器。
+
+## 基类
+
+### `FW.FrameworkBase`
+
+继承者：
+
+- `FW.Logic`
+- `FW.Data`
+- `FW.Service`
+- `FW.Sender`
+- `FW.Handle`
+- `FWManager`
+- `FW.LayerController`
+
+可用方法：
+
+```ts
+this.entry
+this.getLogic<T>()
+this.getData<T>()
+this.getConfig<T>()
+this.getSender<T>()
+this.getHandle<T>()
+this.initializeDependencies()
+await this.invoke(promise, "operationName")
+```
+
+自动注入依赖依赖类名约定：
+
+- `*Logic`
+- `*Data`
+- `*Config` 或 `*AssetConfig`
+- `*Sender` 或 `*SocketSender`
+- `*Handle` 或 `*SocketHandle`
+
+类名还必须包含 bundle 名。例如 bundle 为 `shop`，推荐 `ShopLogic`、`ShopData`。
+
+## Registry
+
+### `FW.Registry`
+
+```ts
+abstract readonly bundleName: string;
+readonly autoRelease?: boolean;
+readonly sceneName?: string;
+readonly depend?: string[];
+readonly logic?: FW.Newable<FW.Logic>;
+readonly data?: FW.Newable<FW.Data>;
+readonly config?: FW.Newable<FW.AssetConfig>;
+readonly sender?: FW.Newable<FW.Sender>;
+readonly handle?: FW.Newable<FW.Handle>;
+register(): void;
+unRegister(): void;
+```
+
+注册表用于把 bundle 元信息和业务组件交给框架。bundle 加载/释放会自动调用。
+
+## Layer API
+
+### `FW.Entry.layerMgr`
+
+```ts
+openAsync<Ctr>({ type, parent?, position?, args? }): Promise<Ctr>
+openSync<Ctr>({ type, parent?, position?, args? }): Ctr
+close(ctr): Promise<Ctr>
+closeFromStack(count?)
+closeFromLayerName(name | name[])
+displayLayer(ctr)
+hideLayer(ctr)
+removeAllChildren(node)
+clear()
+openDebug()
+getLayerMap()
+```
+
+`LayerOpenArgs`：
+
+```ts
+type LayerOpenArgs = {
+  type: new () => FW.LayerController;
+  parent?: cc.Node;
+  position?: { x: number; y: number };
+  args?: any;
+};
+```
+
+### `FW.LayerController`
+
+业务控制器必须实现：
+
+```ts
+renderOrder: FW.SystemDefine.FWLayerRenderOrder;
+layerType: FW.SystemDefine.FWLayerType;
+layer: FW.Layer;
+layerAssetProperty: FW.AssetProperty;
+autoRelease: boolean;
+isRepeatOpen: boolean;
+```
+
+生命周期：
+
+```ts
+initialize()
+onInit(...args)
+onLoad()
+onStart()
+onEnable()
+onDisable()
+onUpdate(dt)
+onLateUpdate(dt)
+onClose()
+onDestroy()
+destroy()
+```
+
+便捷方法：
+
+```ts
+find(path, referenceNode)
+findComponent<T>(path, referenceNode, type)
+registerEvent(args)
+cc(targetNode, cb, responseInterval?, eventName?)
+fw(eventName, cb, target?, responseInterval?)
+pauseEvent()
+resumeEvent()
+hide()
+display()
+close()
+```
+
+## 资源 API
+
+### `FW.AssetProperty`
+
+```ts
+type AssetProperty = {
+  resourceId?: number;
+  bundle?: string;
+  path: string;
+  type?: typeof cc.Asset;
+  cb?: (asset: FW.AssetData | FW.AssetData[]) => void;
+  progress?: (finish: number, total: number, item: cc.AssetManager.RequestItem) => void;
+  user?: string;
+  autoRelease?: boolean;
+  priorityLoaded?: boolean;
+};
+```
+
+### `FW.Entry.resMgr`
+
+```ts
+loadBundle(bundleName): Promise<cc.AssetManager.Bundle>
+getBundle(bundleName): cc.AssetManager.Bundle
+releaseBundle(bundleName): void
+hasBundle(bundleName): boolean
+
+loadAssetData<T>(assetProperty): Promise<FW.AssetData>
+loadAsset<T>(assetProperty, texture?): Promise<T>
+getAssetData<T>(assetProperty, texture?): FW.AssetData
+getAsset<T>(assetProperty, texture?): T
+preLoad(assetProperty | assetProperty[])
+loadDir(assetProperty): Promise<FW.AssetData[]>
+loadRemote<T>(url, options?): Promise<T>
+loadSpineDataFromRemote({ img, ske, atlas, bin? }): Promise<sp.SkeletonData>
+releaseAsset(assetProperty): void
+hasAsset(assetProperty): boolean
+registerRejectHandler(listener): void
+```
+
+纹理注意：默认 `Texture2D` 会转换为 `SpriteFrame`。需要原始纹理时传 `texture: true`。
+
+## 事件 API
+
+### `FW.Entry.evtMgr`
+
+```ts
+register(eventName, cb, target, options?)
+registerOnce(eventName, cb, target, options?)
+dispatch(eventName, ...args)
+unRegister(eventName, target)
+eventOff(eventName)
+targetOff(target)
+targetPause(target)
+targetResume(target)
+has(eventName, target)
+getListenerCount(eventName)
+```
+
+`options`：
+
+```ts
+{
+  priority?: FW.SystemDefine.FWPriorityOrder;
+  intercept?: boolean;
+  once?: boolean;
+}
+```
+
+### `FW.Entry.uiMgr`
+
+```ts
+register({ target?, CCEvent?, FWEvent? })
+find(path, rootNode): cc.Node | null
+pauseEvent(target)
+resumeEvent(target)
+unRegisterEvent(args)
+unRegisterTarget(target)
+unRegisterAll()
+hasRegister(eventName, target)
+buttonEnable(target)
+buttonDisable(target)
+```
+
+## Time API
+
+```ts
+FW.Entry.timeMgr.schedule(cb, intervalSeconds?, repeat?, target?, tag?)
+FW.Entry.timeMgr.scheduleOnce(cbOrTime?, timeOrTargetOrTag?, targetOrTag?)
+FW.Entry.timeMgr.update(cb, tagOrTarget?, target?)
+FW.Entry.timeMgr.pauseSchedule(tag | id | target)
+FW.Entry.timeMgr.resumeSchedule(tag | id | target)
+FW.Entry.timeMgr.unSchedule(tag | id | target)
+FW.Entry.timeMgr.onUpdate(dt)
+```
+
+返回的 `TimerSchedule` 支持：
+
+```ts
+unSchedule()
+pauseSchedule()
+resumeSchedule()
+promise? // scheduleOnce
+```
+
+## Promise API
+
+```ts
+const proxy = FW.Entry.promiseMgr.execute(executor, {
+  reason,
+  timeout,
+  retryCount,
+  retryInterval,
+  retryCondition,
+});
+
+proxy.id
+proxy.promise
+proxy.status
+proxy.abort(reason?)
+proxy.addAbortEventListener(listener)
+```
+
+批量：
+
+```ts
+FW.Entry.promiseMgr.all([proxy1, proxy2], options)
+FW.Entry.promiseMgr.cancel(id, reason?)
+FW.Entry.promiseMgr.cancelMultiple(ids, reason?)
+FW.Entry.promiseMgr.cancelAll(reason?)
+FW.Entry.promiseMgr.getStatus(id)
+FW.Entry.promiseMgr.getAllStatus()
+FW.Entry.promiseMgr.getActiveCount()
+FW.Entry.promiseMgr.clearCompletedPromise()
+```
+
+## Socket API
+
+### `FW.Entry.socketMgr`
+
+```ts
+createSocket(tag, address, sender, handle, config): Promise<FW.Socket>
+getSocket(tag?): FW.Socket
+getSocketMap(): Map<string, FW.Socket>
+closeSocket(socket)
+closeAll()
+pauseMessageHandle()
+resumeMessageHandle()
+```
+
+### `FW.Sender`
+
+```ts
+sendHeart?()
+onHeart?(msg): Promise<boolean>
+onBeforeSendingMessage?(msg): Promise<FW.SocketMessage>
+getProtocolKey?(msg): string
+send(msg)
+```
+
+### `FW.Handle`
+
+```ts
+onMessage(msg): void
+onBeforeReceivingMessage?(msg): Promise<FW.SocketMessage>
+onHeart?(msg): Promise<boolean>
+getProtocolKey?(msg): string
+onOpen?()
+onClose?()
+onError?(msg)
+onTimeout?()
+onWeakNetWork?()
+```
+
+## Object Pool API
+
+```ts
+const pool = await FW.Entry.objectMgr.createObjectPool(prefabOrNodeOrAsset, parent, tagOrType?)
+FW.Entry.objectMgr.getObjectPool(tag)
+FW.Entry.objectMgr.destroyObjectPool(tag)
+FW.Entry.objectMgr.getPoolStats()
+FW.Entry.objectMgr.clearAllPools()
+```
+
+`FW.ObjectPool`：
+
+```ts
+get(...args): FW.ObjectProperty
+put(node | component | uniqueId)
+puts(array)
+findObjectProperty(node | component | uniqueId)
+isEmpty()
+getEnableObjectMap()
+getDisableObjectMap()
+getAllObjectMap()
+onDestroy()
+```
+
+池对象组件继承 `FW.Object`，实现 `onInit()`、`onGet()`、`onPut()`、`onDestroy()`。
+
+## 装饰器
+
+全局装饰器由 `initializeFramework()` 挂到 `globalThis`：
+
+```ts
+@FWPropertyNode({ path? })
+@FWPropertyNodes(...paths)
+@FWPropertyComponent(ComponentClass, childName?, mute?)
+@FWPropertyComponents(ComponentClass, childName?)
+@PerformanceMonitor(operationName?)
+@FWDeprecated(description?)
+@FWSocketAutoProcessPause()
+@FWSocketAutoProcessResume()
+@AutoRegisterCCEvent(nodePath, eventName?)
+@AutoRegisterFWEvent(eventName)
+```
+
+装饰器会改写 `onLoad` 或方法 descriptor。使用时必须确认目标类生命周期和路径稳定。

package/docs/FRAMEWORK_API.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "66b8acf8-acdf-43e2-a401-8b9afa24b01c",
+  "importer": "markdown",
+  "subMetas": {}
+}

package/docs/FRAMEWORK_EXAMPLES.md

@@ -0,0 +1,309 @@
+# Framework Examples
+
+本文档提供可复制的业务代码骨架。示例中的 bundle 名使用 `shop`，实际开发时替换为目标业务名。
+
+## Registry
+
+```ts
+import { FWRegistry } from "../../framework/registry/FWRegistry";
+import { ShopLogic } from "../logic/ShopLogic";
+import { ShopData } from "../data/ShopData";
+import { ShopAssetConfig } from "../config/ShopAssetConfig";
+import { ShopSender } from "../socket/ShopSender";
+import { ShopHandle } from "../socket/ShopHandle";
+
+export class ShopRegistry extends FWRegistry {
+  readonly bundleName = "shop";
+  readonly sceneName = "ShopScene";
+  readonly depend = ["common"];
+  readonly autoRelease = true;
+  readonly logic = ShopLogic;
+  readonly data = ShopData;
+  readonly config = ShopAssetConfig;
+  readonly sender = ShopSender;
+  readonly handle = ShopHandle;
+}
+```
+
+## AssetConfig
+
+```ts
+export class ShopAssetConfig extends FW.AssetConfig {
+  preLoad: FW.LoadConfig = {
+    prefab: {
+      ShopLayer: {
+        bundle: "shop",
+        path: "prefab/ShopLayer",
+        type: cc.Prefab,
+        priorityLoaded: true,
+        autoRelease: true,
+      },
+      ShopItem: {
+        bundle: "shop",
+        path: "prefab/ShopItem",
+        type: cc.Prefab,
+      },
+    },
+  };
+
+  demandLoad: FW.LoadConfig = {
+    texture: {
+      CoinIcon: {
+        bundle: "shop",
+        path: "texture/CoinIcon",
+        type: cc.Texture2D,
+      },
+    },
+  };
+}
+```
+
+## Data
+
+```ts
+export type ShopGoods = {
+  id: number;
+  name: string;
+  price: number;
+  icon: string;
+};
+
+export class ShopData extends FW.Data {
+  private goods: ShopGoods[] = [];
+
+  setGoods(goods: ShopGoods[]) {
+    this.goods = goods || [];
+    FW.Entry.evtMgr.dispatch("SHOP_GOODS_CHANGED", this.goods);
+  }
+
+  getGoods() {
+    return this.goods;
+  }
+}
+```
+
+## Logic
+
+```ts
+export class ShopLogic extends FW.Logic {
+  async openShop() {
+    await FW.Entry.layerMgr.openAsync({
+      type: ShopLayerController,
+    });
+  }
+
+  async refreshGoods() {
+    const response = await this.invoke(
+      this.getSender<ShopSender>().requestGoods(),
+      "requestGoods",
+    );
+
+    if (!response) return;
+    this.getData<ShopData>().setGoods(response.goods);
+  }
+}
+```
+
+## LayerController
+
+```ts
+export class ShopLayerController extends FW.LayerController {
+  renderOrder = FW.SystemDefine.FWLayerRenderOrder.UI;
+  layerType = FW.SystemDefine.FWLayerType.REPEAT;
+  autoRelease = true;
+  isRepeatOpen = false;
+
+  private listNode: cc.Node;
+  private closeButton: cc.Node;
+
+  get layerAssetProperty(): FW.AssetProperty {
+    return this.getConfig<ShopAssetConfig>().preLoad.prefab["ShopLayer"] as FW.AssetProperty;
+  }
+
+  onInit() {
+    this.cacheNodes();
+    this.bindEvents();
+    this.getLogic<ShopLogic>().refreshGoods();
+  }
+
+  private cacheNodes() {
+    this.listNode = this.find("GoodsList", this.layer.node);
+    this.closeButton = this.find("CloseButton", this.layer.node);
+  }
+
+  private bindEvents() {
+    this.cc(this.closeButton, this.onCloseClick);
+    this.fw("SHOP_GOODS_CHANGED", this.renderGoods);
+  }
+
+  private onCloseClick = () => {
+    this.close();
+  };
+
+  private renderGoods = (goods: ShopGoods[]) => {
+    // 渲染列表或刷新虚拟列表
+  };
+}
+```
+
+## Button Event
+
+```ts
+private bindEvents() {
+  const buyButton = this.find("BuyButton", this.layer.node);
+  this.cc(buyButton, this.onBuyClick, 500);
+}
+
+private onBuyClick = () => {
+  this.getLogic<ShopLogic>().buySelectedGoods();
+};
+```
+
+## Framework Event
+
+```ts
+// dispatch
+FW.Entry.evtMgr.dispatch("SHOP_BUY_SUCCESS", goodsId);
+
+// listen inside LayerController
+this.fw("SHOP_BUY_SUCCESS", this.onBuySuccess);
+
+private onBuySuccess = (goodsId: number) => {
+  FW.Log.debug("buy success", goodsId);
+};
+```
+
+## Resource Load
+
+```ts
+async loadCoinIcon(sprite: cc.Sprite) {
+  const cfg = this.getConfig<ShopAssetConfig>();
+  const frame = await this.invoke(
+    FW.Entry.resMgr.loadAsset<cc.SpriteFrame>(
+      cfg.demandLoad.texture["CoinIcon"] as FW.AssetProperty,
+    ),
+    "loadCoinIcon",
+  );
+
+  if (frame && cc.isValid(sprite)) {
+    sprite.spriteFrame = frame;
+  }
+}
+```
+
+## Object Pool Item
+
+```ts
+export class ShopItem extends FW.Object {
+  private label: cc.Label;
+
+  onInit() {
+    this.label = this.node.getChildByName("Name").getComponent(cc.Label);
+  }
+
+  onGet(args: any[]) {
+    const goods = args[0] as ShopGoods;
+    this.label.string = goods.name;
+  }
+
+  onPut() {
+    this.label.string = "";
+  }
+}
+```
+
+```ts
+const cfg = this.getConfig<ShopAssetConfig>();
+const prefab = await FW.Entry.resMgr.loadAsset<cc.Prefab>(
+  cfg.preLoad.prefab["ShopItem"] as FW.AssetProperty,
+);
+const pool = await FW.Entry.objectMgr.createObjectPool(prefab, this.listNode, "shop_item");
+const item = pool.get(goods);
+```
+
+## Virtual View
+
+```ts
+const list = this.findComponent<FW.VirtualViewComponent>(
+  "GoodsScrollView",
+  this.layer.node,
+  FWVirtualViewComponent,
+);
+
+list.onRender = (item: cc.Node, index: number) => {
+  const goods = this.getData<ShopData>().getGoods()[index];
+  item.getChildByName("Name").getComponent(cc.Label).string = goods.name;
+};
+
+list.count = this.getData<ShopData>().getGoods().length;
+```
+
+## Promise With Timeout
+
+```ts
+async waitForAnimation(node: cc.Node) {
+  const proxy = FW.Entry.promiseMgr.execute<void>((resolve) => {
+    cc.tween(node)
+      .to(0.2, { opacity: 255 })
+      .call(() => resolve())
+      .start();
+  }, {
+    timeout: 1000,
+  });
+
+  await proxy.promise;
+}
+```
+
+## Sender And Handle
+
+```ts
+export class ShopSender extends FW.Sender {
+  requestGoods() {
+    const msg = { cmd: "shop.goods", seq: Date.now() };
+    this.send(msg);
+    return new Promise<any>((resolve) => {
+      FW.Entry.evtMgr.registerOnce(`SOCKET_RESPONSE_${msg.seq}`, resolve, this);
+    });
+  }
+
+  sendHeart() {
+    this.send({ cmd: "heart" });
+  }
+
+  async onHeart(msg: any) {
+    return msg?.cmd === "heart";
+  }
+
+  async onBeforeSendingMessage(msg: any) {
+    return JSON.stringify(msg);
+  }
+
+  getProtocolKey(msg: any) {
+    return msg?.seq ? String(msg.seq) : "";
+  }
+}
+```
+
+```ts
+export class ShopHandle extends FW.Handle {
+  async onBeforeReceivingMessage(event: MessageEvent) {
+    return JSON.parse(event.data);
+  }
+
+  onMessage(msg: any) {
+    if (msg.seq) {
+      FW.Entry.evtMgr.dispatch(`SOCKET_RESPONSE_${msg.seq}`, msg);
+    }
+    FW.Entry.evtMgr.dispatch(`SOCKET_CMD_${msg.cmd}`, msg);
+  }
+
+  async onHeart(msg: any) {
+    return msg?.cmd === "heart";
+  }
+
+  getProtocolKey(msg: any) {
+    return msg?.seq ? String(msg.seq) : "";
+  }
+}
+```

package/docs/FRAMEWORK_EXAMPLES.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "95541d8a-714f-40e7-ad8b-7889c597c67a",
+  "importer": "markdown",
+  "subMetas": {}
+}