@feng3d/reactivity 1.0.5 → 1.0.7

package/src/computed.ts

@@ -4,10 +4,10 @@ import { Reactivity, forceTrack } from './Reactivity';
 /**
  * 创建计算反应式对象。
  *
- * 首次获取值将会执行函数，后续获取值且在依赖发生变化的情况下将会重新计算。
+ * 计算属性会缓存计算结果，只有当依赖发生变化时才会重新计算。
  *
- * @param func 检测的可能包含响应式的函数。
- * @returns 包含 value 属性的对象，用于获取计算结果。
+ * @param func 计算函数，可以访问其他响应式数据，并返回计算结果
+ * @returns 包含 value 属性的计算属性对象
  */
 export function computed<T>(func: (oldValue?: T) => T): Computed<T>
 {
@@ -15,7 +15,11 @@ export function computed<T>(func: (oldValue?: T) => T): Computed<T>
 }
 
 /**
- * 计算反应式对象。
+ * 计算属性接口。
+ *
+ * 定义了计算属性的基本结构：
+ * 1. value: 计算属性的当前值
+ * 2. ComputedSymbol: 用于标识这是一个计算属性
  */
 export interface Computed<T = any>
 {
@@ -24,38 +28,56 @@ export interface Computed<T = any>
 }
 declare const ComputedSymbol: unique symbol;
 
