@fastspace/schema-form 0.0.6 → 0.0.8

package/README.md

@@ -804,11 +804,56 @@ const MyCustomInput = ({ field, form, values, label, error, helperText }) => {
 
 ---
 
-## 远程搜索与分页 (Autocomplete)
+## 自动完成 (Autocomplete)
 
-`Autocomplete` 组件支持远程搜索、分页加载、防抖搜索以及回显。
+`Autocomplete` 组件支持两种数据加载模式：**一次性加载**和**服务端搜索**。
 
-配置 `ui.remoteConfig` 即可开启远程模式。
+### 1. 一次性加载 (Static / Async)
+
+适用于数据量较小（如少于 1000 条），或者可以一次性加载所有选项的场景。
+
+**用法：**
+- **静态选项**：直接配置 `ui.options`。
+- **异步加载**：配置 `ui.optionRequest`，组件挂载时（或依赖变化时）会自动执行一次请求。
+
+**特点：**
+- 前端过滤：组件内置了基于输入的本地过滤功能。
+- 简单：无需处理分页、防抖等逻辑。
+
+```typescript
+// 示例：异步加载一次性数据
+{
+  name: 'userId',
+  component: 'Autocomplete',
+  ui: {
+    label: '选择用户',
+    // 方式 A: 静态数据
+    // options: [{ label: '张三', value: 1 }, { label: '李四', value: 2 }],
+    
+    // 方式 B: 异步一次性加载
+    optionRequest: async (values) => {
+      // 这里的 values 是当前表单的值，可用于联动
+      const users = await api.getAllUsers();
+      return users.map(u => ({ label: u.name, value: u.id }));
+    }
+  }
+}
+```
+
+### 2. 服务端搜索 (Remote Search)
+
+适用于数据量极大（如用户库、商品库），无法一次性加载，需要根据用户输入实时搜索的场景。
+
+**用法：**
+- 配置 `ui.remoteConfig`。
+
+**特点：**
+- 服务端过滤：每次输入都会发送请求给服务端。
+- 支持分页：滚动到底部自动加载下一页。
+- 支持防抖：内置防抖机制，减少请求频率。
+- 支持回显：通过 `fetchById` 解决默认值不在当前列表中的问题。
+
+> **注意**：如果配置了 `remoteConfig`，`ui.options` 和 `ui.optionRequest` 加载的数据将被忽略（除非作为初始值），组件将完全由 `remoteConfig` 接管数据流。
 
 ```typescript
 {