docs(record): add bilingual usage guides

2026-09-28 17:24:14 +08:00
parent d3de7cc172
commit 1353dc3145
9 changed files with 488 additions and 0 deletions
@@ -0,0 +1,73 @@
+---
+title: 提供并读取记录
+description: 使用 RecordProvider、useRecord 和 useFieldValue 构建记录感知组件。
+order: 10
+toc:
+  - id: provide-a-record
+    title: 提供记录
+  - id: read-a-record
+    title: 读取记录
+  - id: read-a-field
+    title: 读取字段
+---
+
+## 提供记录 {#provide-a-record}
+
+在获得数据的边界挂载 Provider。`RecordProvider` 接受已经存在的非空记录；请求结果可能为空时，使用 `OptionalRecordProvider`。
+
+```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}
+
+`useRecord` 在没有 Provider 或数据尚未加载时返回 `undefined`。
+
+```tsx
+function ProductDetails() {
+  const product = useRecord<Product>()
+  if (!product) return <p>Loading…</p>
+
+  return <h2>{product.name}</h2>
+}
+```
+
+记录感知组件也可以接受可选的 `record` prop。显式记录优先于上下文，方便单独预览和测试组件。
+
+```tsx
+function ProductTitle({ record }: { record?: Product }) {
+  const product = useRecord({ record })
+  return product ? <h2>{product.name}</h2> : null
+}
+```
+
+## 读取字段 {#read-a-field}
+
+`useFieldValue` 支持直接字段、嵌套对象和数组数字段。路径使用点分隔。
+
+```tsx
+const city = useFieldValue<Customer, "address.city">({
+  source: "address.city",
+  defaultValue: "Unknown",
+})
+
+const firstSku = useFieldValue<Order, "items.0.sku">({
+  source: "items.0.sku",
+})
+```