+/**
+ * 计算反应式节点接口。
+ *
+ * 继承自 Computed 接口，表示这是一个计算反应式节点。
+ */
 export interface ComputedReactivity<T = any> extends Computed<T> { }
 
 /**
- * 计算反应式节点。
- *
- * 当使用 computed 函数时，会创建一个 ComputedDep 对象。
+ * 计算反应式节点类。
  *
- * 首次获取值将会执行函数，后续获取值且在依赖发生变化的情况下将会重新计算。
+ * 当使用 computed 函数时，会创建一个 ComputedReactivity 对象。
+ * 实现了计算属性的核心功能：
+ * 1. 缓存计算结果
+ * 2. 按需重新计算
+ * 3. 依赖追踪
+ * 4. 变更通知
  */
 export class ComputedReactivity<T = any> extends Reactivity<T>
 {
     /**
+     * 标识这是一个 ref 对象。
+     *
      * @internal
      */
     readonly __v_isRef = true;
 
     /**
-     * 监听的函数。
+     * 计算函数。
+     *
+     * 用于计算属性值的函数，可以访问其他响应式数据。
+     * 当依赖发生变化时，会重新执行此函数。
      */
     protected _func: (oldValue?: T) => T;
 
     /**
-     * 失效子节点。
+     * 失效子节点集合。
+     *
+     * 记录所有依赖此计算属性的子节点。
+     * 当计算属性重新计算时，会通知这些子节点。
      *
      * @private
      */
     _children = new Map<Reactivity, any>();
 
     /**
-     * 是否脏，是否需要重新计算。
+     * 脏标记。
      *
-     * 用于在没有值发生变化时，避免重复计算。
+     * 表示计算属性是否需要重新计算。
+     * 当依赖发生变化时，会设置此标记。
+     * 重新计算后会清除此标记。
      *
      * @private
      */
@@ -64,31 +86,34 @@ export class ComputedReactivity<T = any> extends Reactivity<T>
     /**
      * 版本号。
      *
-     * 重新计算后自动递增。用于判断子节点中的父节点引用是否过期。
+     * 每次重新计算后自动递增。
+     * 用于判断子节点中的父节点引用是否过期。
+     * 当子节点发现父节点的版本号不匹配时，会重新建立依赖关系。
      *
      * @private
      */
     _version = -1;
 
     /**
-     * 获取值。
+     * 获取计算属性的值。
      *
-     * 取值时将会建立与父节点的依赖关系。
-     *
-     * 同时会检查子节点是否发生变化，如果发生变化，则重新计算。
+     * 取值时会：
+     * 1. 检查是否需要重新计算
+     * 2. 建立与父节点的依赖关系
+     * 3. 返回当前值
      */
     get value(): T
     {
         this.runIfDirty();
-
         this.track();
 
         return this._value;
     }
 
     /**
-     * 创建计算依赖。
-     * @param func 检测的可能包含响应式的函数。
+     * 创建计算反应式节点。
+     *
+     * @param func 计算函数，可以访问其他响应式数据，并返回计算结果
      */
     constructor(func: (oldValue?: T) => T)
     {
@@ -97,15 +122,15 @@ export class ComputedReactivity<T = any> extends Reactivity<T>
     }
 
     /**
-     * 触发。
-     *
-     * 冒泡到所有父节点，设置失效子节点字典。
+     * 触发更新。
      *
-     * 把触发节点添加到失效子节点字典队列中。
+     * 当依赖发生变化时，会调用此方法。
+     * 如果当前正在执行计算，会将更新延迟到计算完成后。
+     * 否则，立即通知所有父节点进行更新。
      */
     trigger(): void
     {
-        // 正在运行时被触发，需要在运行结束后修复父子节点关系。
+        // 正在运行时被触发，需要在运行结束后修复父子节点关系
         if (Reactivity.activeReactivity === this)
         {
             batch(this, Reactivity.activeReactivity === this);
@@ -115,75 +140,99 @@ export class ComputedReactivity<T = any> extends Reactivity<T>
     }
 
     /**
-     * 执行当前节点。
+     * 执行计算。
+     *
+     * 执行计算函数，更新当前值。
+     * 在计算过程中会：
+     * 1. 强制启用依赖跟踪
+     * 2. 保存并设置当前活动节点
+     * 3. 执行计算函数
+     * 4. 恢复活动节点
      */
     run()
     {
-        // 不受嵌套的 effect 影响。
+        // 不受嵌套的 effect 影响
         forceTrack(() =>
         {
-            // 保存当前节点作为父节点。
+            // 保存当前节点作为父节点
             const parentReactiveNode = Reactivity.activeReactivity;
-            // 设置当前节点为活跃节点。
+
+            // 设置当前节点为活跃节点
             Reactivity.activeReactivity = this as any;
 
             this._version++;
             this._value = this._func(this._value);
 
-            // 执行完毕后恢复父节点。
+            // 执行完毕后恢复父节点
             Reactivity.activeReactivity = parentReactiveNode;
         });
     }
 
     /**
-     * 检查当前节点是否脏。
+     * 检查并执行计算。
+     *
+     * 检查当前节点是否需要重新计算：
+     * 1. 如果脏标记为 true，需要重新计算
+     * 2. 如果子节点发生变化，需要重新计算
      *
-     * 如果脏，则执行计算。
+     * 重新计算后会清除脏标记。
      */
     runIfDirty()
     {
-        // 检查是否存在失效子节点字典。
+        // 检查是否存在失效子节点字典
         this._isDirty = this._isDirty || this.isChildrenChanged();
 
-        // 标记为脏的情况下，执行计算。
+        // 标记为脏的情况下，执行计算
         if (this._isDirty)
         {
-            // 立即去除脏标记，避免循环多重计算。
+            // 立即去除脏标记，避免循环多重计算
             this._isDirty = false;
 
-            //
+            // 执行计算
             this.run();
         }
     }
 
     /**
-     * 判断子节点是否发生变化。
+     * 检查子节点是否发生变化。
+     *
+     * 遍历所有子节点，检查它们的值是否发生变化。
+     * 如果发生变化，返回 true，否则返回 false。
+     *
+     * 在检查过程中会：
+     * 1. 临时禁用依赖跟踪
+     * 2. 检查每个子节点的值
+     * 3. 如果子节点没有变化，重新建立依赖关系
+     * 4. 清空子节点集合
+     *
+     * @returns 是否有子节点发生变化
      */
     protected isChildrenChanged()
     {
         if (this._children.size === 0) return false;
 
-        // 检查是否存在子节点发生变化。
+        // 检查是否存在子节点发生变化
         let isChanged = false;
 
-        // 避免在检查过程建立依赖关系。
+        // 避免在检查过程建立依赖关系
         const preReactiveNode = Reactivity.activeReactivity;
+
         Reactivity.activeReactivity = null;
 
-        // 检查子节点是否发生变化。
+        // 检查子节点是否发生变化
         this._children.forEach((value, node) =>
         {
             if (isChanged) return;
             if (node.value !== value)
             {
-                // 子节点变化，需要重新计算。
+                // 子节点变化，需要重新计算
                 isChanged = true;
 
                 return;
             }
         });
 
-        // 恢复父节点。
+        // 恢复父节点
         Reactivity.activeReactivity = preReactiveNode;
 
         if (!isChanged)
@@ -195,7 +244,7 @@ export class ComputedReactivity<T = any> extends Reactivity<T>
             });
         }
 
-        // 清空子节点。
+        // 清空子节点
         this._children.clear();
 
         return isChanged;

package/src/effect.ts

@@ -1,5 +1,6 @@
 import { batch, batchRun } from './batch';
 import { ComputedReactivity } from './computed';
+import { activeEffectScope } from './effectScope';
 import { Reactivity } from './Reactivity';
 
 /**
@@ -36,14 +37,28 @@ export class EffectReactivity<T = any> extends ComputedReactivity<T> implements
     constructor(func: (oldValue?: T) => T)
     {
         super(func);
+        if (activeEffectScope && activeEffectScope.active)
+        {
+            activeEffectScope.effects.push(this);
+        }
         this.runIfDirty();
     }
 
+    /**
+     * 暂停效果。
+     *
+     * 暂停后，当依赖发生变化时不会自动执行。
+     */
     pause()
     {
         this._isEnable = false;
     }
 
