@feng3d/reactivity 1.0.5 → 1.0.6

package/src/baseHandlers.ts

@@ -7,74 +7,93 @@ import { PropertyReactivity } from './property';
 
 /**
  * 基础响应式处理器。
+ *
+ * 实现了 Proxy 的 get 拦截器，用于：
+ * 1. 响应式对象的标识和原始对象获取
+ * 2. 数组方法的特殊处理
+ * 3. 属性的依赖追踪
+ * 4. 值的自动解包和响应式转换
  */
 class BaseReactiveHandler implements ProxyHandler<Target>
 {
     /**
      * 获取对象的属性值。
      *
-     * @param target 对象本身
-     * @param key 属性名
-     * @param receiver 代理对象
-     * @returns
+     * 实现了以下功能：
+     * 1. 响应式对象标识检查
+     * 2. 原始对象获取
+     * 3. 数组方法拦截
+     * 4. 属性依赖追踪
+     * 5. 值的自动解包
+     * 6. 对象的自动响应式转换
+     *
+     * @param target 被代理的原始对象
+     * @param key 要获取的属性名
+     * @param receiver 代理对象本身
+     * @returns 获取到的属性值
      */
     get(target: Target, key: string | symbol, receiver: object): any
     {
-        //
-        if (key === ReactiveFlags.IS_REACTIVE) // 判断是否为响应式对象
+        // 检查是否为响应式对象
+        if (key === ReactiveFlags.IS_REACTIVE)
         {
             return true;
         }
-        else if (key === ReactiveFlags.RAW) // 获取原始对象
+        // 获取原始对象
+        else if (key === ReactiveFlags.RAW)
         {
             if (
-                receiver
-                === reactiveMap.get(target)
-                // receiver is not the reactive proxy, but has the same prototype
-                // this means the receiver is a user proxy of the reactive proxy
+                receiver === reactiveMap.get(target)
+                // receiver 不是响应式代理，但具有相同的原型
+                // 这意味着 receiver 是响应式代理的用户代理
                 || Object.getPrototypeOf(target) === Object.getPrototypeOf(receiver)
             )
             {
                 return target;
             }
-            // early return undefined
 
+            // 提前返回 undefined
             return;
         }
 
         const targetIsArray = isArray(target);
 
+        // 处理数组方法
         let fn: Function | undefined;
+
         if (targetIsArray && (fn = arrayInstrumentations[key]))
         {
             return fn;
         }
+        // 处理 hasOwnProperty 方法
         if (key === 'hasOwnProperty')
         {
             return hasOwnProperty;
         }
 
+        // 获取属性值
         const res = Reflect.get(
             target,
             key,
             isRef(target) ? target : receiver,
         );
 
+        // 跳过内置 Symbol 和非追踪键的依赖追踪
         if (isSymbol(key) ? builtInSymbols.has(key) : isNonTrackableKeys(key))
         {
             return res;
         }
 
-        //
+        // 追踪属性访问
         PropertyReactivity.track(target, TrackOpTypes.GET, key as any);
 
-        // 如果是 ref，则返回 ref.value
+        // 自动解包 ref 值
         if (isRef(res))
         {
             return targetIsArray && isIntegerKey(key) ? res : res.value;
         }
 
-        // 如果是对象，则递归响应式化
+        // 自动转换对象为响应式
         if (isObject(res))
         {
             return reactive(res);
@@ -86,16 +105,29 @@ class BaseReactiveHandler implements ProxyHandler<Target>
 
 /**
  * 可变响应式处理器。
+ *
+ * 继承自基础响应式处理器，增加了：
+ * 1. 属性设置拦截
+ * 2. 属性删除拦截
+ * 3. 属性存在性检查拦截
+ * 4. 属性遍历拦截
  */
 class MutableReactiveHandler extends BaseReactiveHandler
 {
     /**
      * 设置对象的属性值。
-     * @param target 被代理的对象。
-     * @param key 属性名。
-     * @param value 新值。
-     * @param receiver 代理对象。
-     * @returns 设置是否成功。
+     *
+     * 实现了以下功能：
+     * 1. 值的原始化处理
+     * 2. ref 值的特殊处理
+     * 3. 属性变更通知
+     * 4. 数组长度的特殊处理
+     *
+     * @param target 被代理的原始对象
+     * @param key 要设置的属性名
+     * @param value 要设置的新值
+     * @param receiver 代理对象本身
+     * @returns 设置是否成功
      */
     set(
         target: Record<string | symbol, unknown>,
@@ -106,9 +138,11 @@ class MutableReactiveHandler extends BaseReactiveHandler
     {
         let oldValue = target[key];
 
+        // 获取原始值进行比较
         oldValue = toRaw(oldValue);
         value = toRaw(value);
 
+        // 处理 ref 值的特殊情况
         if (!isArray(target) && isRef(oldValue) && !isRef(value))
         {
             oldValue.value = value;
@@ -116,6 +150,7 @@ class MutableReactiveHandler extends BaseReactiveHandler
             return true;
         }
 
+        // 检查属性是否存在
         const hadKey
             = isArray(target) && isIntegerKey(key)
                 ? Number(key) < target.length
@@ -126,18 +161,21 @@ class MutableReactiveHandler extends BaseReactiveHandler
             value,
             isRef(target) ? target : receiver,
         );
-        //
+
+        // 确保目标在原始原型链中
         __DEV__ && console.assert(target === toRaw(receiver));
 
-        // 如果目标在原始原型链中，则不要触发
+        // 触发属性变更通知
         if (target === toRaw(receiver))
         {
             if (!hadKey)
             {
+                // 新增属性
                 PropertyReactivity.trigger(target, TriggerOpTypes.ADD, key, value);
             }
             else if (hasChanged(value, oldValue))
             {
+                // 修改属性
                 PropertyReactivity.trigger(target, TriggerOpTypes.SET, key, value, oldValue);
             }
         }
@@ -148,9 +186,13 @@ class MutableReactiveHandler extends BaseReactiveHandler
     /**
      * 删除对象的属性。
      *
-     * @param target 被代理的对象。
-     * @param key 属性名。
-     * @returns 删除是否成功。
+     * 实现了以下功能：
+     * 1. 属性删除操作
+     * 2. 删除后的变更通知
+     *
+     * @param target 被代理的原始对象
+     * @param key 要删除的属性名
+     * @returns 删除是否成功
      */
     deleteProperty(
         target: Record<string | symbol, unknown>,
@@ -160,27 +202,53 @@ class MutableReactiveHandler extends BaseReactiveHandler
         const hadKey = hasOwn(target, key);
         const oldValue = target[key];
         const result = Reflect.deleteProperty(target, key);
+
         if (result && hadKey)
         {
+            // 触发删除通知
             PropertyReactivity.trigger(target, TriggerOpTypes.DELETE, key, undefined, oldValue);
         }
 
         return result;
     }
 
+    /**
+     * 检查对象是否包含某个属性。
+     *
+     * 实现了以下功能：
+     * 1. 属性存在性检查
+     * 2. 属性访问依赖追踪
+     *
+     * @param target 被代理的原始对象
+     * @param key 要检查的属性名
+     * @returns 属性是否存在
+     */
     has(target: Record<string | symbol, unknown>, key: string | symbol): boolean
     {
         const result = Reflect.has(target, key);
+
         if (!isSymbol(key) || !builtInSymbols.has(key))
         {
+            // 追踪属性访问
             PropertyReactivity.track(target, TrackOpTypes.HAS, key);
         }
 
         return result;
     }
 
+    /**
+     * 获取对象的所有属性名。
+     *
+     * 实现了以下功能：
+     * 1. 属性遍历
+     * 2. 遍历操作的依赖追踪
+     *
+     * @param target 被代理的原始对象
+     * @returns 对象的所有属性名数组
+     */
     ownKeys(target: Record<string | symbol, unknown>): (string | symbol)[]
     {
+        // 追踪遍历操作
         PropertyReactivity.track(
             target,
             TrackOpTypes.ITERATE,
@@ -192,29 +260,53 @@ class MutableReactiveHandler extends BaseReactiveHandler
 }
 
 /**
- * 可变响应式处理器。
+ * 可变响应式处理器实例。
+ *
+ * 用于创建可变的响应式对象。
  */
 export const mutableHandlers: ProxyHandler<object> = new MutableReactiveHandler();
 
+/**
+ * 自定义 hasOwnProperty 方法。
+ *
+ * 实现了以下功能：
+ * 1. 属性存在性检查
+ * 2. 属性访问依赖追踪
+ *
+ * @param this 调用对象
+ * @param key 要检查的属性名
+ * @returns 属性是否存在
+ */
 function hasOwnProperty(this: object, key: unknown)
 {
-    // #10455 hasOwnProperty may be called with non-string values
+    // #10455 hasOwnProperty 可能被非字符串值调用
     if (!isSymbol(key)) key = String(key);
     const obj = toRaw(this);
+
+    // 追踪属性访问
     PropertyReactivity.track(obj, TrackOpTypes.HAS, key);
 
     return obj.hasOwnProperty(key as string);
 }
 
+/**
+ * 内置 Symbol 集合。
+ *
+ * 用于过滤不需要追踪的 Symbol 属性。
+ */
 const builtInSymbols = new Set(
-    /* @__PURE__*/
+    /* @__PURE__ */
     Object.getOwnPropertyNames(Symbol)
-        // ios10.x Object.getOwnPropertyNames(Symbol) can enumerate 'arguments' and 'caller'
-        // but accessing them on Symbol leads to TypeError because Symbol is a strict mode
-        // function
+        // ios10.x Object.getOwnPropertyNames(Symbol) 可以枚举 'arguments' 和 'caller'
+        // 但在 Symbol 上访问它们会导致 TypeError，因为 Symbol 是严格模式函数
         .filter((key) => key !== 'arguments' && key !== 'caller')
         .map((key) => Symbol[key as keyof SymbolConstructor])
         .filter(isSymbol),
 );
 
-const isNonTrackableKeys = /* @__PURE__*/ makeMap(`__proto__,__v_isRef,__isVue`);
+/**
+ * 非追踪键集合。
+ *
+ * 用于过滤不需要追踪的属性名。
+ */
+const isNonTrackableKeys = /* @__PURE__ */ makeMap(`__proto__,__v_isRef,__isVue`);

package/src/batch.ts

@@ -2,10 +2,14 @@ import { ComputedReactivity } from './computed';
 import { Reactivity } from './Reactivity';
 
 /**
- * 合批处理。
+ * 合批处理依赖。
  *
- * @param dep 要处理的依赖。
- * @param isRunning 添加时是否是正在运行。
+ * 将依赖添加到待处理队列中，根据依赖的运行状态决定处理方式：
+ * 1. 如果依赖正在运行，添加到已运行队列
+ * 2. 如果依赖未运行，添加到待运行队列
+ *
+ * @param dep 要处理的依赖
+ * @param isRunning 依赖是否正在运行
  */
 export function batch(dep: ComputedReactivity, isRunning: boolean): void
 {
@@ -20,8 +24,15 @@ export function batch(dep: ComputedReactivity, isRunning: boolean): void
 }
 
 /**
- * 批次执行多次修改反应式对象，可以减少不必要的反应式触发。
+ * 批次执行多次修改反应式对象。
+ *
+ * 将多个响应式更新合并为一个批次执行，可以减少不必要的反应式触发。
+ * 在批次执行期间：
+ * 1. 所有响应式更新都会被收集
+ * 2. 批次结束后统一处理所有更新
+ * 3. 避免中间状态触发不必要的更新
  *
+ * 示例：
  * ```ts
  * batchRun(() => {
  *     // 修改反应式对象
@@ -30,7 +41,8 @@ export function batch(dep: ComputedReactivity, isRunning: boolean): void
  * })
  * ```
  *
- * @param fn 要执行的函数，在此函数中多次修改反应式对象。
+ * @param fn 要执行的函数，在此函数中多次修改反应式对象
+ * @returns 函数的执行结果
  */
 export function batchRun<T>(fn: () => T): T
 {
@@ -43,12 +55,12 @@ export function batchRun<T>(fn: () => T): T
         return;
     }
 
-    // 处理已经运行过的依赖，
+    // 处理已经运行过的依赖
     if (_isRunedDeps.length > 0)
     {
         _isRunedDeps.forEach((dep) =>
         {
-            // 此时依赖以及子依赖都已经运行过了，只需修复与子节点关系。
+            // 此时依赖以及子依赖都已经运行过了，只需修复与子节点关系
             __DEV__ && console.assert(dep._isDirty === false, 'dep.dirty === false');
 
             // 修复与子节点关系
@@ -61,13 +73,14 @@ export function batchRun<T>(fn: () => T): T
         _isRunedDeps.length = 0;
     }
 
-    // 批次处理
+    // 批次处理待运行的依赖
     if (_needEffectDeps.length > 0)
     {
         _needEffectDeps.forEach((dep) =>
         {
-            // 独立执行回调
+            // 独立执行回调，避免影响其他依赖
             const pre = Reactivity.activeReactivity;
+
             Reactivity.activeReactivity = null;
 
             dep.runIfDirty();
@@ -80,12 +93,26 @@ export function batchRun<T>(fn: () => T): T
     return result;
 }
 
+/**
+ * 批次深度。
+ *
+ * 用于跟踪嵌套的批次执行。
+ * 当深度大于 0 时，表示当前正在批次执行中。
+ */
 let _batchDepth = 0;
+
 /**
- * 正在运行的依赖。
+ * 待运行的依赖队列。
+ *
+ * 存储需要执行但尚未执行的依赖。
+ * 在批次执行结束后，会统一处理这些依赖。
  */
 const _needEffectDeps: ComputedReactivity[] = [];
+
 /**
- * 已经运行过的依赖，只需要修复与子节点关系。
+ * 已运行的依赖队列。
+ *
+ * 存储已经执行过的依赖。
+ * 这些依赖只需要修复与子节点的关系，不需要重新执行。
  */
 const _isRunedDeps: ComputedReactivity[] = [];