react-native-fxview 1.0.0 → 1.0.2-beta1

package/FXViewManager.js

@@ -0,0 +1,352 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FXViewManager = void 0;
+const FXViewController_1 = require("./FXViewController");
+const PriorityQueue_1 = require("./queue/PriorityQueue");
+class FXViewManager {
+    constructor() {
+        // 存储视图控制器
+        this.viewControllerMap = new Map();
+        this.fxViewIdQueue = new PriorityQueue_1.PriorityQueue(PriorityQueue_1.HeapType.MAX_HEAP, PriorityQueue_1.PriorityOrder.LIFO);
+        this.viewLifecycleCallbacks = [];
+        //#endregion
+    }
+    static getInstance() {
+        if (!FXViewManager.instance) {
+            FXViewManager.instance = new FXViewManager();
+        }
+        return FXViewManager.instance;
+    }
+    //#region ========== 主要 API 方法 ==========
+    /**
+     * 创建并显示组件
+     * @param component 组件内容
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选，默认 "default"）
+     * @param componentId 组件 ID（可选，自动生成）
+     * @returns 组件控制器
+     */
+    add(component, fxViewId, categoryId, componentId) {
+        console.log("FXViewManager.add", {
+            fxViewId,
+            categoryId,
+            componentId,
+        });
+        const viewController = this.getViewControllerOrCreate(fxViewId);
+        return viewController.add(component, categoryId, componentId);
+    }
+    /**
+     * 创建但不显示组件
+     * @param component 组件内容
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选，默认 "default"）
+     * @param componentId 组件 ID（可选，自动生成）
+     * @returns 组件控制器
+     */
+    build(component, fxViewId, categoryId, componentId) {
+        console.log("FXViewManager.build", {
+            fxViewId,
+            categoryId,
+            componentId,
+        });
+        const viewController = this.getViewControllerOrCreate(fxViewId);
+        return viewController.build(component, categoryId, componentId);
+    }
+    /**
+     * 显示已存在的组件
+     * @param componentId 组件 ID
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选，默认 "default"）
+     */
+    show(componentId, fxViewId, categoryId) {
+        console.log("FXViewManager.show", {
+            fxViewId,
+            categoryId,
+            componentId,
+        });
+        const viewController = this.getViewController(fxViewId);
+        if (!viewController) {
+            console.warn(`FXView ${fxViewId || "latest"} not found`);
+            return;
+        }
+        viewController.show(componentId, categoryId);
+    }
+    /**
+     * 隐藏但不删除组件
+     * @param componentId 组件 ID
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选，默认 "default"）
+     */
+    hide(componentId, fxViewId, categoryId) {
+        console.log("FXViewManager.hide", {
+            fxViewId,
+            categoryId,
+            componentId,
+        });
+        const viewController = this.getViewController(fxViewId);
+        if (!viewController) {
+            console.warn(`FXView ${fxViewId || "latest"} not found`);
+            return;
+        }
+        viewController.hide(componentId, categoryId);
+    }
+    /**
+     * 更新组件内容
+     * @param componentId 组件 ID
+     * @param component 新的组件内容
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选，默认 "default"）
+     */
+    update(componentId, component, fxViewId, categoryId) {
+        console.log("FXViewManager.update", {
+            fxViewId,
+            categoryId,
+            componentId,
+        });
+        const viewController = this.getViewController(fxViewId);
+        if (!viewController) {
+            console.warn(`FXView ${fxViewId || "latest"} not found`);
+            return;
+        }
+        viewController.update(componentId, component, categoryId);
+    }
+    /**
+     * 彻底删除组件
+     * @param componentId 组件 ID
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选，默认 "default"）
+     */
+    remove(componentId, fxViewId, categoryId) {
+        console.log("FXViewManager.remove", {
+            fxViewId,
+            categoryId,
+            componentId,
+        });
+        const viewController = this.getViewController(fxViewId);
+        if (!viewController) {
+            console.warn(`FXView ${fxViewId || "latest"} not found`);
+            return;
+        }
+        viewController.remove(componentId, categoryId);
+    }
+    /**
+     * 移除最后一个组件（向后兼容）
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选，默认 "default"）
+     */
+    removeLast(fxViewId, categoryId) {
+        console.log("FXViewManager.removeLast", {
+            fxViewId,
+            categoryId,
+        });
+        const viewController = this.getViewController(fxViewId);
+        if (!viewController) {
+            console.warn(`FXView ${fxViewId || "latest"} not found`);
+            return;
+        }
+        viewController.removeLast(categoryId);
+    }
+    /**
+     * 清空指定视图的所有组件
+     * @param fxViewId 视图 ID（可选，清空所有视图）
+     */
+    clearAll(fxViewId) {
+        console.log("FXViewManager.clearAll", { fxViewId });
+        if (fxViewId) {
+            // 清空指定视图
+            const viewController = this.getViewController(fxViewId);
+            if (viewController) {
+                viewController.clearAll();
+            }
+        }
+        else {
+            // 清空所有视图
+            this.viewControllerMap.forEach((controller) => {
+                controller.clearAll();
+            });
+        }
+    }
+    /**
+     * 清空指定分类的所有组件
+     * @param categoryId 分类 ID
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     */
+    clearCategory(categoryId, fxViewId) {
+        console.log("FXViewManager.clearCategory", { fxViewId, categoryId });
+        const viewController = this.getViewController(fxViewId);
+        if (!viewController) {
+            console.warn(`FXView ${fxViewId || "latest"} not found`);
+            return;
+        }
+        viewController.clearCategory(categoryId);
+    }
+    //#endregion
+    //#region ========== 视图管理方法 ==========
+    /**
+     * 注册视图（FXView 挂载时调用）
+     * @param fxViewId 视图 ID
+     * @param updateCallback 更新回调函数
+     * @returns 视图控制器
+     */
+    registerView(fxViewId, updateCallback) {
+        console.log("FXViewManager.registerView", fxViewId);
+        let viewController = this.viewControllerMap.get(fxViewId);
+        if (!viewController) {
+            viewController = new FXViewController_1.FXViewController(fxViewId);
+            this.viewControllerMap.set(fxViewId, viewController);
+        }
+        // 注册更新回调
+        viewController.registerUpdateCallback(updateCallback);
+        this.fxViewIdQueue.remove(fxViewId);
+        this.fxViewIdQueue.enqueue(fxViewId);
+        this.viewLifecycleCallbacks.forEach((callback) => {
+            var _a;
+            (_a = callback.didMount) === null || _a === void 0 ? void 0 : _a.call(callback, fxViewId);
+        });
+        return viewController;
+    }
+    /**
+     * 注销视图（FXView 卸载时调用）
+     * @param fxViewId 视图 ID
+     * @returns 是否成功注销
+     */
+    unregisterView(fxViewId) {
+        console.log("FXViewManager.unregisterView", fxViewId);
+        const viewController = this.getViewController(fxViewId);
+        if (!viewController) {
+            console.warn(`FXView ${fxViewId} not found, cannot unregister`);
+            return false;
+        }
+        // 清空回调
+        viewController.registerUpdateCallback(undefined);
+        // 清空所有组件
+        viewController.clearAll();
+        // 从队列中移除
+        this.fxViewIdQueue.remove(fxViewId);
+        // 从 Map 中删除
+        this.viewControllerMap.delete(fxViewId);
+        this.viewLifecycleCallbacks.forEach((callback) => {
+            var _a;
+            (_a = callback.willUnmount) === null || _a === void 0 ? void 0 : _a.call(callback, fxViewId);
+        });
+        return true;
+    }
+    registerLifecycleCallbacks(callbacks) {
+        console.log("FXViewManager.registerLifecycleCallbacks");
+        this.viewLifecycleCallbacks.push(callbacks);
+    }
+    unregisterLifecycleCallbacks(callbacks) {
+        console.log("FXViewManager.unregisterLifecycleCallbacks");
+        this.viewLifecycleCallbacks = this.viewLifecycleCallbacks.filter((callback) => callback !== callbacks);
+    }
+    /**
+     * 获取最近使用的视图 ID（栈顶）
+     * @returns 最近的视图 ID 或 null
+     */
+    getLatestFXViewId() {
+        return this.fxViewIdQueue.peek() || null;
+    }
+    /**
+     * 获取组件列表
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选）
+     * @returns 组件列表
+     */
+    getComponents(fxViewId, categoryId) {
+        console.log("FXViewManager.getComponents", { fxViewId, categoryId });
+        const finalFXViewId = fxViewId || this.getLatestFXViewId();
+        if (!finalFXViewId) {
+            console.warn("No FXView available");
+            return [];
+        }
+        const viewController = this.getViewController(finalFXViewId);
+        if (!viewController) {
+            console.warn(`FXViewController ${finalFXViewId} not found`);
+            return [];
+        }
+        return viewController.getComponents(categoryId);
+    }
+    /**
+     * 获取组件数量
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @returns 组件数量
+     */
+    getComponentCount(fxViewId) {
+        var _a;
+        const viewController = this.getViewController(fxViewId);
+        return (_a = viewController === null || viewController === void 0 ? void 0 : viewController.getComponentCount()) !== null && _a !== void 0 ? _a : 0;
+    }
+    /**
+     * 获取可见组件数量
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @returns 可见组件数量
+     */
+    getVisibleComponentCount(fxViewId) {
+        var _a;
+        const viewController = this.getViewController(fxViewId);
+        return (_a = viewController === null || viewController === void 0 ? void 0 : viewController.getVisibleComponentCount()) !== null && _a !== void 0 ? _a : 0;
+    }
+    /**
+     * 检查组件是否存在
+     * @param componentId 组件 ID
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选）
+     * @returns 是否存在
+     */
+    hasComponent(componentId, fxViewId, categoryId) {
+        var _a;
+        const viewController = this.getViewController(fxViewId);
+        return (_a = viewController === null || viewController === void 0 ? void 0 : viewController.hasComponent(componentId, categoryId)) !== null && _a !== void 0 ? _a : false;
+    }
+    /**
+     * 检查组件是否可见
+     * @param componentId 组件 ID
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @param categoryId 分类 ID（可选）
+     * @returns 是否可见
+     */
+    isComponentVisible(componentId, fxViewId, categoryId) {
+        var _a;
+        const viewController = this.getViewController(fxViewId);
+        return (_a = viewController === null || viewController === void 0 ? void 0 : viewController.isComponentVisible(componentId, categoryId)) !== null && _a !== void 0 ? _a : false;
+    }
+    //#endregion
+    //#region ========== 私有方法 ==========
+    /**
+     * 获取视图控制器
+     * @param fxViewId 视图 ID（可选，使用最近的视图）
+     * @returns 视图控制器或 null
+     */
+    getViewController(fxViewId) {
+        const finalFXViewId = fxViewId || this.getLatestFXViewId();
+        if (!finalFXViewId) {
+            console.warn("FXViewManager.getViewController: no fxViewId available");
+            return null;
+        }
+        return this.viewControllerMap.get(finalFXViewId) || null;
+    }
+    /**
+     * 获取或创建视图控制器
+     * @param fxViewId 视图 ID（可选，使用最近的视图或创建新的）
+     * @returns 视图控制器
+     */
+    getViewControllerOrCreate(fxViewId) {
+        const finalFXViewId = fxViewId || this.getLatestFXViewId() || this.autoFXViewId();
+        let viewController = this.viewControllerMap.get(finalFXViewId);
+        if (!viewController) {
+            console.warn(`FXViewController ${finalFXViewId} not registered, creating a temporary one`);
+            viewController = new FXViewController_1.FXViewController(finalFXViewId);
+            this.viewControllerMap.set(finalFXViewId, viewController);
+            this.fxViewIdQueue.enqueue(finalFXViewId);
+        }
+        return viewController;
+    }
+    /**
+     * 自动生成 fxViewId
+     * @returns 生成的 fxViewId
+     */
+    autoFXViewId() {
+        return `fxView_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+    }
+}
+exports.FXViewManager = FXViewManager;

package/FXViewManager.ts

@@ -1,15 +1,22 @@
 import React from "react";
-import { ComponentController, ComponentItem } from "./types";
+import {
+  FXComponentController,
+  FXComponentItem,
+  FXLifecycleCallbacks,
+} from "./types";
 import { FXViewController } from "./FXViewController";
-import { HeapType, PriorityOrder, PriorityQueue } from "../queue/PriorityQueue";
+import { HeapType, PriorityOrder, PriorityQueue } from "./queue/PriorityQueue";
 
 export class FXViewManager {
   private static instance: FXViewManager;
 
   // 存储视图控制器
   private viewControllerMap: Map<string, FXViewController> = new Map();
-  private viewControllerQueue: PriorityQueue<FXViewController> =
-    new PriorityQueue(HeapType.MAX_HEAP, PriorityOrder.LIFO);
+  private fxViewIdQueue: PriorityQueue<string> = new PriorityQueue(
+    HeapType.MAX_HEAP,
+    PriorityOrder.LIFO,
+  );
+  private viewLifecycleCallbacks: Array<FXLifecycleCallbacks> = [];
 
   static getInstance(): FXViewManager {
     if (!FXViewManager.instance) {
@@ -33,7 +40,7 @@ export class FXViewManager {
     fxViewId?: string,
     categoryId?: string,
     componentId?: string,
-  ): ComponentController {
+  ): FXComponentController {
     console.log("FXViewManager.add", {
       fxViewId,
       categoryId,
@@ -57,7 +64,7 @@ export class FXViewManager {
     fxViewId?: string,
     categoryId?: string,
     componentId?: string,
-  ): ComponentController {
+  ): FXComponentController {
     console.log("FXViewManager.build", {
       fxViewId,
       categoryId,
@@ -242,16 +249,11 @@ export class FXViewManager {
 
     // 注册更新回调
     viewController.registerUpdateCallback(updateCallback);
-
-    // 更新视图栈（移除旧的引用，添加新的）
-    const existingController = this.viewControllerQueue
-      .getAll()
-      .find((vc) => vc.fxViewId === fxViewId);
-    if (existingController) {
-      this.viewControllerQueue.remove(existingController);
-    }
-    this.viewControllerQueue.enqueue(viewController);
-
+    this.fxViewIdQueue.remove(fxViewId);
+    this.fxViewIdQueue.enqueue(fxViewId);
+    this.viewLifecycleCallbacks.forEach((callback) => {
+      callback.didMount?.(fxViewId);
+    });
     return viewController;
   }
 
@@ -276,20 +278,36 @@ export class FXViewManager {
     viewController.clearAll();
 
     // 从队列中移除
-    this.viewControllerQueue.remove(viewController);
+    this.fxViewIdQueue.remove(fxViewId);
 
     // 从 Map 中删除
     this.viewControllerMap.delete(fxViewId);
 
+    this.viewLifecycleCallbacks.forEach((callback) => {
+      callback.willUnmount?.(fxViewId);
+    });
+
     return true;
   }
 
+  registerLifecycleCallbacks(callbacks: FXLifecycleCallbacks): void {
+    console.log("FXViewManager.registerLifecycleCallbacks");
+    this.viewLifecycleCallbacks.push(callbacks);
+  }
+
+  unregisterLifecycleCallbacks(callbacks: FXLifecycleCallbacks): void {
+    console.log("FXViewManager.unregisterLifecycleCallbacks");
+    this.viewLifecycleCallbacks = this.viewLifecycleCallbacks.filter(
+      (callback) => callback !== callbacks,
+    );
+  }
+
   /**
    * 获取最近使用的视图 ID（栈顶）
    * @returns 最近的视图 ID 或 null
    */
   getLatestFXViewId(): string | null {
-    return this.viewControllerQueue.peek()?.fxViewId || null;
+    return this.fxViewIdQueue.peek() || null;
   }
 
   /**
@@ -298,7 +316,7 @@ export class FXViewManager {
    * @param categoryId 分类 ID（可选）
    * @returns 组件列表
    */
-  getComponents(fxViewId?: string, categoryId?: string): ComponentItem[] {
+  getComponents(fxViewId?: string, categoryId?: string): FXComponentItem[] {
     console.log("FXViewManager.getComponents", { fxViewId, categoryId });
 
     const finalFXViewId = fxViewId || this.getLatestFXViewId();
@@ -403,7 +421,7 @@ export class FXViewManager {
       );
       viewController = new FXViewController(finalFXViewId);
       this.viewControllerMap.set(finalFXViewId, viewController);
-      this.viewControllerQueue.enqueue(viewController);
+      this.fxViewIdQueue.enqueue(finalFXViewId);
     }
 
     return viewController;

package/README.md

@@ -0,0 +1,209 @@
+# React Native FXView
+
+一个革命性的React Native动态UI预埋框架，支持在任何位置预埋容器，然后通过全局管理器在运行时动态注入和控制React组件。
+
+## 🎯 核心概念
+
+FXView采用**预埋+注入**的设计模式：
+
+1. **预埋容器**：在应用的任何位置预埋`FXView`容器
+2. **动态注入**：通过`FXViewManager`在任何时间、任何位置动态注入React组件
+3. **全局控制**：支持跨组件、跨页面的全局UI管理和状态控制
+
+## ✨ 功能特性
+
+- 🎯 **动态组件注入** - 运行时在任何预埋位置注入React组件
+- 🔄 **实时UI更新** - 支持组件内容的实时更新和状态管理
+- 📂 **智能分类管理** - 按分类组织和管理动态组件
+- 👁️ **显示/隐藏控制** - 灵活控制组件的显示状态
+- 🌍 **全局访问** - 从应用的任何地方访问和管理UI
+- 🚀 **轻量级高性能** - 优化的渲染性能和内存管理
+
+## 📦 安装
+
+```bash
+npm install react-native-fxview
+# 或者
+yarn add react-native-fxview
+```
+
+## 🚀 快速开始
+
+### 1. 预埋FXView容器
+
+在任何需要动态注入UI的位置预埋FXView：
+
+```javascript
+import React from 'react';
+import { View, Text } from 'react-native';
+import { FXView } from 'react-native-fxview';
+
+export default function App() {
+  return (
+    <View style={{ flex: 1 }}>
+      <Text>静态内容</Text>
+      
+      {/* 预埋动态UI容器 */}
+      <FXView fxViewId="headerArea" style={{ height: 60 }} />
+      
+      <Text>更多静态内容</Text>
+      
+      {/* 在底部预埋另一个容器 */}
+      <FXView fxViewId="bottomSheet" style={{ position: 'absolute', bottom: 0 }} />
+    </View>
+  );
+}
+```
+
+### 2. 动态注入组件
+
+从应用的任何地方（甚至不同的页面或组件）动态注入UI：
+
+```javascript
+import { FXViewManager } from 'react-native-fxview';
+import { Button, View, Text } from 'react-native';
+
+// 在headerArea注入一个搜索栏
+const searchBarController = FXViewManager.getInstance().add(
+  <View style={{ backgroundColor: '#f0f0f0', padding: 10 }}>
+    <Text>搜索栏组件</Text>
+  </View>,
+  'headerArea',  // fxViewId
+  'navigation'   // categoryId
+);
+
+// 在bottomSheet注入一个弹窗
+const sheetController = FXViewManager.getInstance().add(
+  <View style={{ backgroundColor: 'white', padding: 20, borderRadius: 10 }}>
+    <Text>底部弹窗内容</Text>
+    <Button title="关闭" onPress={() => sheetController.hide()} />
+  </View>,
+  'bottomSheet',
+  'modals'
+);
+```
+
+### 3. 运行时控制
+
+```javascript
+// 隐藏搜索栏
+searchBarController.hide();
+
+// 更新搜索栏内容
+searchBarController.update(
+  <View style={{ backgroundColor: 'blue', padding: 10 }}>
+    <Text style={{ color: 'white' }}>更新后的搜索栏</Text>
+  </View>
+);
+
+// 显示搜索栏
+searchBarController.show();
+
+// 完全移除组件
+searchBarController.remove();
+```
+
+## 📖 API 参考
+
+### FXView Props
+
+- `fxViewId` (string, optional): 容器唯一标识符，用于后续注入组件时的定位
+
+### FXViewManager 主要方法
+
+#### 组件管理
+- `add(component, fxViewId?, category?, componentId?)` - 创建并显示组件
+- `build(component, fxViewId?, category?, componentId?)` - 创建但不显示组件
+- `show(componentId, fxViewId?, category?)` - 显示已存在的组件
+- `hide(componentId, fxViewId?, category?)` - 隐藏组件
+- `update(componentId, newComponent, fxViewId?, category?)` - 更新组件内容
+- `remove(componentId, fxViewId?, category?)` - 移除组件
+
+#### 批量操作
+- `clearAll(fxViewId?)` - 清空指定或所有容器
+- `clearCategory(categoryId, fxViewId?)` - 清空指定分类
+
+#### 查询方法
+- `getComponents(fxViewId?, category?)` - 获取组件列表
+- `hasComponent(componentId, fxViewId?, category?)` - 检查组件是否存在
+- `isComponentVisible(componentId, fxViewId?, category?)` - 检查组件是否可见
+
+### 组件控制器 (FXComponentController)
+
+- `show()` - 显示组件
+- `hide()` - 隐藏组件
+- `remove()` - 移除组件
+- `update(newComponent)` - 更新组件内容
+- `isVisible()` - 获取可见状态
+- `exists()` - 检查组件是否存在
+
+## 💡 使用场景
+
+### 1. 动态导航栏
+在不同页面根据状态动态改变顶部导航栏内容
+
+### 2. 全局弹窗系统
+从任何地方触发全局弹窗、通知、确认框等
+
+### 3. 动态表单
+根据用户操作动态添加、移除、更新表单字段
+
+### 4. 插件化UI
+支持第三方插件动态注入UI组件到主应用
+
+### 5. A/B测试
+动态切换不同的UI组件进行A/B测试
+
+## 🎯 最佳实践
+
+### 分类管理
+使用分类来组织不同类型的动态组件：
+
+```javascript
+// 导航相关
+FXViewManager.getInstance().add(navComponent, 'header', 'navigation');
+
+// 弹窗相关
+FXViewManager.getInstance().add(modalComponent, 'overlay', 'modals');
+
+// 通知相关
+FXViewManager.getInstance().add(toastComponent, 'notification', 'notifications');
+```
+
+### 生命周期管理
+```javascript
+// 创建时
+const controller = FXViewManager.getInstance().build(component, 'container');
+
+// 需要时显示
+controller.show();
+
+// 不需要时隐藏
+controller.hide();
+
+// 完全清理
+controller.remove();
+```
+
+## 🔧 高级用法
+
+### 生命周期回调
+```javascript
+FXViewManager.getInstance().registerLifecycleCallbacks({
+  didMount: (fxViewId) => console.log('FXView挂载:', fxViewId),
+  willUnmount: (fxViewId) => console.log('FXView卸载:', fxViewId)
+});
+```
+
+### 组件查询和批量操作
+```javascript
+// 获取所有导航组件
+const navComponents = FXViewManager.getInstance().getComponents(null, 'navigation');
+
+// 清空所有弹窗
+FXViewManager.getInstance().clearCategory('modals');
+```
+
+## 📄 许可证
+
+MIT

package/index.d.ts

@@ -0,0 +1,5 @@
+export { default as FXView } from "./FXView";
+export { FXViewManager } from "./FXViewManager";
+export { FXViewController } from "./FXViewController";
+export { FXCategoryController } from "./FXCategoryController";
+export * from "./types";