+    /**
+     * 恢复效果。
+     *
+     * 恢复后，当依赖发生变化时会自动执行。
+     */
     resume()
     {
         if (this._isEnable) return;
@@ -55,6 +70,22 @@ export class EffectReactivity<T = any> extends ComputedReactivity<T> implements
         }
     }
 
+    /**
+     * 停止效果。
+     *
+     * 停止后，效果将不再响应依赖的变化。
+     */
+    stop()
+    {
+        this._isEnable = false;
+        EffectReactivity.pausedQueueEffects.delete(this);
+    }
+
+    /**
+     * 触发效果执行。
+     *
+     * 当依赖发生变化时，会调用此方法。
+     */
     trigger()
     {
         batchRun(() =>
@@ -72,6 +103,7 @@ export class EffectReactivity<T = any> extends ComputedReactivity<T> implements
             }
         });
     }
+
     private static pausedQueueEffects = new WeakSet<EffectReactivity>();
 
     /**
@@ -101,8 +133,14 @@ export interface Effect
      * 暂停。
      */
     pause: () => void;
+
     /**
      * 恢复。
      */
     resume: () => void;
+
+    /**
+     * 停止。
+     */
+    stop: () => void;
 }

package/src/effectScope.ts

@@ -0,0 +1,294 @@
+import type { Effect as ReactiveEffect } from './effect';
+import { warn } from './shared/general';
+
+/**
+ * 当前活动的效果作用域
+ */
+export let activeEffectScope: EffectScope | undefined;
+
+/**
+ * 效果作用域类
+ *
+ * 用于管理一组相关的响应式效果，可以统一控制它们的生命周期。
+ */
+export class EffectScope
+{
+    /**
+     * 作用域是否处于活动状态
+     * @internal
+     */
+    private _active = true;
+    /**
+     * 跟踪 on 方法的调用次数，允许多次调用 on 方法
+     * @internal
+     */
+    private _on = 0;
+    /**
+     * 存储当前作用域中的所有效果
+     * @internal
+     */
+    effects: ReactiveEffect[] = [];
+    /**
+     * 存储清理函数
+     * @internal
+     */
+    cleanups: (() => void)[] = [];
+
+    /**
+     * 作用域是否被暂停
+     */
+    private _isPaused = false;
+
+    /**
+     * 父作用域，仅由非分离的作用域分配
+     * @internal
+     */
+    parent: EffectScope | undefined;
+    /**
+     * 记录未分离的子作用域
+     * @internal
+     */
+    scopes: EffectScope[] | undefined;
+    /**
+     * 在父作用域的 scopes 数组中记录子作用域的索引，用于优化移除操作
+     * @internal
+     */
+    private index: number | undefined;
+
+    /**
+     * 构造函数
+     * @param detached 是否创建分离的作用域
+     */
+    constructor(public detached = false)
+    {
+        this.parent = activeEffectScope;
+        if (!detached && activeEffectScope)
+        {
+            this.index =
+                (activeEffectScope.scopes || (activeEffectScope.scopes = [])).push(
+                    this,
+                ) - 1;
+        }
+    }
+
+    /**
+     * 获取作用域是否处于活动状态
+     */
+    get active(): boolean
+    {
+        return this._active;
+    }
+
+    /**
+     * 暂停作用域
+     *
+     * 暂停当前作用域及其所有子作用域和效果
+     */
+    pause(): void
+    {
+        if (this._active)
+        {
+            this._isPaused = true;
+            let i: number, l: number;
+
+            if (this.scopes)
+            {
+                for (i = 0, l = this.scopes.length; i < l; i++)
+                {
+                    this.scopes[i].pause();
+                }
+            }
+            for (i = 0, l = this.effects.length; i < l; i++)
+            {
+                this.effects[i].pause();
+            }
+        }
+    }
+
+    /**
+     * 恢复作用域
+     *
+     * 恢复当前作用域及其所有子作用域和效果
+     */
+    resume(): void
+    {
+        if (this._active)
+        {
+            if (this._isPaused)
+            {
+                this._isPaused = false;
+                let i: number, l: number;
+
+                if (this.scopes)
+                {
+                    for (i = 0, l = this.scopes.length; i < l; i++)
+                    {
+                        this.scopes[i].resume();
+                    }
+                }
+                for (i = 0, l = this.effects.length; i < l; i++)
+                {
+                    this.effects[i].resume();
+                }
+            }
+        }
+    }
+
+    /**
+     * 在作用域中运行函数
+     * @param fn 要运行的函数
+     * @returns 函数的返回值
+     */
+    run<T>(fn: () => T): T | undefined
+    {
+        if (this._active)
+        {
+            const currentEffectScope = activeEffectScope;
+
+            try
+            {
+                activeEffectScope = this;
+
+                return fn();
+            }
+            finally
+            {
+                activeEffectScope = currentEffectScope;
+            }
+        }
+        else if (__DEV__)
+        {
+            warn(`cannot run an inactive effect scope.`);
+        }
+    }
+
+    /**
+     * 前一个作用域
+     */
+    prevScope: EffectScope | undefined;
+    /**
+     * 激活作用域
+     * 仅应在非分离的作用域上调用
+     * @internal
+     */
+    on(): void
+    {
+        if (++this._on === 1)
+        {
+            this.prevScope = activeEffectScope;
+            activeEffectScope = this;
+        }
+    }
+
+    /**
+     * 停用作用域
+     * 仅应在非分离的作用域上调用
+     * @internal
+     */
+    off(): void
+    {
+        if (this._on > 0 && --this._on === 0)
+        {
+            activeEffectScope = this.prevScope;
+            this.prevScope = undefined;
+        }
+    }
+
+    /**
+     * 停止作用域
+     *
+     * 停止当前作用域及其所有子作用域和效果，并执行清理函数
+     * @param fromParent 是否由父作用域调用
+     */
+    stop(fromParent?: boolean): void
+    {
+        if (this._active)
+        {
+            this._active = false;
+            let i: number, l: number;
+
+            for (i = 0, l = this.effects.length; i < l; i++)
+            {
+                this.effects[i].stop();
+            }
+            this.effects.length = 0;
+
+            for (i = 0, l = this.cleanups.length; i < l; i++)
+            {
+                this.cleanups[i]();
+            }
+            this.cleanups.length = 0;
+
+            if (this.scopes)
+            {
+                for (i = 0, l = this.scopes.length; i < l; i++)
+                {
+                    this.scopes[i].stop(true);
+                }
+                this.scopes.length = 0;
+            }
+
+            // 嵌套作用域，从父作用域中解除引用以避免内存泄漏
+            if (!this.detached && this.parent && !fromParent)
+            {
+                // 优化的 O(1) 移除
+                const last = this.parent.scopes!.pop();
+
+                if (last && last !== this)
+                {
+                    this.parent.scopes![this.index!] = last;
+                    last.index = this.index!;
+                }
+            }
+            this.parent = undefined;
+        }
+    }
+}
+
+/**
+ * 创建效果作用域对象
+ *
+ * 可以捕获在其中创建的响应式效果（即计算属性和观察者），以便这些效果可以一起处理。
+ *
+ * @param detached 是否创建分离的作用域
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#effectscope}
+ */
+export function effectScope(detached?: boolean): EffectScope
+{
+    return new EffectScope(detached);
+}
+
+/**
+ * 获取当前活动的效果作用域
+ *
+ * @returns 当前活动的效果作用域，如果没有则返回 undefined
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#getcurrentscope}
+ */
+export function getCurrentScope(): EffectScope | undefined
+{
+    return activeEffectScope;
+}
+
+/**
+ * 在当前活动的效果作用域上注册清理回调
+ *
+ * 当关联的效果作用域停止时，将调用此回调函数。
+ *
+ * @param fn 要附加到作用域清理的回调函数
+ * @param failSilently 是否静默失败
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#onscopedispose}
+ */
+export function onScopeDispose(fn: () => void, failSilently = false): void
+{
+    if (activeEffectScope)
+    {
+        activeEffectScope.cleanups.push(fn);
+    }
+    else if (__DEV__ && !failSilently)
+    {
+        warn(
+            `onScopeDispose() is called when there is no active effect scope` +
+            ` to be associated with.`,
+        );
+    }
+}

package/src/index.ts

@@ -1,8 +1,9 @@
 export { batchRun } from './batch';
-export { ComputedReactivity as ComputedDep, computed, type Computed } from './computed';
-export { Reactivity as Dep, forceTrack, noTrack } from './Reactivity';
-export { EffectReactivity as EffectDep, effect, type Effect } from './effect';
-export { isProxy, isReactive, reactive, type Reactive } from './reactive';
-export { RefReactivity, isRef, ref, type Ref } from './ref';
+export { computed, type Computed } from './computed';
+export { effect, type Effect } from './effect';
+export { effectScope, EffectScope, getCurrentScope, onScopeDispose } from './effectScope';
+export { isProxy, isReactive, reactive, type Reactive, type UnReadonly } from './reactive';
+export { forceTrack, noTrack } from './Reactivity';
+export { isRef, ref, type Ref } from './ref';
 export { toRaw } from './shared/general';