docs(record): add bilingual usage guides

This commit is contained in:
Maofeng
2026-09-28 17:24:14 +08:00
parent d3de7cc172
commit 1353dc3145
9 changed files with 488 additions and 0 deletions
@@ -0,0 +1,77 @@
---
title: 记录列表示例
description: 使用共享字段组件渲染带上下文的记录列表。
order: 30
toc:
- id: define-field-components
title: 定义字段组件
- id: render-the-list
title: 渲染列表
- id: iterator-callback
title: 使用迭代回调
- id: add-separators
title: 添加分隔内容
---
## 定义字段组件 {#define-field-components}
字段组件只依赖记录上下文,可以复用于详情页、列表和嵌套对象。
```tsx
function ProductName() {
const name = useFieldValue<Product, "name">({ source: "name" })
return <strong>{name}</strong>
}
function ProductPrice() {
const price = useFieldValue<Product, "price">({ source: "price" })
return <span>¥{price}</span>
}
```
## 渲染列表 {#render-the-list}
把相同的 children 传给 Iterator,它会为每条记录重新提供一次上下文。
```tsx
<ul>
<RecordsIterator data={products}>
<li>
<ProductName />
<ProductPrice />
</li>
</RecordsIterator>
</ul>
```
当 `data` 为空、未定义,或没有提供 children/iterator 时,Iterator 返回 `null`。加载、错误和空状态由外层请求界面处理。
## 使用迭代回调 {#iterator-callback}
简单场景可以直接读取回调参数。回调仍然位于对应记录的上下文中,因此内部组件可以继续使用 Hooks。
```tsx
<RecordsIterator
data={products}
iterator={(product, index) => (
<article>
<span>#{index + 1}</span>
<ProductName />
<button onClick={() => addToCart(product.id)}>Add</button>
</article>
)}
/>
```
## 添加分隔内容 {#add-separators}
使用 `separator` 在相邻记录之间插入分隔内容。它不会在第一条记录之前或最后一条记录之后渲染。回调参数是分隔符后面那条记录的索引,并且分隔内容位于对应记录的 `RecordProvider` 之外。
```tsx
<RecordsIterator
data={products}
separator={(index) => <hr aria-label={`第 ${index} 个分隔符`} />}
>
<ProductCard />
</RecordsIterator>
```