Maofeng
74 lines
1.8 KiB
Plaintext
74 lines
1.8 KiB
Plaintext
---
|
|
title: Provide and read records
|
|
description: Build record-aware components with RecordProvider, useRecord, and useFieldValue.
|
|
order: 10
|
|
toc:
|
|
- id: provide-a-record
|
|
title: Provide a record
|
|
- id: read-a-record
|
|
title: Read a record
|
|
- id: read-a-field
|
|
title: Read a field
|
|
---
|
|
|
|
## Provide a record {#provide-a-record}
|
|
|
|
Mount the provider at the boundary that owns the data. `RecordProvider` accepts a present, non-nullish record. Use `OptionalRecordProvider` when a query result may be absent.
|
|
|
|
```tsx
|
|
import { RecordProvider } from "@workspace/record"
|
|
|
|
function ProductScreen({ product }: { product: Product }) {
|
|
return (
|
|
<RecordProvider value={product}>
|
|
<ProductDetails />
|
|
</RecordProvider>
|
|
)
|
|
}
|
|
```
|
|
|
|
```tsx
|
|
import { OptionalRecordProvider } from "@workspace/record"
|
|
|
|
;<OptionalRecordProvider value={query.data}>
|
|
<ProductDetails />
|
|
</OptionalRecordProvider>
|
|
```
|
|
|
|
## Read a record {#read-a-record}
|
|
|
|
`useRecord` returns `undefined` when there is no provider or data has not loaded yet.
|
|
|
|
```tsx
|
|
function ProductDetails() {
|
|
const product = useRecord<Product>()
|
|
if (!product) return <p>Loading…</p>
|
|
|
|
return <h2>{product.name}</h2>
|
|
}
|
|
```
|
|
|
|
A record-aware component can also accept an optional `record` prop. The explicit record takes precedence over context, making isolated previews and tests straightforward.
|
|
|
|
```tsx
|
|
function ProductTitle({ record }: { record?: Product }) {
|
|
const product = useRecord({ record })
|
|
return product ? <h2>{product.name}</h2> : null
|
|
}
|
|
```
|
|
|
|
## Read a field {#read-a-field}
|
|
|
|
`useFieldValue` supports direct properties, nested objects, and numeric array segments. Paths use dot notation.
|
|
|
|
```tsx
|
|
const city = useFieldValue<Customer, "address.city">({
|
|
source: "address.city",
|
|
defaultValue: "Unknown",
|
|
})
|
|
|
|
const firstSku = useFieldValue<Order, "items.0.sku">({
|
|
source: "items.0.sku",
|
|
})
|
|
```
|