react-admin useFieldValue Hook 完整解析:从 RecordContext 安全读取字段值的官方工具
react-admin useFieldValue Hook 完整解析:从 RecordContext 安全读取字段值的官方工具
useFieldValue 是 react-admin 提供给字段(Field)组件开发者的核心 Hook,它负责从当前记录(Record)中按 source 路径取出字段值,并优先支持从组件 props 覆盖记录对象。本文基于 react-admin 仓库源码(packages/ra-core/src/util/useFieldValue.ts)与官方文档 docs/useFieldValue.md,带你掌握该 Hook 的全部参数、底层实现原理、类型安全机制,以及如何用它与内置字段组件保持一致的取值行为。
一、为什么需要 useFieldValue
在 react-admin 中,字段组件(如 TextField、NumberField)并不直接接收记录数据,而是通过 React Context 共享当前记录。当你要编写自定义字段组件时,最自然的做法是调用 useRecordContext() 手动取记录、再自行读取字段值:
const MyField = () => {
const record = useRecordContext();
return <span>{record && record[props.source]}</span>;
};
这种写法存在三个痛点:
- 无法处理深路径:当
source为"author.name"这类嵌套路径时,你需要自己递归取值; - 无法优雅处理缺省值:记录中不存在该字段时,需要手工做空值判断;
- 无法复用组件:字段组件通常希望允许调用方通过
record属性显式传入记录(例如在Datagrid之外单独渲染),而 Context 方案无法兼顾 props 覆盖。
useFieldValue 将这三件事统一封装为一个 Hook。文档中给出的官方定义是:"A hook that gets the value of a field of the current record. It gets the current record from the context or use the one provided as a prop. It supports deep sources such as name.fr."(获取当前记录的字段值;记录取自 Context,也可通过 prop 指定;支持 name.fr 这样的深路径。)
二、基本用法:一分钟写出自定义字段
useFieldValue 接收一个参数对象,返回该字段的值。最典型的用法是让自定义字段组件直接透传自己的 props(因为字段组件的 props 本身就包含 source、record 等字段):
// In TextField.tsx
import * as React from 'react';
import { useFieldValue, type FieldProps } from 'react-admin';
export const TextField = (props: FieldProps) => {
const value = useFieldValue(props);
return <span>{value}</span>;
}
在展示视图(Show)中把它当作普通字段使用,source 支持深路径:
// In PostShow.tsx
import { Show, SimpleShowLayout } from 'react-admin';
import { TextField } from './TextField.tsx';
export const PostShow = () => (
<Show>
<SimpleShowLayout>
<TextField source="author.name" label="Author" />
</SimpleShowLayout>
</Show>
);
当 PostShow 渲染时,<Show> 组件会通过 ShowContextProvider 向子树注入当前帖子记录,useFieldValue({ source: 'author.name' }) 便能在深层嵌套的 SimpleShowLayout 中拿到 record.author.name 的值。
从源码看,packages/ra-core/src/util/useFieldValue.ts 的实现非常精简:
export const useFieldValue = <RecordType extends Record<string, any> = Record<string, any>>(
params: UseFieldValueOptions<RecordType>
) => {
const { defaultValue, source } = params;
const record = useRecordContext<RecordType>(params);
return get(record, source, defaultValue);
};
整个取值逻辑本质上是两行:useRecordContext 取记录 + lodash 的 get 按路径取值。get(record, source, defaultValue) 正是深路径与缺省值同时得到支持的关键——lodash 的 get 会按点号分隔的路径逐级查找,路径上的任何一级不存在都会回退到 defaultValue。
三、Params 详解:source / record / defaultValue
source:取值路径(必填)
source 指定记录对象上要读取的属性名,可以是深路径。官方示例如下——自定义一张顾客名片,分别读取 firstName 与 lastName 两个字段:
import * as React from 'react';
import { useFieldValue } from 'react-admin';
export const CustomerCard = () => {
const firstName = useFieldValue({ source: 'firstName' });
const lastName = useFieldValue({ source: 'lastName' });
return <span>{lastName} {firstName}</span>;
}
由于深路径支持,你也可以写成 useFieldValue({ source: 'name.firstName' }),与文档中 name.fr 的官方示例一致。这在处理后端返回的嵌套对象(如 author: { name, email }、address: { city })时非常实用。
类型层面的保障:source 的类型是 ExtractRecordPaths<RecordType>。从 packages/ra-core/src/types.ts 可以看到:
export type RecordValues = Record<string, any>;
export type RecordPath<TRecordValues extends RecordValues> = FieldPath<TRecordValues>;
export type ExtractRecordPaths<T extends RecordValues> =
[T] extends [never] ? string : RecordPath<T>;
它复用 react-hook-form 的 FieldPath 实现,能够推导出记录类型的所有可能路径(例如对 { title: string; author: { name: string } },合法路径就是 "title" | "author" | "author.name")。这意味着当你为 useFieldValue 提供具体的泛型 RecordType 时,写错的 source 会在编译期直接报错;而未指定泛型时则退化为普通 string,保持灵活。仓库中的 BaseFieldProps(packages/ra-core/src/controller/field/types.ts)也以 source: ExtractRecordPaths<RecordType> 作为字段组件 props 的类型基础,因此自定义字段直接透传 props 即可自动获得这一类型安全。
record:显式指定记录(可选)
默认情况下,useFieldValue 从 RecordContext 读取记录。但某些场景下你希望在 Context 之外使用,例如在只持有记录 id 的组件里先通过 useGetOne 拉取数据,再手动传入:
import * as React from 'react';
import { useFieldValue, useGetOne } from 'react-admin';
export const CustomerCard = ({ id }: { id: string }) => {
const { data } = useGetOne('customer', { id });
const firstName = useFieldValue({ source: 'firstName', record: data });
const lastName = useFieldValue({ source: 'lastName', record: data });
return <span>{lastName} {firstName}</span>;
}
props 中的 record 优先级高于 Context。这在底层由 useRecordContext 保证——packages/ra-core/src/controller/record/useRecordContext.ts 的实现为 return (props && props.record) || context;。所以当组件同时被 Context 包裹且显式传入了 record 时,以显式传入的为准。这一语义让字段组件既能在 <Show>、<Edit> 中无感工作,也能被单独复用(如放进普通卡片、图表或抽屉里)。
defaultValue:缺省回退值(可选)
当记录中不存在 source 指定的值时,返回 defaultValue:
import * as React from 'react';
import { useFieldValue } from 'react-admin';
export const CustomerStatus = () => {
const status = useFieldValue({ source: 'status', defaultValue: 'active' });
return <span>{status}</span>;
}
这里需要注意两点语义细节:
defaultValue在「记录不存在」与「记录中该字段不存在/为空」两种情况下都会生效,因为 lodashget的第三个参数正是兜底值;- 从源码注释看,参数类型中的
defaultValue目前标注为any(packages/ra-core/src/util/useFieldValue.ts 中留有 FIXME:希望未来能约束其类型为RecordType[Source]并做编译期检查)。所以在泛型严格模式下,defaultValue的类型目前需要你自己把控。
四、底层原理:为什么用 RecordContext 而非 SourceContext
useFieldValue 的源码中有一段关键注释(packages/ra-core/src/util/useFieldValue.ts),解释了它的设计取舍:
- react-admin 中存在
SourceContext,它用于修正表单输入(Input)组件在嵌套场景(如SimpleFormIterator、TranslatableInputs等子记录上下文)下的字段路径偏移; - 但字段(Field)组件特意不依赖
SourceContext,只读取RecordContext。原因是这些组件可能创建"子记录上下文"(sub record context),若同时叠加 SourceContext 的路径改写,反而会取错字段; - 输入组件(Input)必须依赖
SourceContext,因为它们读取的是 Form 的值,而表单不能嵌套;字段组件读取的是 Record 的值,而 RecordContext 是可以嵌套的,因此直接按记录结构取值即可。
这正是 useFieldValue 与 useInput 在取值哲学上的根本分界:Input 面向 Form,Field 面向 Record。理解这一点,你就能预判在 SimpleFormIterator、TranslatableInputs 等复杂场景中字段取值为何依旧准确。
五、测试覆盖:六种行为均有单测验证
仓库为 useFieldValue 提供了完整的单元测试(packages/ra-core/src/util/useFieldValue.spec.tsx),覆盖了六个核心行为,可作为你理解语义的"行为规范":
| 测试场景 | 期望结果 |
|---|---|
| 无任何记录可用 | 返回 undefined |
无记录但提供了 defaultValue |
返回 defaultValue |
记录存在但该字段缺失(如 { id: 123 } 取 name) |
返回 defaultValue |
记录在 RecordContext 中({ name: 'John Wick' }) |
返回 name 字段值 |
同时存在 Context 记录与 props record |
返回 props record 中的值(props 优先) |
source 为深路径(name.firstName) |
返回嵌套值 |
这些测试通过 RecordContextProvider 注入记录、用 @testing-library/react 渲染并断言渲染结果,你可以直接运行仓库测试验证:yarn test packages/ra-core/src/util/useFieldValue.spec.tsx。特别是「props 优先于 Context」和「深路径取值」两个用例,精确锁定了前文所述的行为边界。
六、内置字段组件都在用它:与官方实现保持一致
useFieldValue 不是孤立工具,它是 react-admin 所有内置字段组件的取值基石。搜索 packages/ra-ui-materialui/src/field 目录可以发现,以下内置字段均以 useFieldValue(props) 的方式取数:
- TextField.tsx(文档示例的同名组件,
value != null时空值回退到emptyText) - NumberField.tsx、DateField.tsx、BooleanField.tsx
- EmailField.tsx、UrlField.tsx、ChipField.tsx
- RichTextField.tsx、SelectField.tsx、TextArrayField.tsx
- FileField.tsx 与 ImageField.tsx 还会二次调用
useFieldValue读取src等子字段
以 TextField.tsx 为例,它正是"用 useFieldValue 取原始值 → 自己做渲染层处理"的标准范式:先取到值,再判断 value != null 时做 toString() 转换,否则回退到翻译后的 emptyText 或 null。这也给自定义字段提供了最佳实践:用 useFieldValue 负责取值,把精力集中在值的展示逻辑上。
此外,ra-core 的引用字段控制器(ReferenceFieldBase.tsx、ArrayFieldBase.tsx)以及 useReferenceFieldController.ts 也依赖 useFieldValue 读取引用 id,可见它在字段体系中的基础地位。
七、实战小结与最佳实践
综合官方文档与仓库实现,使用 useFieldValue 时请记住以下几点:
- 透传 props 而非逐个传参:字段组件签名保持
(props: FieldProps),直接useFieldValue(props),既能获得source/record的类型安全,又让组件与内置字段的 API 完全对齐; - 深路径放心用:
source支持author.name、name.fr等任意深度,lodashget保证路径中任意一级缺失都不会抛错; - 善用
defaultValue:在记录缺失或字段为空时提供稳定的回退值,减少组件内的空值分支判断; record用于 Context 之外的场景:通过useGetOne等数据 Hook 取到记录后传入record,即可让字段组件脱离<Show>/<Edit>/<List>独立工作,props 优先级更高;- 理解取值哲学:字段走 RecordContext(可嵌套、结构清晰),输入走 SourceContext(表单路径需偏移修正),两者分工不同,不要混用。
掌握了 useFieldValue,你就掌握了 react-admin 字段组件取值层的最核心抽象,无论是仿照 TextField 编写自定义展示组件,还是深入阅读内置字段源码,都能事半功倍。