feat: add the useSelector hook to support selecting aggregated values from the form, and integrate the UseSelector component in the example to demonstrate its usage.

Ohh-889 · Ohh-889 · commit 057f18cf6b57 · 2025-09-23T07:30:47.000+08:00
diff --git a/packages/ui/src/components/form/index.ts b/packages/ui/src/components/form/index.ts
@@ -4,9 +4,11 @@ export {
   ComputedField as FormComputedField,
   Form,
   List as FormList,
+  useEffectField,
   useFieldError,
   useFieldState,
   useForm,
+  useSelector,
   useWatch
 } from 'skyroc-form';
 
diff --git a/playground/src/app/(demo)/form/modules/UseSelector.tsx b/playground/src/app/(demo)/form/modules/UseSelector.tsx
@@ -0,0 +1,171 @@
+'use client';
+
+import type { FormInstance } from 'soybean-react-ui';
+import { Button, Card, Form, FormField, Input, useForm, useSelector } from 'soybean-react-ui';
+
+import { showToastCode } from './toast';
+
+type Inputs = {
+  confirmPassword: string;
+  info: {
+    age: number;
+    familyInfo: {
+      phone: string;
+    };
+    gender: string;
+    hobbies: string;
+  };
+  password: string;
+  username: string;
+};
+
+const SelectorEffect = ({ form }: { form: FormInstance<Inputs> }) => {
+  // 1. Single-field selection: only listen to username
+  const username = useSelector(get => get('username'), { deps: ['username'], form });
+
+  // 2. Multi-field combination: watch password & confirmPassword
+  const passwordsMatch = useSelector(
+    get => {
+      const pass = get('password');
+      const confirm = get('confirmPassword');
+      return pass && confirm && pass === confirm;
+    },
+    { deps: ['password', 'confirmPassword'], form }
+  );
+
+  // 3. Deep dependency: watch info.age
+  const age = useSelector(get => get('info.age'), { deps: ['info.age'], form });
+
+  // 4. Complex selection: username + age combination
+  const userSummary = useSelector(
+    (get, all) => ({
+      age: get('info.age'),
+      name: get('username'),
+      phone: all.info?.familyInfo?.phone
+    }),
+    { deps: ['username', 'info.age', 'info.familyInfo.phone'], form }
+  );
+
+  console.log('username', username);
+  console.log('passwordsMatch', passwordsMatch);
+  console.log('age', age);
+  console.log('userSummary', userSummary);
+
+  return null;
+};
+
+const initialValues: Inputs = {
+  confirmPassword: '123456',
+  info: {
+    age: 24,
+    familyInfo: { phone: '110' },
+    gender: 'male',
+    hobbies: 'play lol'
+  },
+  password: '123456',
+  username: 'ohh'
+};
+
+const UseSelectorDemo = () => {
+  const [form] = useForm<Inputs>();
+
+  const setValues = () => {
+    form.setFieldsValue({
+      confirmPassword: 'abc123',
+      info: { age: 30, gender: 'female', hobbies: 'reading' },
+      password: 'abc123',
+      username: 'new_user'
+    });
+  };
+
+  const setWrongConfirm = () => {
+    form.setFieldValue('confirmPassword', 'wrong_pass');
+  };
+
+  const setPhone = () => {
+    form.setFieldValue('info.familyInfo.phone', '1234567890');
+  };
+
+  const getSummary = () => {
+    const values = form.getFieldsValue();
+    showToastCode('Summary', values);
+  };
+
+  return (
+    <Card title="UseSelector Demo">
+      <Form
+        className="w-[480px] max-sm:w-full space-y-4"
+        form={form}
+        initialValues={initialValues}
+      >
+        <FormField
+          label="Username"
+          name="username"
+        >
+          <Input />
+        </FormField>
+
+        <FormField
+          label="Password"
+          name="password"
+        >
+          <Input type="password" />
+        </FormField>
+
+        <FormField
+          label="Confirm Password"
+          name="confirmPassword"
+        >
+          <Input type="password" />
+        </FormField>
+
+        <FormField
+          label="Info Age"
+          name="info.age"
+        >
+          <Input type="number" />
+        </FormField>
+
+        <FormField
+          label="Info Phone"
+          name="info.familyInfo.phone"
+        >
+          <Input />
+        </FormField>
+
+        <div className="flex gap-2 flex-wrap">
+          <Button
+            type="button"
+            onClick={setValues}
+          >
+            Set Values
+          </Button>
+          <Button
+            type="button"
+            onClick={setWrongConfirm}
+          >
+            Set Wrong Confirm
+          </Button>
+          <Button
+            type="button"
+            onClick={setPhone}
+          >
+            Set Phone
+          </Button>
+          <Button
+            type="button"
+            onClick={getSummary}
+          >
+            Get All Values
+          </Button>
+          <Button type="submit">Submit</Button>
+        </div>
+      </Form>
+
+      {/* Observe dependency changes of useSelector */}
+      <SelectorEffect form={form} />
+    </Card>
+  );
+};
+
+export default UseSelectorDemo;
diff --git a/playground/src/app/(demo)/form/page.tsx b/playground/src/app/(demo)/form/page.tsx
@@ -6,6 +6,7 @@ import List from './modules/List';
 import Preserve from './modules/Preserve';
 import Reset from './modules/Reset';
 import UseForm from './modules/UseForm';
+import UseSelector from './modules/UseSelector';
 import UseWatch from './modules/UseWatch';
 import Validate from './modules/validate';
 import ValidateWarning from './modules/validateWaring';
