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,62 @@
+---
+title: 嵌套上下文与稳定标识
+description: 组合局部记录上下文，并为记录列表选择稳定的 React key。
+order: 20
+toc:
+  - id: nested-records
+    title: 嵌套记录
+  - id: optional-provider
+    title: 可选 Provider
+  - id: stable-keys
+    title: 稳定标识
+---
+
+## 嵌套记录 {#nested-records}
+
+Provider 可以嵌套。内层字段读取局部记录，离开内层边界后恢复外层记录。
+
+```tsx
+<RecordProvider value={order}>
+  <OrderNumber />
+
+  <RecordProvider value={order.customer}>
+    <CustomerName />
+  </RecordProvider>
+</RecordProvider>
+```
+
+不要把记录上下文当作可变 Store。新数据到达时，把新的记录引用传给 Provider；需要编辑的字段交给表单或其他状态层管理。
+
+## 可选 Provider {#optional-provider}
+
+`OptionalRecordProvider` 只在 `value` 不是 `undefined` 或 `null` 时创建新边界。值为空时，它保留最近的父级记录；`0`、`false` 和空字符串仍会创建新边界。这适合既能接收 prop、又能嵌入现有记录界面的组件。
+
+```tsx
+function ProductCard({ product }: { product?: Product }) {
+  return (
+    <OptionalRecordProvider value={product}>
+      <ProductTitle />
+      <ProductPrice />
+    </OptionalRecordProvider>
+  )
+}
+```
+
+## 稳定标识 {#stable-keys}
+
+`RecordsIterator` 会直接使用字符串、数字或 bigint 记录作为 key；对于对象记录，它默认读取 `id`。其他值或没有 `id` 的对象可通过回调提供 `recordKey`，对象也可以提供字段名。只有未获得有效标识时才会回退到数组下标。
+
+```tsx
+<RecordsIterator
+  data={locales}
+  iterator={(locale) => <LocaleRow />}
+  recordKey="code"
+/>
+
+<RecordsIterator
+  data={revisions}
+  recordKey={(revision) => `${revision.documentId}:${revision.version}`}
+>
+  <RevisionRow />
+</RecordsIterator>
+```