react-native-fxview 1.0.0

package/FXView.tsx

@@ -0,0 +1,90 @@
+import React, { Component } from "react";
+import { View, ViewProps } from "react-native";
+import { ComponentItem } from "./types";
+import { FXViewManager } from "./FXViewManager";
+
+interface FXViewProps extends ViewProps {
+  fxViewId?: string; // 动态标识属性，可选
+}
+
+interface FXViewState {
+  components: ComponentItem[];
+}
+
+export default class FXView extends Component<FXViewProps, FXViewState> {
+  state: FXViewState = {
+    components: [],
+  };
+
+  private viewId: string;
+
+  constructor(props: FXViewProps) {
+    super(props);
+    // 使用 fxViewId，如果没有则生成一个唯一 ID
+    this.viewId =
+      props.fxViewId ||
+      `auto_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  componentDidMount() {
+    console.log("FXView mounted with viewId:", this.viewId);
+    // 注册到视图管理器
+    FXViewManager.getInstance().registerView(
+      this.viewId,
+      this.updateComponents,
+    );
+    // 初始更新
+    this.updateComponents();
+  }
+
+  componentDidUpdate(_prevProps: FXViewProps) {
+    console.log("FXView updated", this.viewId);
+    const newViewId = this.props.fxViewId || this.viewId;
+
+    if (newViewId !== this.viewId) {
+      // ID 变化时重新注册
+      FXViewManager.getInstance().unregisterView(this.viewId);
+
+      this.viewId = newViewId;
+
+      FXViewManager.getInstance().registerView(
+        this.viewId,
+        this.updateComponents,
+      );
+      this.updateComponents();
+    }
+  }
+
+  componentWillUnmount() {
+    console.log("FXView unmounted", this.viewId);
+    // 注销视图（会自动清理所有组件和回调）
+    FXViewManager.getInstance().unregisterView(this.viewId);
+  }
+
+  updateComponents = () => {
+    const components = FXViewManager.getInstance().getComponents(this.viewId);
+    this.setState({ components: components });
+  };
+
+  render() {
+    const { children } = this.props;
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { fxViewId, ...restProps } = this.props;
+    const { components } = this.state;
+    console.log("rendering fxView components", components.length);
+    return (
+      <View {...restProps}>
+        {children}
+        {components.map((item) =>
+          item.visible ? (
+            <React.Fragment key={item.componentId}>
+              {item.component}
+            </React.Fragment>
+          ) : null,
+        )}
+      </View>
+    );
+  }
+}
+
+export type { FXViewProps };

package/FXViewCategoryController.ts

@@ -0,0 +1,380 @@
+import React from "react";
+import { ComponentItem, ComponentController } from "./types";
+import { HeapType, PriorityOrder, PriorityQueue } from "../queue/PriorityQueue";
+
+export class FXViewCategoryController {
+  public fxViewId: string;
+  public categoryId: string;
+  private updateCallback?: () => void;
+
+  // 存储组件的 Map 和优先队列
+  private componentMap: Map<string, ComponentItem> = new Map();
+  private componentQueue: PriorityQueue<ComponentItem> = new PriorityQueue(
+    HeapType.MAX_HEAP,
+    PriorityOrder.FIFO,
+  );
+
+  constructor(
+    fxViewId: string,
+    categoryId: string,
+    triggerUpdate?: () => void,
+  ) {
+    this.fxViewId = fxViewId;
+    this.categoryId = categoryId;
+    this.updateCallback = triggerUpdate;
+  }
+
+  // ========== 主要 API 方法 ==========
+
+  /**
+   * 创建并展示组件
+   * @param component 要显示的组件
+   * @param componentId 可选的组件 ID
+   * @returns 组件控制器
+   */
+  add(component: React.ReactNode, componentId?: string): ComponentController {
+    console.log(
+      `FXViewCategoryController.add`,
+      `[${this.categoryId}]`,
+      componentId,
+    );
+
+    const finalComponentId = componentId || this.autoComponentId();
+
+    // 如果组件已存在，先移除旧的
+    if (this.componentMap.has(finalComponentId)) {
+      console.warn(
+        `Component ${finalComponentId} already exists, removing old one`,
+      );
+      this.remove(finalComponentId);
+    }
+
+    const componentItem: ComponentItem = {
+      componentId: finalComponentId,
+      component,
+      visible: true, // add 方法默认可见
+    };
+
+    this.componentMap.set(finalComponentId, componentItem);
+    this.componentQueue.enqueue(componentItem);
+    this.triggerUpdate();
+
+    return this.createController(finalComponentId);
+  }
+
+  /**
+   * 创建但不显示组件
+   * @param component 要创建的组件
+   * @param componentId 可选的组件 ID
+   * @returns 组件控制器
+   */
+  build(component: React.ReactNode, componentId?: string): ComponentController {
+    console.log(
+      `FXViewCategoryController.build`,
+      `[${this.categoryId}]`,
+      componentId,
+    );
+
+    const finalComponentId = componentId || this.autoComponentId();
+
+    // 如果组件已存在，先移除旧的
+    if (this.componentMap.has(finalComponentId)) {
+      console.warn(
+        `Component ${finalComponentId} already exists, removing old one`,
+      );
+      this.remove(finalComponentId);
+    }
+
+    const componentItem: ComponentItem = {
+      componentId: finalComponentId,
+      component,
+      visible: false, // build 方法默认不可见
+    };
+
+    this.componentMap.set(finalComponentId, componentItem);
+    this.componentQueue.enqueue(componentItem);
+
+    // build 不触发更新，因为组件不可见
+    // this.triggerUpdate();
+
+    return this.createController(finalComponentId);
+  }
+
+  /**
+   * 显示已存在的组件
+   * @param componentId 组件 ID
+   */
+  show(componentId: string): void {
+    console.log(
+      `FXViewCategoryController.show`,
+      `[${this.categoryId}]`,
+      componentId,
+    );
+
+    const componentItem = this.componentMap.get(componentId);
+
+    if (!componentItem) {
+      console.warn(
+        `Component ${componentId} not found in category ${this.categoryId}`,
+      );
+      return;
+    }
+
+    // 如果已经可见，不需要重复操作
+    if (componentItem.visible) {
+      console.log(`Component ${componentId} is already visible`);
+      return;
+    }
+
+    componentItem.visible = true;
+    this.triggerUpdate();
+  }
+
+  /**
+   * 隐藏但不删除组件
+   * @param componentId 组件 ID
+   */
+  hide(componentId: string): void {
+    console.log(
+      `FXViewCategoryController.hide`,
+      `[${this.categoryId}]`,
+      componentId,
+    );
+
+    const componentItem = this.componentMap.get(componentId);
+
+    if (!componentItem) {
+      console.warn(
+        `Component ${componentId} not found in category ${this.categoryId}`,
+      );
+      return;
+    }
+
+    // 如果已经隐藏，不需要重复操作
+    if (!componentItem.visible) {
+      console.log(`Component ${componentId} is already hidden`);
+      return;
+    }
+
+    componentItem.visible = false;
+    this.triggerUpdate();
+  }
+
+  /**
+   * 更新组件内容
+   * @param componentId 组件 ID
+   * @param component 新的组件内容
+   */
+  update(componentId: string, component: React.ReactNode): void {
+    console.log(
+      `FXViewCategoryController.update`,
+      `[${this.categoryId}]`,
+      componentId,
+    );
+
+    const componentItem = this.componentMap.get(componentId);
+
+    if (!componentItem) {
+      console.warn(
+        `Component ${componentId} not found in category ${this.categoryId}`,
+      );
+      return;
+    }
+
+    // 更新组件内容
+    componentItem.component = component;
+
+    // 只有在组件可见时才触发更新
+    if (componentItem.visible) {
+      this.triggerUpdate();
+    } else {
+      console.log(
+        `Component ${componentId} is hidden, update without re-render`,
+      );
+    }
+  }
+
+  /**
+   * 彻底删除组件
+   * @param componentId 组件 ID（必需）
+   */
+  remove(componentId: string): void {
+    console.log(
+      `FXViewCategoryController.remove`,
+      `[${this.categoryId}]`,
+      componentId,
+    );
+
+    const componentItem = this.componentMap.get(componentId);
+
+    if (!componentItem) {
+      console.warn(
+        `Component ${componentId} not found in category ${this.categoryId}`,
+      );
+      return;
+    }
+
+    // 从 Map 中删除
+    this.componentMap.delete(componentId);
+
+    // 从优先队列中删除
+    this.componentQueue.remove(componentItem);
+
+    this.triggerUpdate();
+  }
+
+  /**
+   * 移除最后一个组件（可选：用于向后兼容）
+   */
+  removeLast(): void {
+    console.log(`FXViewCategoryController.removeLast`, `[${this.categoryId}]`);
+
+    const lastComponent = this.componentQueue.peek();
+
+    if (!lastComponent) {
+      console.warn(`No component to remove in category ${this.categoryId}`);
+      return;
+    }
+
+    this.remove(lastComponent.componentId);
+  }
+
+  /**
+   * 清空所有组件
+   */
+  clearAll(): void {
+    console.log(`FXViewCategoryController.clearAll`, `[${this.categoryId}]`);
+
+    const hadVisibleComponents = Array.from(this.componentMap.values()).some(
+      (item) => item.visible,
+    );
+
+    this.componentMap.clear();
+    this.componentQueue.clear();
+
+    // 只有在有可见组件时才触发更新
+    if (hadVisibleComponents) {
+      this.triggerUpdate();
+    }
+  }
+
+  /**
+   * 注册更新回调
+   * @param updateCallback 更新回调函数
+   */
+  registerUpdateCallback(updateCallback?: () => void): void {
+    this.updateCallback = updateCallback;
+  }
+
+  /**
+   * 获取组件列表
+   * @returns 组件列表
+   */
+  getComponents(): ComponentItem[] {
+    return this.componentQueue.getAll();
+  }
+
+  /**
+   * 获取组件数量
+   * @returns 组件数量
+   */
+  getComponentCount(): number {
+    return this.componentMap.size;
+  }
+
+  /**
+   * 获取可见组件数量
+   * @returns 可见组件数量
+   */
+  getVisibleComponentCount(): number {
+    return Array.from(this.componentMap.values()).filter((item) => item.visible)
+      .length;
+  }
+
+  /**
+   * 检查组件是否存在
+   * @param componentId 组件 ID
+   * @returns 是否存在
+   */
+  hasComponent(componentId: string): boolean {
+    return this.componentMap.has(componentId);
+  }
+
+  /**
+   * 检查组件是否可见
+   * @param componentId 组件 ID
+   * @returns 是否可见
+   */
+  isVisible(componentId: string): boolean {
+    const component = this.componentMap.get(componentId);
+    return component?.visible ?? false;
+  }
+
+  // ========== 私有方法 ==========
+
+  /**
+   * 触发更新
+   */
+  private triggerUpdate(): void {
+    console.log(
+      `FXViewCategoryController.triggerUpdate`,
+      `[${this.categoryId}]`,
+    );
+
+    if (this.updateCallback) {
+      this.updateCallback();
+    }
+  }
+
+  /**
+   * 创建组件控制器
+   * @param componentId 组件 ID
+   * @returns 组件控制器
+   */
+  private createController(componentId: string): ComponentController {
+    console.log(
+      `FXViewCategoryController.createController`,
+      `[${this.categoryId}]`,
+      componentId,
+    );
+
+    // ✅ 修复：不在闭包中捕获 componentItem，每次都从 Map 获取最新引用
+    return {
+      show: () => {
+        this.show(componentId);
+      },
+      hide: () => {
+        this.hide(componentId);
+      },
+      remove: () => {
+        this.remove(componentId);
+      },
+      update: (component: React.ReactNode) => {
+        this.update(componentId, component);
+      },
+      getFxViewId: () => this.fxViewId,
+      getCategoryId: () => this.categoryId,
+      getComponentId: () => componentId,
+      getComponent: () => {
+        // ✅ 每次都从 Map 获取最新的组件引用
+        return this.componentMap.get(componentId)?.component;
+      },
+      isVisible: () => {
+        return this.isVisible(componentId);
+      },
+      exists: () => {
+        return this.hasComponent(componentId);
+      },
+    };
+  }
+
+  /**
+   * 自动生成 componentId
+   * @returns 生成的 componentId
+   */
+  private autoComponentId(): string {
+    return `component_${Date.now()}_${Math.random()
+      .toString(36)
+      .substring(2, 9)}`;
+  }
+}

package/FXViewController.ts

@@ -0,0 +1,370 @@
+import React from "react";
+import { ComponentController, ComponentItem } from "./types";
+import { FXViewCategoryController } from "./FXViewCategoryController";
+
+export class FXViewController {
+  public fxViewId: string;
+  public updateCallback?: () => void;
+
+  // 存储各分类的控制器
+  private categoryControllerMap: Map<string, FXViewCategoryController> =
+    new Map();
+
+  constructor(fxViewId: string) {
+    this.fxViewId = fxViewId;
+  }
+
+  //#region ========== 主要 API 方法 ==========
+
+  /**
+   * 创建并显示组件
+   * @param component 组件内容
+   * @param categoryId 分类 ID（可选，默认 "default"）
+   * @param componentId 组件 ID（可选，自动生成）
+   * @returns 组件控制器
+   */
+  add(
+    component: React.ReactNode,
+    categoryId?: string,
+    componentId?: string,
+  ): ComponentController {
+    console.log("FXViewController.add", `[${this.fxViewId}]`, {
+      categoryId,
+      componentId,
+    });
+
+    const categoryController = this.getCategoryControllerOrCreate(categoryId);
+    return categoryController.add(component, componentId);
+  }
+
+  /**
+   * 创建但不显示组件
+   * @param component 组件内容
+   * @param categoryId 分类 ID（可选，默认 "default"）
+   * @param componentId 组件 ID（可选，自动生成）
+   * @returns 组件控制器
+   */
+  build(
+    component: React.ReactNode,
+    categoryId?: string,
+    componentId?: string,
+  ): ComponentController {
+    console.log("FXViewController.build", `[${this.fxViewId}]`, {
+      categoryId,
+      componentId,
+    });
+
+    const categoryController = this.getCategoryControllerOrCreate(categoryId);
+    return categoryController.build(component, componentId);
+  }
+
+  /**
+   * 显示已存在的组件
+   * @param componentId 组件 ID
+   * @param categoryId 分类 ID（可选，默认 "default"）
+   */
+  show(componentId: string, categoryId?: string): void {
+    console.log("FXViewController.show", `[${this.fxViewId}]`, {
+      categoryId,
+      componentId,
+    });
+
+    const categoryController = this.getCategoryController(categoryId);
+    if (!categoryController) {
+      console.warn(
+        `CategoryController ${categoryId || "default"} not found in view ${this.fxViewId}`,
+      );
+      return;
+    }
+
+    categoryController.show(componentId);
+  }
+
+  /**
+   * 隐藏但不删除组件
+   * @param componentId 组件 ID
+   * @param categoryId 分类 ID（可选，默认 "default"）
+   */
+  hide(componentId: string, categoryId?: string): void {
+    console.log("FXViewController.hide", `[${this.fxViewId}]`, {
+      categoryId,
+      componentId,
+    });
+
+    const categoryController = this.getCategoryController(categoryId);
+    if (!categoryController) {
+      console.warn(
+        `CategoryController ${categoryId || "default"} not found in view ${this.fxViewId}`,
+      );
+      return;
+    }
+
+    categoryController.hide(componentId);
+  }
+
+  /**
+   * 更新组件内容
+   * @param componentId 组件 ID
+   * @param component 新的组件内容
+   * @param categoryId 分类 ID（可选，默认 "default"）
+   */
+  update(
+    componentId: string,
+    component: React.ReactNode,
+    categoryId?: string,
+  ): void {
+    console.log("FXViewController.update", `[${this.fxViewId}]`, {
+      categoryId,
+      componentId,
+    });
+
+    const categoryController = this.getCategoryController(categoryId);
+    if (!categoryController) {
+      console.warn(
+        `CategoryController ${categoryId || "default"} not found in view ${this.fxViewId}`,
+      );
+      return;
+    }
+
+    categoryController.update(componentId, component);
+  }
+
+  /**
+   * 彻底删除组件
+   * @param componentId 组件 ID
+   * @param categoryId 分类 ID（可选，默认 "default"）
+   */
+  remove(componentId: string, categoryId?: string): void {
+    console.log("FXViewController.remove", `[${this.fxViewId}]`, {
+      categoryId,
+      componentId,
+    });
+
+    const categoryController = this.getCategoryController(categoryId);
+    if (!categoryController) {
+      console.warn(
+        `CategoryController ${categoryId || "default"} not found in view ${this.fxViewId}`,
+      );
+      return;
+    }
+
+    categoryController.remove(componentId);
+
+    // 如果该分类没有组件了，删除整个分类控制器
+    if (categoryController.getComponentCount() === 0) {
+      this.removeCategory(categoryId);
+    }
+  }
+
+  /**
+   * 移除最后一个组件（向后兼容）
+   * @param categoryId 分类 ID（可选，默认 "default"）
+   */
+  removeLast(categoryId?: string): void {
+    console.log("FXViewController.removeLast", `[${this.fxViewId}]`, {
+      categoryId,
+    });
+
+    const categoryController = this.getCategoryController(categoryId);
+    if (!categoryController) {
+      console.warn(
+        `CategoryController ${categoryId || "default"} not found in view ${this.fxViewId}`,
+      );
+      return;
+    }
+
+    categoryController.removeLast();
+
+    // 如果该分类没有组件了，删除整个分类控制器
+    if (categoryController.getComponentCount() === 0) {
+      this.removeCategory(categoryId);
+    }
+  }
+
+  /**
+   * 清空所有分类的所有组件
+   */
+  clearAll(): void {
+    console.log("FXViewController.clearAll", `[${this.fxViewId}]`);
+
+    this.categoryControllerMap.forEach((controller) => {
+      controller.clearAll();
+    });
+    this.categoryControllerMap.clear();
+  }
+
+  /**
+   * 清空指定分类的所有组件
+   * @param categoryId 分类 ID
+   */
+  clearCategory(categoryId?: string): void {
+    const finalCategoryId = categoryId || "default";
+    console.log("FXViewController.clearCategory", `[${this.fxViewId}]`, {
+      categoryId: finalCategoryId,
+    });
+
+    const categoryController = this.getCategoryController(categoryId);
+    if (!categoryController) {
+      console.warn(
+        `CategoryController ${finalCategoryId} not found in view ${this.fxViewId}`,
+      );
+      return;
+    }
+
+    categoryController.clearAll();
+    this.categoryControllerMap.delete(finalCategoryId);
+  }
+
+  /**
+   * 注册更新回调
+   * @param callback 更新回调函数
+   */
+  registerUpdateCallback(callback?: () => void): void {
+    this.updateCallback = callback;
+
+    // 将回调传递给所有已存在的分类控制器
+    this.categoryControllerMap.forEach((controller) => {
+      controller.registerUpdateCallback(callback);
+    });
+  }
+
+  /**
+   * 获取组件列表
+   * @param filterOptions 过滤选项
+   * @returns 组件列表
+   */
+  getComponents(categoryId?: string): ComponentItem[] {
+    const result: ComponentItem[] = [];
+
+    this.categoryControllerMap.forEach((categoryController, category) => {
+      // 如果指定了类别，只处理指定类别
+      if (categoryId && categoryId !== category) {
+        return;
+      }
+      const categoryComponents = categoryController.getComponents();
+      result.push(...categoryComponents);
+    });
+
+    return result;
+  }
+
+  /**
+   * 获取总组件数量
+   * @returns 组件数量
+   */
+  getComponentCount(): number {
+    let count = 0;
+    this.categoryControllerMap.forEach((controller) => {
+      count += controller.getComponentCount();
+    });
+    return count;
+  }
+
+  /**
+   * 获取可见组件数量
+   * @returns 可见组件数量
+   */
+  getVisibleComponentCount(): number {
+    let count = 0;
+    this.categoryControllerMap.forEach((controller) => {
+      count += controller.getVisibleComponentCount();
+    });
+    return count;
+  }
+
+  /**
+   * 检查组件是否存在
+   * @param componentId 组件 ID
+   * @param categoryId 分类 ID（可选）
+   * @returns 是否存在
+   */
+  hasComponent(componentId: string, categoryId?: string): boolean {
+    if (categoryId) {
+      const controller = this.getCategoryController(categoryId);
+      return controller?.hasComponent(componentId) ?? false;
+    }
+
+    // 如果没有指定分类，搜索所有分类
+    for (const controller of this.categoryControllerMap.values()) {
+      if (controller.hasComponent(componentId)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * 检查组件是否可见
+   * @param componentId 组件 ID
+   * @param categoryId 分类 ID（可选）
+   * @returns 是否可见
+   */
+  isComponentVisible(componentId: string, categoryId?: string): boolean {
+    if (categoryId) {
+      const controller = this.getCategoryController(categoryId);
+      return controller?.isVisible(componentId) ?? false;
+    }
+
+    // 如果没有指定分类，搜索所有分类
+    for (const controller of this.categoryControllerMap.values()) {
+      if (controller.hasComponent(componentId)) {
+        return controller.isVisible(componentId);
+      }
+    }
+    return false;
+  }
+
+  //#endregion
+
+  //#region ========== 私有方法 ==========
+
+  /**
+   * 获取分类控制器
+   * @param categoryId 分类 ID
+   * @returns 分类控制器或 null
+   */
+  private getCategoryController(
+    categoryId?: string,
+  ): FXViewCategoryController | null {
+    const finalCategoryId = categoryId || "default";
+    return this.categoryControllerMap.get(finalCategoryId) || null;
+  }
+
+  /**
+   * 获取或创建分类控制器
+   * @param categoryId 分类 ID
+   * @returns 分类控制器
+   */
+  private getCategoryControllerOrCreate(
+    categoryId?: string,
+  ): FXViewCategoryController {
+    const finalCategoryId = categoryId || "default";
+
+    let categoryController = this.categoryControllerMap.get(finalCategoryId);
+
+    if (!categoryController) {
+      categoryController = new FXViewCategoryController(
+        this.fxViewId,
+        finalCategoryId,
+        this.updateCallback,
+      );
+      this.categoryControllerMap.set(finalCategoryId, categoryController);
+    }
+
+    return categoryController;
+  }
+
+  /**
+   * 删除分类控制器
+   * @param categoryId 分类 ID
+   */
+  private removeCategory(categoryId?: string): void {
+    const finalCategoryId = categoryId || "default";
+    console.log("FXViewController.removeCategory", `[${this.fxViewId}]`, {
+      categoryId: finalCategoryId,
+    });
+    this.categoryControllerMap.delete(finalCategoryId);
+  }
+
+  //#endregion
+}

package/FXViewManager.ts

@@ -0,0 +1,421 @@
+import React from "react";
+import { ComponentController, ComponentItem } from "./types";
+import { FXViewController } from "./FXViewController";
+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);
+
+  static getInstance(): FXViewManager {
+    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: React.ReactNode,
+    fxViewId?: string,
+    categoryId?: string,
+    componentId?: string,
+  ): ComponentController {
+    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: React.ReactNode,
+    fxViewId?: string,
+    categoryId?: string,
+    componentId?: string,
+  ): ComponentController {
+    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: string, fxViewId?: string, categoryId?: string): void {
+    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: string, fxViewId?: string, categoryId?: string): void {
+    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: string,
+    component: React.ReactNode,
+    fxViewId?: string,
+    categoryId?: string,
+  ): void {
+    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: string, fxViewId?: string, categoryId?: string): void {
+    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?: string, categoryId?: string): void {
+    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?: string): void {
+    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: string, fxViewId?: string): void {
+    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: string, updateCallback: () => void): FXViewController {
+    console.log("FXViewManager.registerView", fxViewId);
+
+    let viewController = this.viewControllerMap.get(fxViewId);
+
+    if (!viewController) {
+      viewController = new FXViewController(fxViewId);
+      this.viewControllerMap.set(fxViewId, viewController);
+    }
+
+    // 注册更新回调
+    viewController.registerUpdateCallback(updateCallback);
+
+    // 更新视图栈（移除旧的引用，添加新的）
+    const existingController = this.viewControllerQueue
+      .getAll()
+      .find((vc) => vc.fxViewId === fxViewId);
+    if (existingController) {
+      this.viewControllerQueue.remove(existingController);
+    }
+    this.viewControllerQueue.enqueue(viewController);
+
+    return viewController;
+  }
+
+  /**
+   * 注销视图（FXView 卸载时调用）
+   * @param fxViewId 视图 ID
+   * @returns 是否成功注销
+   */
+  unregisterView(fxViewId: string): boolean {
+    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.viewControllerQueue.remove(viewController);
+
+    // 从 Map 中删除
+    this.viewControllerMap.delete(fxViewId);
+
+    return true;
+  }
+
+  /**
+   * 获取最近使用的视图 ID（栈顶）
+   * @returns 最近的视图 ID 或 null
+   */
+  getLatestFXViewId(): string | null {
+    return this.viewControllerQueue.peek()?.fxViewId || null;
+  }
+
+  /**
+   * 获取组件列表
+   * @param fxViewId 视图 ID（可选，使用最近的视图）
+   * @param categoryId 分类 ID（可选）
+   * @returns 组件列表
+   */
+  getComponents(fxViewId?: string, categoryId?: string): ComponentItem[] {
+    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?: string): number {
+    const viewController = this.getViewController(fxViewId);
+    return viewController?.getComponentCount() ?? 0;
+  }
+
+  /**
+   * 获取可见组件数量
+   * @param fxViewId 视图 ID（可选，使用最近的视图）
+   * @returns 可见组件数量
+   */
+  getVisibleComponentCount(fxViewId?: string): number {
+    const viewController = this.getViewController(fxViewId);
+    return viewController?.getVisibleComponentCount() ?? 0;
+  }
+
+  /**
+   * 检查组件是否存在
+   * @param componentId 组件 ID
+   * @param fxViewId 视图 ID（可选，使用最近的视图）
+   * @param categoryId 分类 ID（可选）
+   * @returns 是否存在
+   */
+  hasComponent(
+    componentId: string,
+    fxViewId?: string,
+    categoryId?: string,
+  ): boolean {
+    const viewController = this.getViewController(fxViewId);
+    return viewController?.hasComponent(componentId, categoryId) ?? false;
+  }
+
+  /**
+   * 检查组件是否可见
+   * @param componentId 组件 ID
+   * @param fxViewId 视图 ID（可选，使用最近的视图）
+   * @param categoryId 分类 ID（可选）
+   * @returns 是否可见
+   */
+  isComponentVisible(
+    componentId: string,
+    fxViewId?: string,
+    categoryId?: string,
+  ): boolean {
+    const viewController = this.getViewController(fxViewId);
+    return viewController?.isComponentVisible(componentId, categoryId) ?? false;
+  }
+
+  //#endregion
+
+  //#region ========== 私有方法 ==========
+
+  /**
+   * 获取视图控制器
+   * @param fxViewId 视图 ID（可选，使用最近的视图）
+   * @returns 视图控制器或 null
+   */
+  private getViewController(fxViewId?: string): FXViewController | null {
+    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 视图控制器
+   */
+  private getViewControllerOrCreate(fxViewId?: string): FXViewController {
+    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(finalFXViewId);
+      this.viewControllerMap.set(finalFXViewId, viewController);
+      this.viewControllerQueue.enqueue(viewController);
+    }
+
+    return viewController;
+  }
+
+  /**
+   * 自动生成 fxViewId
+   * @returns 生成的 fxViewId
+   */
+  private autoFXViewId(): string {
+    return `fxView_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  //#endregion
+}

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "react-native-fxview",
+  "version": "1.0.0",
+  "description": "dynamic view ",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC"
+}

package/types.ts

@@ -0,0 +1,39 @@
+import type React from "react";
+
+// ========== 参数配置接口 ==========
+
+/**
+ * 组件控制器接口
+ * 用于控制动态组件的显示、隐藏、更新等操作
+ */
+export interface ComponentController {
+  /** 显示组件 */
+  show: () => void;
+  /** 隐藏组件 */
+  hide: () => void;
+  /** 移除组件 */
+  remove: () => void;
+  /** 更新组件内容 */
+  update: (component: React.ReactNode) => void;
+  /** 获取所属的 FXView ID */
+  getFxViewId: () => string;
+  /** 获取所属的分类 ID */
+  getCategoryId: () => string;
+  /** 获取组件 ID */
+  getComponentId: () => string;
+  /** 获取组件实例 */
+  getComponent: () => React.ReactNode;
+  /** 判断组件是否可见 */
+  isVisible: () => boolean;
+  /** 判断组件是否存在 */
+  exists: () => boolean;
+}
+
+/**
+ * 组件项配置接口
+ */
+export interface ComponentItem {
+  componentId: string; // 组件唯一标识（必填）
+  component?: React.ReactNode; // 组件内容
+  visible?: boolean; // 是否可见，默认为 true
+}