@@ -29,6 +30,8 @@ const FormPage = () => {
 
       <UseWatch />
 
+      <UseSelector />
+
       <Reset />
 
       <Preserve />
diff --git a/primitives/filed-form /src/react/hooks/useSelector.ts b/primitives/filed-form /src/react/hooks/useSelector.ts
@@ -1,55 +1,83 @@
-// useSelector.ts
 'use client';
-import * as React from 'react';
-import { useSyncExternalStore } from 'react';
+/* eslint-disable no-bitwise */
+import { useEffect, useRef, useState } from 'react';
+import { flushSync } from 'react-dom';
+import type { AllPathsKeys } from 'skyroc-type-utils';
+
+import type { ChangeMask } from '../../form-core/event';
+import { ChangeTag } from '../../form-core/event';
 
 import { useFieldContext } from './FieldContext';
-import type { ChangeMask } from './events';
-import { ChangeTag } from './events';
-import type { NamePath } from './types';
+import type { FormInstance, InternalFormInstance } from './FieldContext';
 
 type Eq<T> = (a: T, b: T) => boolean;
 
-export function useSelector<T>(
-  selector: (get: (n: NamePath) => any, all: any) => T,
-  eq: Eq<T> = Object.is,
-  opt?: { mask?: ChangeMask; names?: NamePath[] }
-): T {
-  const form = useFieldContext();
-  const mask = opt?.mask ?? ChangeTag.Value | ChangeTag.Errors | ChangeTag.Validating;
-  const names = opt?.names || [];
-
-  const getSel = React.useCallback(
-    () => selector(form.getFieldValue.bind(form), form.getFieldsValue()),
-    [form, selector]
-  );
-
-  const subscribe = React.useCallback(
-    (on: () => void) => {
-      if (!names.length) {
-        // 全局订阅：任意字段改变都试着比较
-        return form.__store.subscribeField([], () => on(), { includeChildren: true, mask });
+type UseSelectorOpts<Values, R> = {
+  /** 订阅字段，空则订阅全部 */
+  deps?: AllPathsKeys<Values>[];
+  /** 是否相等 */
+  eq?: Eq<R>;
+  /** 表单实例 */
+  form?: FormInstance<Values>;
+  /** 是否订阅子路径 */
+  includeChildren?: boolean;
+  /** 变更掩码 */
+  mask?: ChangeMask;
+};
+
+/**
+ * 从表单中“选择”任意聚合值，只有依赖变化才刷新。
+ */
+export function useSelector<Values = any, R = unknown>(
+  selector: (get: (n: AllPathsKeys<Values>) => any, all: Values) => R,
+  opts?: UseSelectorOpts<Values, R>
+): R {
+  const ctxForm = useFieldContext<Values>();
+  const form = opts?.form ?? ctxForm;
+
+  const eq = opts?.eq ?? Object.is;
+
+  if (!form) {
+    throw new Error('Can not find FormContext. Please make sure you wrap Field under Form or provide a form instance.');
+  }
+
+  const { getInternalHooks } = form as unknown as InternalFormInstance<Values>;
+  const { subscribeField } = getInternalHooks();
+
+  const deps = opts?.deps;
+
+  const mask = opts?.mask ?? ChangeTag.Value;
+  const includeChildren = opts?.includeChildren;
+
+  // 计算当前选择值
+  const compute = () => {
+    const getField = form.getFieldValue;
+    const all = form.getFieldsValue() as Values;
+    return selector(getField, all);
+  };
+
+  // state + ref 用于去抖渲染
+  const [val, setVal] = useState<R>(compute);
+
+  const prevRef = useRef<R>(val);
+
+  useEffect(() => {
+    // 订阅器
+    const onChange = () => {
+      const next = compute();
+      if (!eq(prevRef.current, next)) {
+        prevRef.current = next;
+        // 与 useFieldState 一致：同步刷新，减少闪烁
+        flushSync(() => setVal(next));
       }
-      const offs = names.map(n => form.__store.subscribeField(n, () => on(), { includeChildren: true, mask }));
-      return () => offs.forEach(f => f());
-    },
-    [form, names.map(String).join('|'), mask]
-  );
-
-  const getSnap = React.useRef<T>(getSel());
-  const getSnapshot = () => getSnap.current;
-  const serverSnapshot = getSnapshot;
-
-  useSyncExternalStore(
-    subscribe,
-    () => {
-      const next = getSel();
-      const prev = getSnap.current;
-      if (!eq(prev, next)) getSnap.current = next;
-      return getSnap.current;
-    },
-    serverSnapshot
-  );
-
-  return getSnap.current;
+    };
+
+    // 指定字段订阅
+    return subscribeField(deps, onChange, {
+      includeChildren,
+      mask
+    });
+  }, []);
+
+  return val;
 }
diff --git a/primitives/filed-form /src/react/index.ts b/primitives/filed-form /src/react/index.ts
@@ -16,10 +16,14 @@ export * from './hooks/FieldContext';
 
 export { useArrayField } from './hooks/useFieldArray';
 
+export { useEffectField } from './hooks/useFieldEffect';
+
 export { useFieldError } from './hooks/useFieldError';
 
 export { useFieldState } from './hooks/useFieldState';
 
 export { useForm } from './hooks/useForm';
 
+export { useSelector } from './hooks/useSelector';
+
 export { useWatch } from './hooks/useWatch';
