SuperAPI AI 工具集

gpui-entity

通用与其它

查看项目

更新于 10-16 00:01

技能介绍

用途:介绍 GPUI 框架中 Entity 的状态管理与组件间协调方式。Entity<T> 是类型 T 状态的句柄,提供安全读取与更新。

主要能力:entity.read(cx) 只读访问;entity.read_with(cx, |state, cx| ...) 带闭包读取;entity.update(cx, |state, cx| ...) 可变更新;entity.downgrade() 生成 WeakEntity<T>;entity.entity_id() 返回唯一标识。Entity<T> 为强引用会增加引用计数,WeakEntity<T> 为弱引用不阻止清理并返回 Result。

使用方式:用 cx.new(|cx| Counter { count: 0 }) 创建实体;读取 counter.read(cx).count;更新时在闭包内修改状态并调用 cx.notify() 触发重渲染。组件中可持有 Entity<SharedData> 字段,通过 self.shared_state.update(cx, ...) 修改共享状态。异步场景用 cx.entity().downgrade() 获取弱引用,再在 cx.spawn 中通过 weak_self.update(cx, ...) 安全更新。

核心原则:闭包与回调中始终使用弱引用以避免循环引用和内存泄漏;更新闭包内使用内部 cx 而非外部 cx;避免嵌套 entity.update,同一实体重入会立即 panic,不同实体通常安全但间接循环仍会 panic,建议展平调用顺序。cx.defer_in 不会绕过锁,回调内同样受重入规则约束。render_item 等渲染钩子运行在渲染过程中,不得对外部实体调用 read 或 update,应改用提前维护的普通快照字段。

适用场景:组件内部响应式状态、多组件共享状态、父子组件协调(配合弱引用)、异步操作引起的状态变更、观察其他实体变化。

限制:资料未提供具体版本、平台、性能数据或收费信息;嵌套更新与渲染期实体访问会触发 panic,需按上述规则规避。