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,28 @@
+---
+title: 概览
+description: 了解 Record 包如何在数据驱动界面中传递当前记录。
+order: 1
+toc:
+  - id: package-role
+    title: 包的职责
+  - id: capabilities
+    title: 主要能力
+  - id: design-boundary
+    title: 设计边界
+---
+
+## 包的职责 {#package-role}
+
+`@workspace/record` 是一个无 UI 的 React 记录上下文层。这里的“记录”不是特定对象类型：除 `undefined` 和 `null` 外，数字、布尔值、字符串、数组、函数和普通对象都可以作为记录。它让后代组件读取当前值，而不需要逐层传递 `record` prop。
+
+## 主要能力 {#capabilities}
+
+- 使用 `RecordProvider` 提供当前记录。
+- 使用 `useRecord` 读取上下文，或通过显式记录覆盖上下文。
+- 使用 `useFieldValue` 按类型安全的点路径读取嵌套字段。
+- 使用 `RecordsIterator` 为列表中的每条数据创建隔离的记录上下文。
+- 使用 `OptionalRecordProvider` 让组件同时支持独立使用和上下文组合。
+
+## 设计边界 {#design-boundary}
+
+该包不负责请求、缓存、分页、表单状态或 UI。请求层只需把已加载的值交给 Provider 或 Iterator。`undefined` 和 `null` 表示没有可提供的记录；`0`、`false` 和空字符串仍是有效记录。表单中的实时输入值仍应由表单状态读取。