@kkarum/framework 2.3.18 → 2.3.20

package/docs/UI_DEVELOPMENT_GUIDE.md

@@ -0,0 +1,295 @@
+# UI Development Guide
+
+## AI 生成 UI 代码规则
+
+以下规则用于约束 Codex / AI 工具生成 UI 相关代码，并覆盖本文档中的旧示例：
+
+- `LayerController` 中不要查找节点或组件，不要使用 `find()` / `findComponent()` 缓存 UI 引用。
+- 节点引用写在对应 `FW.Layer` 组件中，使用 `@FWPropertyNode()`，变量名与节点名一致。
+- 组件引用写在对应 `FW.Layer` 组件中，使用 `@FWPropertyComponent(ComponentClass)`，变量名与节点名一致。
+- `layerAssetProperty` 返回资源时使用点访问：`preLoad.prefab.ShopLayer`，不要写 `preLoad.prefab["ShopLayer"]`。
+- 默认不要在 Controller 或业务层调用 `invoke()`，除非用户明确要求。
+
+推荐结构：
+
+```ts
+@ccclass
+export class ShopLayer extends FW.Layer {
+  @FWPropertyNode()
+  BtnClose: cc.Node = null;
+
+  @FWPropertyComponent(cc.Label)
+  TitleLabel: cc.Label = null;
+}
+
+export class ShopLayerController extends FW.LayerController {
+  get layerAssetProperty(): FW.AssetProperty {
+    return FW.Entry.getComponent(ShopAssetConfig).preLoad.prefab.ShopLayer;
+  }
+
+  onInit() {
+    const layer = this.layer as ShopLayer;
+    this.cc(layer.BtnClose, this.onCloseClick);
+    layer.TitleLabel.string = "Shop";
+  }
+}
+```
+
+本文档定义基于本框架开发 UI 的标准做法。
+
+## UI 类型
+
+### 常驻层
+
+适合主界面、HUD、底部导航。
+
+```ts
+layerType = FW.SystemDefine.FWLayerType.PERMANENT;
+renderOrder = FW.SystemDefine.FWLayerRenderOrder.PERMANENT;
+```
+
+可使用：
+
+```ts
+this.hide();
+this.display();
+```
+
+框架会暂停/恢复节点系统事件、框架事件和定时器。
+
+### 普通 UI
+
+适合可重复打开的页面。
+
+```ts
+layerType = FW.SystemDefine.FWLayerType.REPEAT;
+renderOrder = FW.SystemDefine.FWLayerRenderOrder.UI;
+```
+
+### 队列弹窗
+
+适合奖励弹窗、确认弹窗。
+
+```ts
+layerType = FW.SystemDefine.FWLayerType.POPUP_QUEUE;
+renderOrder = FW.SystemDefine.FWLayerRenderOrder.POPUP;
+```
+
+已有队列弹窗时，新弹窗会入队，当前弹窗关闭后再打开下一个。
+
+### 一次性弹窗
+
+```ts
+layerType = FW.SystemDefine.FWLayerType.POPUP_DISPOSABLE;
+renderOrder = FW.SystemDefine.FWLayerRenderOrder.POPUP;
+```
+
+## LayerController 标准结构
+
+```ts
+export class InventoryLayerController extends FW.LayerController {
+  renderOrder = FW.SystemDefine.FWLayerRenderOrder.UI;
+  layerType = FW.SystemDefine.FWLayerType.REPEAT;
+  autoRelease = true;
+  isRepeatOpen = false;
+
+  private closeButton: cc.Node;
+  private titleLabel: cc.Label;
+
+  get layerAssetProperty(): FW.AssetProperty {
+    return this.getConfig<InventoryAssetConfig>().preLoad.prefab["InventoryLayer"] as FW.AssetProperty;
+  }
+
+  onInit(args?: any) {
+    this.cacheNodes();
+    this.bindEvents();
+    this.render();
+  }
+
+  private cacheNodes() {
+    this.closeButton = this.find("CloseButton", this.layer.node);
+    this.titleLabel = this.findComponent("TitleLabel", this.layer.node, cc.Label);
+  }
+
+  private bindEvents() {
+    this.cc(this.closeButton, this.onCloseClick);
+  }
+
+  private render() {
+    this.titleLabel.string = "Inventory";
+  }
+
+  private onCloseClick = () => {
+    this.close();
+  };
+}
+```
+
+## 节点查找
+
+推荐：
+
+```ts
+const node = this.find("CloseButton", this.layer.node);
+const label = this.findComponent("TitleLabel", this.layer.node, cc.Label);
+```
+
+可使用装饰器：
+
+```ts
+@FWPropertyNode({ path: "CloseButton" })
+private closeButton: cc.Node;
+
+@FWPropertyComponent(cc.Label, "TitleLabel")
+private titleLabel: cc.Label;
+```
+
+注意：
+
+- 装饰器改写 `onLoad`，更适合 Cocos Component。
+- LayerController 不是挂在节点上的 Cocos Component，优先使用 `find()`。
+
+## 事件绑定
+
+按钮：
+
+```ts
+this.cc(buttonNode, this.onButtonClick);
+```
+
+自定义事件：
+
+```ts
+this.fw("INVENTORY_CHANGED", this.render);
+```
+
+复杂：
+
+```ts
+this.registerEvent({
+  CCEvent: [{
+    target: buttonNode,
+    eventName: cc.Node.EventType.TOUCH_END,
+    responseInterval: 500,
+    cb: this.onButtonClick,
+  }],
+});
+```
+
+不要在 LayerController 中散落裸 `node.on()`。如必须使用，必须在关闭时手动 `off`。
+
+## 列表开发
+
+### 小列表
+
+可以直接实例化 item prefab，但仍应使用 `FW.Entry.resMgr` 加载资源。
+
+### 大列表
+
+优先使用：
+
+- `FWVirtualViewComponent`
+- `FWVirtuaScrollViewComponent`
+- `FW.Entry.objectMgr.createObjectPool()`
+
+`FWVirtualViewComponent` 常用字段：
+
+```ts
+list.onRender = (item, index) => {};
+list.onSelected = (item, index, lastIndex, selected?) => {};
+list.onPageChange = (item, page) => {};
+list.count = data.length;
+list.updateItem(index);
+list.updateAll();
+list.scrollTo(index, 0.3);
+list.prePage();
+list.nextPage();
+list.skipPage(page, 0.3);
+```
+
+## UI 与 Data 同步
+
+推荐方向：
+
+```text
+Logic -> Data -> evtMgr.dispatch -> LayerController.render
+```
+
+示例：
+
+```ts
+// Data
+setItems(items: Item[]) {
+  this.items = items;
+  FW.Entry.evtMgr.dispatch("INVENTORY_ITEMS_CHANGED", items);
+}
+
+// LayerController
+this.fw("INVENTORY_ITEMS_CHANGED", this.renderItems);
+```
+
+## 打开和关闭
+
+打开：
+
+```ts
+await FW.Entry.layerMgr.openAsync<InventoryLayerController>({
+  type: InventoryLayerController,
+  args: { selectedTab: 1 },
+});
+```
+
+关闭：
+
+```ts
+this.close();
+```
+
+关闭前异步处理：
+
+```ts
+async onClose() {
+  await this.playCloseAnimation();
+}
+```
+
+`FWLayerManager.close()` 会等待 `onClose()`，再销毁节点、释放资源、清理状态。
+
+## 资源释放
+
+LayerController 属性：
+
+```ts
+autoRelease = true;
+```
+
+关闭时，如果 `autoRelease` 为 true，框架会调用：
+
+```ts
+FW.Entry.resMgr.releaseAsset(ctr.layerData.layerAssetProperty);
+```
+
+注意：资源释放依赖 `AssetProperty.autoRelease` 和引用计数。不要手动释放还在使用的公共资源。
+
+## UI 自动化约定
+
+使用 cocos-mcp 创建 UI 时：
+
+- 根节点名与 prefab 名一致。
+- 交互节点名与代码一致。
+- 按钮节点含 `cc.Button` 和可视组件。
+- 文本节点含 `cc.Label`。
+- 滚动区域含 `cc.ScrollView`、`content`、`cc.Layout`。
+- 全屏根节点使用 `cc.Widget` stretch/full。
+
+## UI 质量检查
+
+完成 UI 功能前检查：
+
+- `layerAssetProperty` 能解析到有效 prefab。
+- `onInit()` 中所有 `find()` 节点存在。
+- 按钮不会重复注册。
+- 列表刷新不会无限实例化节点。
+- 关闭时没有未清理定时器。
+- 弹窗类型和渲染顺序符合用途。
+- `autoRelease` 与资源复用场景一致。

package/docs/UI_DEVELOPMENT_GUIDE.md.meta

@@ -0,0 +1,6 @@
+{
+  "ver": "2.0.2",
+  "uuid": "a1d8b0f1-89cd-4fad-be1a-84e8df02cb56",
+  "importer": "markdown",
+  "subMetas": {}
+}

package/docs.meta

@@ -0,0 +1,13 @@
+{
+  "ver": "1.1.3",
+  "uuid": "1e0c55a2-93ba-4368-9b54-26c8d470d0ed",
+  "importer": "folder",
+  "isBundle": false,
+  "bundleName": "",
+  "priority": 1,
+  "compressionType": {},
+  "optimizeHotUpdate": {},
+  "inlineSpriteFrames": {},
+  "isRemoteBundle": {},
+  "subMetas": {}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkarum/framework",
-  "version": "2.3.18",
+  "version": "2.3.20",
   "description": "cocoscreator 2.x mvc framework",
   "main": "index.js",
   "keywords": [