@fastspace/schema-form 0.0.8 → 0.0.9

package/README.md

@@ -97,6 +97,79 @@ function App() {
 | `Switch` | 开关 | `boolean` |
 | `Radio` | 单选组 | `string \| number` |
 
+### 选项配置详解 (Select / Autocomplete)
+
+`OptionItem` 结构支持以下属性：
+
+```typescript
+type OptionItem = {
+  label: string;                  // 选中后输入框展示的文本
+  value: string | number | boolean | null; // 提交到表单的值
+  key?: string | number;          // [可选] 唯一标识 (当 value 不唯一或 label 重复时使用)
+  listLabel?: React.ReactNode;    // [可选] 下拉列表展示的内容 (可与 label 不一致)
+  disabled?: boolean;             // 是否禁用
+};
+```
+
+#### 场景 1：Label 重复导致 React Key 报错
+如果选项中存在相同的 `label` 或 `value`，请显式提供 `key`：
+
+```typescript
+{
+  label: '重复项',
+  value: 'dup_1',
+  key: 'unique_key_1'
+},
+{
+  label: '重复项',
+  value: 'dup_2',
+  key: 'unique_key_2'
+}
+```
+
+#### 场景 2：列表展示与选中展示不一致
+例如，列表中展示详细信息（如 "张三 (ID:001)"），选中后只展示姓名（"张三"）：
+
+```typescript
+{
+  label: '张三',                // 选中后展示
+  value: '001',
+  listLabel: (                  // 列表中展示
+    <div>
+      <strong>张三</strong>
+      <span style={{ color: '#999', fontSize: 12 }}> (ID: 001)</span>
+    </div>
+  )
+}
+```
+
+#### 场景 3：选中后触发额外操作
+可以在 `fieldProps` 中传入 `onChange` 回调：
+
+```typescript
+{
+  name: 'userSelect',
+  component: 'Select',
+  ui: {
+    label: '选择用户',
+    options: [
+      { label: 'User A', value: 'a' },
+      { label: 'User B', value: 'b' }
+    ]
+  },
+  fieldProps: {
+    // 这里的 onChange 会在表单值更新后触发
+    onChange: (event, option) => {
+      console.log('选中项:', option);
+      // 执行额外逻辑，例如：
+      // 1. 调用接口获取详情
+      // 2. 联动更新其他字段 (通过 form 实例)
+      // 3. 弹窗提示
+    }
+  }
+}
+```
+
 ### 日期时间组件
 
 | 组件名 | 说明 | 数据类型 |

package/dist/index.d.ts

@@ -321,6 +321,10 @@ export declare type OptionItem = {
     label: string;
     value: string | number | boolean | null;
     disabled?: boolean;
+    /** 唯一标识 (解决 label 重复问题) */
+    key?: string | number;
+    /** 列表展示文本 (允许与选中后回显的 label 不一致) */
+    listLabel?: React.ReactNode;
     [key: string]: unknown;
 };