@pisell/private-materials 6.6.8 → 6.6.10

package/dist/lib/pro/Selector/docs/selector.$tab-dev.md

@@ -0,0 +1,1782 @@
+---
+title: 开发文档
+order: 1
+category: pro
+---
+
+# Selector 组件开发文档
+
+## 1. 组件的命名和存放位置
+
+**组件名称**: `Selector`  
+**存放位置**: `private-materials/src/pro/Selector/`  
+**组件编号**: `pcp_de_selector`
+
+## 2. 版本
+
+**当前版本**: `1.0.1`  
+**最后更新**: 2025-11-1
+
+## 3. 相关文档
+
+### 设计文档
+
+- **Figma**: [Selector 组件设计稿](https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=11247-1234)
+- **飞书**: [Selector 组件需求文档](https://m1ed09stz4r.feishu.cn/wiki/NL5AwOs0ei5ZBekT4i6cuzIOnoM)
+
+## 4. 组件规划
+
+### 4.1 组件架构
+
+#### Selector
+
+```
+Selector
+  ├── useSelectionController (逻辑层)
+  │     ├── state (values、errors、options)
+  │     └── actions (状态操作、校验方法)
+  ├── usePresetProps (预设配置转换层)
+  │     ├── layout 计算 (flex/grid 布局配置)
+  │     └── indicatorProps 增强 (自动应用 filled 等样式)
+  ├── usePresetItemProps (预设选项配置层)
+  │     ├── mediaProps 计算 (媒体选项配置)
+  │     └── cardProps 计算 (卡片选项配置)
+  └── content (内容渲染)
+        ├── Title (分组标题)
+        │     └── Tips (校验信息)
+        └── OptionList (选项列表， 布局)
+              ├── inject component (选中指示器/数量选择器)
+              └── LayoutContainer (布局容器：flex/grid)
+                  └── OptionItem (卡片、图文、自定义Radio/Checkbox)
+                        └── slot ｜ children (插槽 ｜ 子元素)
+
+```
+
+#### SelectorGroup
+
+```
+SelectorGroup (容器组件)
+  ├── 状态管理层 (useReducer)
+  │     ├── values (选择值状态)
+  │     ├── visibleGroups (分组可见性)
+  │     └── effects (联动效果)
+  │
+  ├── 联动规则处理
+  │     ├── normalizeRules (规则标准化)
+  │     ├── computeEffects (计算联动效果)
+  │     └── pruneValuesByAllowOnly (值裁剪)
+  │
+  └── 渲染层
+        ├── CategoryTabs (标签页导航 - 可选)
+        │     ├── 标签切换逻辑
+        │     └── 滚动定位功能
+        │
+        └── IntersectionObserverProvider (视口观察容器)
+              └── Content Container (内容容器)
+                    └── IntersectionItem[] (观察项包装)
+                          └── Selector (选择器组件)
+                                ├── 验证规则处理
+                                ├── 数据源动态禁用
+                                ├── Title (标题 + 提示)
+                                └── Options (选项列表)
+```
+
+### 4.2 选择模式支持
+
+#### 基础模式
+
+- **单选模式** : 只能选择一个选项
+- **多选模式** : 可以选择多个选项
+
+#### 高阶模式
+
+- **单选+数量** : 单选基础上支持数量调节
+- **多选+数量** : 多选基础上每个选项支持数量调节
+
+### 4.3 预设系统（Preset System）
+
+#### 设计目标
+
+预设系统是 Selector 组件的**核心能力**，旨在极大简化低代码用户的配置复杂度。通过预定义的样式组合，用户无需深入了解底层的 `layout`、`itemProps`、`indicatorProps` 等复杂属性，仅通过一个简单的 `preset.variant` 值即可快速应用专业的展示形态。
+
+**设计理念**：
+- `preset={{ variant: '1' }}` 即可应用完整的布局和样式
+- 预设提供默认配置，高级用户可通过手动配置覆盖
+- 预设自动处理响应式布局（flex/grid），无需手动计算
+- 预设基于设计规范，确保视觉一致性
+
+#### 核心概念
+
+预设系统基于两个核心配置项：
+
+1. **variant** (组件级): `'default' | 'select' | 'card' | 'media'`
+   - 决定选项的基础展示形态（默认样式 / 下拉选择器 / 卡片 / 图文）
+   
+2. **preset.variant** (预设编号): `'1' | '2' | '3' | '4' | '5'`
+   - 在当前 variant 下选择具体的布局和样式方案
+
+#### 预设变体编号说明（'1' - '5'）
+
+不同的 `variant` 支持不同数量的预设变体：
+
+| Variant   | 支持的预设变体 | 说明                                           |
+| --------- | -------------- | ---------------------------------------------- |
+| `default` | '1', '2', '3', '4' | 默认样式，支持单列/自适应布局的 4 种变体      |
+| `select`  | '1'            | 下拉选择器样式，仅一种形态                     |
+| `card`    | '1', '2', '3', '4', '5' | 卡片样式，支持最丰富的 5 种变体（固定宽度网格/单列等） |
+| `media`   | '1', '2'       | 图文样式，支持 2 种变体（小尺寸/大尺寸）       |
+
+**各变体的特点**：
+
+- **'1'**: 基础布局，最常用的默认形态
+- **'2'**: 增强样式（如自动应用 filled 指示器、添加边框等）
+- **'3'**: 单列布局，适合横向卡片展示
+- **'4'**: 大尺寸网格（325px），适合内容丰富的卡片
+- **'5'**: 单列大卡片，适合详细信息展示
+
+#### 预设系统的工作机制
+
+预设系统通过两个核心 Hook 实现配置转换：
+
+##### 1. usePresetProps - 组件级配置转换
+
+**职责**：根据 `variant` 和 `preset.variant` 生成布局配置（layout）和指示器配置（indicatorProps）
+
+**转换规则**：
+
+```
+// Layout 配置转换
+const COL_CONFIG_MAP = {
+  default: {
+    '1': '100%',      // 单列布局
+    '2': 'auto',      // Flex 自适应
+    '3': '100%',      // 单列布局
+    '4': 'auto',      // Flex 自适应
+  },
+  card: {
+    '1': '209px',     // 固定宽度网格
+    '2': '209px',     // 固定宽度网格 + filled 指示器
+    '3': '100%',      // 单列布局
+    '4': '325px',     // 大尺寸网格
+    '5': '100%',      // 单列大卡片
+  },
+  media: {
+    '1': 'auto',      // Flex 自适应
+    '2': 'auto',      // Flex 自适应
+  },
+};
+
+// 布局类型映射
+- '100%' → { type: 'flex', direction: 'column' }  // 单列
+- 'auto' → { type: 'flex', direction: 'row', wrap: true }  // 自适应
+- '209px'/'325px' → { type: 'grid', baseWidth: '209px' }  // 固定宽度网格
+```
+
+**IndicatorProps 自动增强**：
+- `variant='media'` 时，自动应用 `indicatorProps={{ variant: 'filled' }}`
+- `variant='card' && preset.variant='2'` 时，自动应用 `indicatorProps={{ variant: 'filled' }}`
+
+##### 2. usePresetItemProps - 选项级配置转换
+
+**职责**：根据预设生成具体的选项配置（mediaProps 或 cardProps）
+
+**转换规则**：
+
+**A. variant='default'**：
+```
+cardProps = {
+  variant: 'borderless',
+  layout: 'horizontal',
+  selectedType: 'none',
+  actionsPosition: 'left',
+  actions: numberSelector ? [numberSelector] : [indicator],
+}
+```
+
+**B. variant='media'**：
+- `preset.variant='1'`:
+  ```
+  mediaProps = {
+    size: 'small',
+    showIndicator: false,
+    shape: mode === 'single' ? 'circle' : 'square',
+    coverType: 'text',
+  }
+  ```
+- `preset.variant='2'`:
+  ```
+  mediaProps = {
+    size: 'large',
+    showIndicator: true,
+    shape: 'circle',
+  }
+  ```
+
+**C. variant='card'**：
+
+横向布局（horizontal）：
+- `preset.variant='1'`:
+  ```
+  cardProps = {
+    styles: {
+      container: { padding: 8, borderWidth: selected ? '2px' : '1px' },
+      content: { textAlign: 'center', fontWeight: selected ? '600' : 'normal' }
+    },
+    actions: numberSelector ? [numberSelector] : [], // 不显示 indicator
+  }
+  ```
+- `preset.variant='2'`:
+  ```
+  cardProps = {
+    selectedType: 'filled',
+    styles: { container: { padding: 8 } },
+    actions: numberSelector ? [numberSelector] : [indicator],
+  }
+  ```
+- `preset.variant='5'`:
+  ```
+  cardProps = {
+    variant: 'borderless',
+    selectedType: 'none',
+    styles: { container: { padding: 8 } },
+    actions: numberSelector ? [numberSelector] : [indicator],
+  }
+  ```
+
+纵向布局（vertical）：
+- `preset.variant='2'`:
+  ```
+  cardProps = {
+    layout: 'vertical',
+    variant: 'borderless',
+    corner: indicator,  // indicator 放到右上角
+    actions: numberSelector ? [numberSelector] : [],
+  }
+  ```
+- 其他变体：
+  ```
+  cardProps = {
+    layout: 'vertical',
+    variant: 'borderless',
+    actions: numberSelector ? [numberSelector] : [indicator],
+  }
+  ```
+
+#### 预设系统接口定义
+
+```
+export interface PresetConfig {
+  variant?: '1' | '2' | '3' | '4' | '5'; // 预设变体编号
+}
+
+export interface LayoutConfig {
+  type: 'flex' | 'grid';
+  // flex 模式
+  direction?: 'row' | 'column';
+  wrap?: boolean;
+  // grid 模式
+  baseWidth?: string;  // 如 '209px', '325px'
+}
+
+export interface SelectorProps<T = OptionKey> extends GroupItem {
+  // ... 其他属性
+  preset?: PresetConfig; // 预设配置
+  layout?: LayoutConfig; // 手动布局配置（优先级高于预设）
+}
+```
+
+#### 预设与手动配置的优先级
+
+预设系统采用**渐进增强**的设计原则：
+
+1. **预设作为默认配置**：当仅提供 `preset` 时，组件使用预设的完整配置
+2. **手动配置覆盖预设**：当同时提供 `preset` 和手动配置时，手动配置优先级更高
+3. **深度合并策略**：对于 `styles` 等嵌套对象，使用 lodash merge 进行深度合并
+
+**优先级顺序**：
+```
+自定义 renderItem > 手动 layout/itemProps/indicatorProps > preset 配置
+```
+
+**使用建议**：
+- ✅ **低代码用户**：仅使用 `preset`，快速配置
+- ✅ **设计师**：使用 `preset` + 少量 `itemProps.renderContent` 定制内容
+- ✅ **高级开发者**：使用 `preset` 作为基础，通过手动配置精细调整
+- ✅ **完全自定义**：使用 `renderItem` 完全控制渲染逻辑
+
+## 5. 组件设计
+
+### 5.1 主要接口
+
+```
+// 条件表达式
+export interface ConditionExpr {
+  groupId: string;
+  op?: 'in' | 'notIn' | 'eq' | 'neq' | 'contains' | 'range' | 'exists';
+  value?: any;
+  values?: any[];
+  min?: number;
+  max?: number;
+}
+
+export interface ExprRule {
+  // 逻辑组合
+  and?: (ConditionExpr | ExprRule)[];
+  or?: (ConditionExpr | ExprRule)[];
+  not?: (ConditionExpr | ExprRule)[];
+  // 别名
+  allOf?: (ConditionExpr | ExprRule)[];
+  anyOf?: (ConditionExpr | ExprRule)[];
+  noneOf?: (ConditionExpr | ExprRule)[];
+}
+
+// 联动动作
+export interface LinkageAction {
+  type: 'show' | 'allowOnly' | 'requireOneOf';
+  groupId: string;
+  values?: any[];
+  message?: string;
+}
+
+// 联动规则项
+export interface LinkageRule {
+  type?: 'expr';
+  when: ExprRule | ConditionExpr;
+  then: LinkageAction[];
+  elseThen?: LinkageAction[];
+  priority?: number;
+  stopAfterApply?: boolean;
+}
+
+export type OptionKey = number | string;
+
+export interface RuleConfig {
+  autoValidate?: boolean; // 是否自动校验
+  required?: 0 | 1; // 是否必填
+  min?: number; // 最小选择数量（组级）
+  max?: number; // 最大选择数量（组级）
+  mutex?: Array<Array<OptionKey>>; // 组内互斥
+  customValidator?: (value: SelectionValue) => Promise<void>; // 自定义异步校验器
+}
+
+export interface GroupItem {
+  id?: number; // 分组id
+  title?: string; // 分组标题
+  mode?: 'single' | 'multiple';
+  valueType?: 'primitive' | 'object'; //是否返回原始值，true时返回id或id[]，false时返回包含数量等信息的复合对象
+  preserve?: boolean;
+  fieldNames?: {
+    label?: string; // 选项标题字段名
+    value?: string; // 选项值字段名
+    cover?: string; // 封面图片字段名
+  };
+  ruleConfig?: RuleConfig; // 校验规则
+  dataSource?: OptionItem[]; // 选项列表
+}
+
+export interface OptionItem {
+  id?: number; // 选项id
+  title?: string; // 选项标题
+  label?: string; // 选项标题
+  value?: OptionKey; // 选项值
+  cover?: string; // 封面图片
+  groups?: GroupItem[]; // 选项组列表（预留）
+  disabled?: boolean; // 是否禁用
+  ruleConfig?: {
+    min?: number; // 最小选择数量
+    max?: number; // 最大选择数量
+  }; // 选项校验规则
+  [key: string]: any;
+}
+
+/** 原始值类型：单选时为id，多选时为id[] */
+export type SelectionValuePrimitive<T = OptionKey> = T | T[];
+
+/** 复杂对象值类型：包含id、数量等额外信息 */
+export interface SelectionValueObject<T = OptionKey> {
+  value?: T; // 选项值
+  quantity?: number; // 选择数量
+  [key: string]: any;
+}
+
+/** 单选值类型 */
+export type SelectionValueSingle<T = OptionKey> = T | SelectionValueObject<T>;
+
+/** 多选值类型 */
+export type SelectionValueMultiple<T = OptionKey> =
+  | T[]
+  | SelectionValueObject<T>[];
+
+/** 选择器值类型 */
+export type SelectionValue<T = OptionKey> =
+  | SelectionValueSingle<T>
+  | SelectionValueMultiple<T>;
+
+export type RenderItemProps<T = OptionKey> = {
+  dataSource: OptionItem;
+  actions: any;
+  optionItemValue?: SelectionValue<T>;
+  indicator: React.ReactNode;
+  numberSelector: React.ReactNode;
+};
+
+export type ItemProps = {
+  // card 类型子组件属性
+  layout?: 'vertical' | 'horizontal'; // 默认水平方向
+  selectedTypeVariant?: 'default' | 'bordered' | 'filled'; // 选中态样式变体
+  // 自定义内容渲染
+  renderContent?: (props: { dataSource: OptionItem }) => React.ReactNode;
+  // 自定义样式
+  styles?: {
+    container?: React.CSSProperties;
+    cover?: React.CSSProperties;
+    label?: React.CSSProperties;
+  };
+  // indicator 相关配置, 需要配合layout使用
+  // 卡片模式，横向布局时值为right，其他情况不生效
+  // 卡片模式，垂直布局时值可以设置为topRight，bottom，其他情况不生效，当有数量选择器时，值必为topRight
+  indicatorPosition?: 'left' | 'right' | 'bottom' | 'topRight';
+  size?: 'small' | 'middle' | 'large' | number; // 针对图文模式，尺寸，默认large，当为数字时，表示px
+  [key: string]: any;
+};
+
+export type GridConfig = {
+  align?: 'top' | 'middle' | 'bottom' | 'stretch'; // 网格对齐方式
+  columns?: number; // 网格列数
+  gutter?: number | object | Array<number>; // 子元素间距
+  justify?: 'start' | 'end' | 'center' | 'space-between' | 'space-around'; // 网格对齐方式
+  wrap?: boolean; // 是否换行
+  colConfig?: {
+    [key: string]: any;
+  }; // 列配置
+};
+
+export type LayoutConfig = {
+  type: 'flex' | 'grid';
+  // flex 模式
+  direction?: 'row' | 'column';
+  wrap?: boolean;
+  // grid 模式
+  baseWidth?: string;  // 如 '209px', '325px'
+};
+
+export interface PresetConfig {
+  variant?: '1' | '2' | '3' | '4' | '5'; // 预设变体编号
+}
+
+export interface SelectorProps<T = OptionKey> extends GroupItem {
+  // 值控制（支持 id、id[]、{id, quantity}、{id, quantity}[]）
+  value?: SelectionValue<T>;
+  defaultValue?: SelectionValue<T>;
+  onChange?: (value: SelectionValue<T>) => void;
+  onClear?: () => void;
+  // 禁用状态
+  disabled?: boolean;
+  // UI 配置
+  // 预设配置（简化低代码用户配置）
+  preset?: PresetConfig;
+  // 选项布局配置
+  grid?: GridConfig;
+  // 选项变体
+  variant?: 'default' | 'select' | 'card' | 'media';
+  // 自定义渲染函数
+  renderItem?: (props: RenderItemProps<T>) => React.ReactNode;
+  itemProps?: ItemProps;
+  indicatorProps?: {
+    show?: boolean; // 是否展示指示器 默认展示
+    render?: (props: {
+      option: OptionItem;
+      selected: boolean;
+      disabled: boolean;
+      actions: any;
+    }) => React.ReactNode; // 自定义指示器
+  };
+  // 是否展示数量选择器 默认auto: 根据选项的min和max判断
+  showStepper?: true | false | 'auto';
+  stepperProps?: {
+    size?: 'small' | 'middle' | 'large';
+    shape?: 'round' | 'square';
+  };
+  // 标题相关
+  titleProps?: {
+    visible?: boolean;
+    style?: React.CSSProperties;
+    title?: {
+      visible?: boolean;
+      text?: React.ReactNode;
+      style?: React.CSSProperties;
+    };
+    icon?: {
+      visible?: boolean;
+      icon?: React.ReactNode;
+      style?: React.CSSProperties;
+    };
+    tip?: {
+      visible?: boolean;
+      text?: React.ReactNode;
+      style?: React.CSSProperties;
+    };
+  };
+}
+```
+
+### 5.2 Props 详细说明
+
+#### 基本属性
+
+| 属性           | 类型                            | 默认值 | 说明                                                                                         | 示例                                                        |
+| -------------- | ------------------------------- | ------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `id`           | `any`                           | -      | 组件标识符（可用于区分多个 Selector）                                                        | `1`                                                         |
+| `title`        | `string`                        | -      | 组件标题文案                                                                                 | `'主食选择'`                                                |
+| `dataSource`   | `OptionItem[]`                  | -      | 组件的数据源（选项列表）。`OptionItem.groups` 可预留嵌套，不参与当前渲染                     | `[{ value:1, label:'米饭' }, { value:2, label:'面条' }]`    |
+| `value`        | `any \| any[]`                  | -      | 受控值。单选为 `value` 或 `{ value, quantity }`，多选为 `value[]` 或 `{ value, quantity }[]` | 单选：`1`；多选：`[1,3]`；带数量：`{ value:1, quantity:2 }` |
+| `defaultValue` | `any \| any[]`                  | -      | 非受控初始值，形态与 `value` 一致                                                            | `[{ value:1, quantity:2 }]`                                 |
+| `onChange`     | `(value: any \| any[]) => void` | -      | 选中变更回调。返回与 `value` 同形态                                                          | `onChange={(v) => console.log(v)}`                          |
+| `onClear`      | `() => void`                    | -      | 清空当前选择的回调                                                                           | `onClear={() => setValue(undefined)}`                       |
+
+#### 分组属性（GroupItem）
+
+| 字段         | 类型                                                    | 默认值      | 说明                                  |
+| ------------ | ------------------------------------------------------- | ----------- | ------------------------------------- |
+| `mode`       | `'single' \| 'multiple'`                                | -           | 选择模式（单选/多选）                 |
+| `valueType`  | `'primitive' \| 'object'`                               | -           | 值返回形态（原始值或对象）            |
+| `preserve`   | `boolean`                                               | -           | 隐藏时是否保留值                      |
+| `variant`    | `'default' \| 'select' \| 'card' \| 'media'`            | `'default'` | 展示变体                              |
+| `fieldNames` | `{ label?: string; value?: string; cover?: string }`    | -           | 字段映射（自定义标题/值/封面字段名）  |
+
+#### 预设配置 `preset`（低代码环境）
+
+| 字段        | 类型                                        | 默认值 | 说明                                               |
+| ----------- | ------------------------------------------- | ------ | -------------------------------------------------- |
+| `variant`   | `'1' \| '2' \| '3' \| '4' \| '5'`           | `'1'`  | 预设变体编号（可选项由 variant 决定：default 支持 1-4，card 支持 1-5，media 支持 1-2，select 仅支持 1） |
+
+#### 布局配置 `layout`（高级功能）
+
+| 字段        | 类型                                        | 默认值 | 说明                                               |
+| ----------- | ------------------------------------------- | ------ | -------------------------------------------------- |
+| `type`      | `'flex' \| 'grid'`                          | -      | 布局类型                                           |
+| `direction` | `'row' \| 'column'`                         | `'row'`| 仅 flex 模式：主轴方向                             |
+| `wrap`      | `boolean`                                   | `true` | 是否换行                                           |
+| `baseWidth` | `string`                                    | -      | 仅 grid 模式：列基础宽度（如 '209px'）             |
+
+#### 规则配置 `ruleConfig`
+
+| 字段              | 类型                       | 默认值 | 说明                                                                   |
+| ----------------- | -------------------------- | ------ | ---------------------------------------------------------------------- |
+| `autoValidate`    | `boolean`                  | -      | 是否自动校验                                                           |
+| `required`        | `0 \| 1`                   | `0`    | 是否必选（在 Form 中配合校验）                                         |
+| `min`             | `number`                   | -      | 最小选择数量（组级；多选或数量控件聚合后校验）                         |
+| `max`             | `number`                   | -      | 最大选择数量（组级；多选或数量控件聚合后校验）                         |
+| `mutex`           | `Array<Array<OptionKey>>`  | -      | 组内互斥规则                                                           |
+| `customValidator` | `(value) => Promise<void>` | -      | 自定义异步校验器；`resolve` 通过，`reject({ type, message })` 写入错误 |
+
+#### UI 配置
+
+| 字段                               | 类型                                                                                         | 默认值         | 说明                                               |
+| ---------------------------------- | -------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------- |
+| `renderItem`                       | `(props: RenderItemProps) => React.ReactNode`                                                | -              | 自定义渲染函数（优先级高于 variant）               |
+| `itemProps.layout`                 | `'vertical' \| 'horizontal'`                                                                 | `'horizontal'` | 卡片内容排布方向                                   |
+| `itemProps.selectedTypeVariant`    | `'default' \| 'bordered' \| 'filled'`                                                        | `'default'`    | 选中态样式变体                                     |
+| `itemProps.renderContent`          | `(props: { dataSource: OptionItem }) => React.ReactNode`                                     | -              | 自定义内容渲染                                     |
+| `itemProps.styles`                 | `{ container?: CSSProperties; cover?: CSSProperties; label?: CSSProperties }`                | -              | 自定义样式（容器/封面/标签）                       |
+| `itemProps.indicatorPosition`      | `'left' \| 'right' \| 'bottom' \| 'topRight'`                                                | -              | 指示器位置（需配合 layout 使用）                   |
+| `itemProps.size`                   | `'small' \| 'middle' \| 'large' \| number`                                                   | `'large'`      | 尺寸（图文模式，数字时表示 px）                    |
+| `indicatorProps.show`              | `boolean`                                                                                    | `true`         | 是否展示指示器                                     |
+| `indicatorProps.render`            | `(props: { option: OptionItem; selected: boolean; disabled: boolean; actions: any }) => ...` | -              | 自定义指示器渲染                                   |
+| `stepperProps.size`                | `'small' \| 'middle' \| 'large'`                                                             | -              | 数量步进器尺寸                                     |
+| `stepperProps.shape`               | `'round' \| 'square'`                                                                        | -              | 数量步进器形状                                     |
+
+### 5.3 SelectorGroup 组件接口
+
+SelectorGroup 是管理多个 Selector 组件的容器组件，支持联动规则、标签页导航和滚动监听等功能。
+
+```
+export interface SelectorGroupProps {
+  dataSource: GroupItem[];
+  linkageRules?: ExprRule[] | Record<string, any>; // 跨组规则集合（数组或语法糖对象）
+  allowedValuesPolicy?: 'relaxed' | 'strict'; // 允许值集合处理策略
+  preserve?: boolean;
+  // 受控值能力
+  value?: Record<string, SelectionValue>;
+  defaultValue?: Record<string, SelectionValue>;
+  onChange?: (values: Record<string, SelectionValue>) => void;
+  tabProps?: {
+    visible?: boolean;
+  };
+  customScrollParent?: HTMLElement | string;
+  className?: string;
+  style?: React.CSSProperties;
+  [key: string]: any; // 其他自定义属性
+}
+
+export type SelectorGroupRef = {
+  getValues: (includeHidden?: boolean) => Record<string, SelectionValue>;
+  setValues: (values: Record<string, SelectionValue>) => void;
+  validate: () => Promise<Record<string, never>>;
+  reset: () => void;
+};
+```
+
+#### SelectorGroup Props 说明
+
+| 字段                  | 类型                                | 默认值     | 说明                               |
+| --------------------- | ----------------------------------- | ---------- | ---------------------------------- |
+| `dataSource`          | `GroupItem[]`                       | -          | 分组数据源                         |
+| `linkageRules`        | `ExprRule[] \| Record<string, any>` | -          | 跨组联动规则（数组或语法糖对象）   |
+| `allowedValuesPolicy` | `'relaxed' \| 'strict'`             | `'strict'` | 允许值集合处理策略                 |
+| `preserve`            | `boolean`                           | `false`    | 隐藏分组是否保留值                 |
+| `value`               | `Record<string, SelectionValue>`    | -          | 受控值（按分组 ID 组织）           |
+| `defaultValue`        | `Record<string, SelectionValue>`    | -          | 默认值                             |
+| `onChange`            | `(values) => void`                  | -          | 值变更回调                         |
+| `tabProps.visible`    | `boolean`                           | `true`     | 是否显示标签页导航                 |
+| `customScrollParent`  | `HTMLElement \| string`             | -          | 自定义滚动容器（元素或选择器）     |
+| `className`           | `string`                            | -          | 自定义类名                         |
+| `style`               | `React.CSSProperties`               | -          | 自定义样式                         |
+
+### 5.4 Selector 组件设计
+
+#### 5.4.1 概述
+
+- 逻辑层：由 `useSelectionController` 提供状态、事件、数量校验与输出值归一化能力。
+- 渲染层：消费逻辑层接口，负责具体 UI 呈现（`Card` / 自定义 `renderItem`）。
+- 交互桥接：渲染层通过 `actions.toggle/update` 触发变更；逻辑层归一化并调用 `onChange`。
+
+#### 5.4.2 useSelectionController
+
+- 状态管理：当前选中集合、数量、错误信息（`state.errors`）。
+- 事件处理：选择/取消、切换、清空、数量变更等交互（`actions.toggle/update/clear`）。
+- 输出值构建：根据 `valueType` 与数量是否启用，构建外部 `value`。
+- 校验器：`actions.validate()` 返回 `Promise<boolean>`，失败时写入 `state.errors`。
+
+#### 5.4.3 Hook API
+
+```
+export interface SelectionOption extends OptionItem {
+  _key: OptionKey;
+  _label: string;
+  selected: boolean;
+  quantity: number;
+}
+
+export interface SelectionState {
+  options: SelectionOption[];
+  values: SelectionValue;
+  showQuantity: boolean;
+  errors: Array<{ type: 'required' | 'max' | 'min' | 'requireOneOf' ; message: string; _key?: OptionKey }>;
+}
+
+export interface SelectionActions {
+  toggle: (optionKey: OptionKey) => void;
+  update: (optionKey: OptionKey, data?: any) => void;
+  clear: () => void;
+  validate: () => Promise<boolean>;
+}
+
+export type SelectionValidator = () => boolean;
+
+export function useSelectionController(params: {
+  dataSource?: OptionItem[];
+  ruleConfig?: RuleConfig;
+  fieldNames?: { label?: string; value?: string };
+  mode?: 'single' | 'multiple';
+  valueType?: 'primitive' | 'object';
+  value?: SelectionValuePrimitive | SelectionValue;
+  defaultValue?: SelectionValuePrimitive | SelectionValue;
+  onChange?: (value: SelectionValuePrimitive | SelectionValue) => void;
+}): {
+  state: SelectionState;
+  actions: SelectionActions;
+} {
+  // 实现详见源码
+}
+```
+
+#### 5.4.4 事件流与受控/非受控
+
+- 非受控：内部维护 `state`；`actions` 更新状态并回调 `onChange`。
+- 受控：优先以外部 `value` 为准；`actions` 仅触发 `onChange`，由父级决定是否更新传入的 `value`。
+
+#### 5.4.5 校验逻辑（更新）
+
+- 基础校验：
+  - `required`：必须至少选择 1 项（或数量满足最小要求）。
+  - `min/max`：多选数量限制；带数量时按实际数量聚合后校验。
+- 规则扩展：组间联动规则由上层 `BatchSelector` 的 `linkageRules` 属性统一管理（不再在 `GroupItem` 的 `ruleConfig` 中定义）。
+- 对外接口：组件通过 `ref.validate()` 暴露校验方法，返回 `Promise<boolean>`；错误信息可从 `state.errors` 读取（参考第 7 章示例）。
+
+- 自定义校验：`ruleConfig.customValidator?: (value) => Promise<void>`，`resolve` 表示通过；`reject` 表示失败，建议抛出 `{ type: 'requireOneOf' | 'custom', message?: string }`，组件会把错误写入 `state.errors`。
+
+#### 5.4.6 扩展能力
+
+自定义子组件需要实现以下接口
+
+```
+interface RenderItemProps<T = OptionKey> {
+  dataSource: OptionItem;
+  actions: any;
+  optionItemValue?: SelectionValue<T>;
+  indicator: React.ReactNode; // 单选/多选指示器
+  numberSelector: React.ReactNode; // 数量步进器
+}
+```
+
+#### 5.4.7 简易示例（骨架伪代码）
+
+```
+function Selector(props, ref) {
+  const { dataSource = [], ruleConfig, mode, valueType, fieldNames, appearance, disabled } = props;
+  const { state, actions } = useSelectionController({ dataSource, ruleConfig, mode, valueType, fieldNames, ...props });
+  useImperativeHandle(ref, () => ({ validate: () => actions.validate() }));
+
+  return (
+    <div>
+      {(state.options || []).map((opt) => (
+        <CardItem
+          key={opt._key}
+          selected={opt.selected}
+          disabled={disabled}
+          indicator={/* 单选用 Radio；多选用 Checkbox */}
+          numberSelector={/* 仅在启用数量且选中时显示 */}
+          onClick={() => actions.toggle(opt._key)}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+## 6. 快速开始
+
+### 6.1 使用预设系统（推荐 ⭐）
+
+预设系统是最简单的使用方式，仅需配置 `variant` 和 `preset.variant` 即可快速实现专业的展示效果。
+
+#### 6.1.1 Default Variant - 默认样式
+
+**适用场景**：常规的选项列表，文本为主的选择场景
+
+```
+// Preset 1 - 单列布局
+<Selector
+  title="主食选择"
+  dataSource={[
+    { value: 1, label: '米饭' },
+    { value: 2, label: '面条' },
+    { value: 3, label: '馒头' },
+  ]}
+  mode="single"
+  variant="default"
+  preset={{ variant: '1' }}  // 仅需这一行配置
+  value={1}
+  onChange={(value) => console.log(value)}
+/>
+
+// Preset 2 - 自适应宽度
+<Selector
+  title="口味选择"
+  dataSource={[
+    { value: 1, label: '麻辣' },
+    { value: 2, label: '酸辣' },
+    { value: 3, label: '甜味' },
+  ]}
+  mode="single"
+  variant="default"
+  preset={{ variant: '2' }}  // Flex 自适应布局
+  value={1}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+#### 6.1.2 Card Variant - 卡片样式
+
+**适用场景**：套餐选择、商品规格、配置选项等需要卡片展示的场景
+
+```
+// Preset 1 - 固定宽度网格（209px）
+<Selector
+  title="选择套餐"
+  mode="single"
+  variant="card"
+  preset={{ variant: '1' }}
+  dataSource={[
+    { value: 1, label: '基础版', price: '¥99/月' },
+    { value: 2, label: '专业版', price: '¥299/月' },
+    { value: 3, label: '企业版', price: '¥999/月' },
+  ]}
+  itemProps={{
+    renderContent: ({ dataSource }) => (
+      <div>
+        <div style={{ fontSize: 16, fontWeight: 600 }}>{dataSource.label}</div>
+        <div style={{ color: '#ff4d4f', marginTop: 8 }}>{dataSource.price}</div>
+      </div>
+    ),
+  }}
+  value={1}
+  onChange={(value) => console.log(value)}
+/>
+
+// Preset 2 - 固定宽度 + Filled 指示器
+<Selector
+  title="选择配送方式"
+  mode="single"
+  variant="card"
+  preset={{ variant: '2' }}  // 自动应用 filled 风格指示器
+  dataSource={[
+    { value: 1, label: '标准配送', desc: '3-5个工作日送达' },
+    { value: 2, label: '加急配送', desc: '1-2个工作日送达' },
+  ]}
+  value={1}
+  onChange={(value) => console.log(value)}
+/>
+
+// Preset 3 - 单列横向卡片
+<Selector
+  title="支付方式"
+  mode="single"
+  variant="card"
+  preset={{ variant: '3' }}
+  dataSource={[
+    { value: 1, label: '支付宝', icon: '💳' },
+    { value: 2, label: '微信支付', icon: '💚' },
+  ]}
+  itemProps={{
+    layout: 'horizontal',
+    indicatorPosition: 'right',
+    renderContent: ({ dataSource }) => (
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        <span style={{ fontSize: 24 }}>{dataSource.icon}</span>
+        <span>{dataSource.label}</span>
+      </div>
+    ),
+  }}
+  value={1}
+  onChange={(value) => console.log(value)}
+/>
+
+// Preset 4 - 大尺寸网格（325px）
+<Selector
+  title="会员套餐"
+  mode="single"
+  variant="card"
+  preset={{ variant: '4' }}
+  dataSource={[
+    { 
+      value: 1, 
+      label: 'VIP会员', 
+      price: '¥199/年',
+      desc: '享受全站95折优惠',
+      features: ['5GB 存储', '基础功能']
+    },
+  ]}
+  itemProps={{
+    renderContent: ({ dataSource }) => (
+      <div>
+        <div style={{ fontSize: 20, fontWeight: 600 }}>{dataSource.label}</div>
+        <div style={{ color: '#ff4d4f', fontSize: 24, margin: '12px 0' }}>
+          {dataSource.price}
+        </div>
+        <div style={{ color: '#666', marginBottom: 12 }}>{dataSource.desc}</div>
+        {dataSource.features.map((f, i) => (
+          <div key={i}>✓ {f}</div>
+        ))}
+      </div>
+    ),
+  }}
+  value={1}
+  onChange={(value) => console.log(value)}
+/>
+
+// Preset 5 - 单列大卡片
+<Selector
+  title="商品详情"
+  mode="single"
+  variant="card"
+  preset={{ variant: '5' }}
+  dataSource={[
+    { value: 1, label: '商品A', price: '¥999', desc: '详细描述信息' },
+  ]}
+  itemProps={{
+    layout: 'horizontal',
+    indicatorPosition: 'right',
+  }}
+  value={1}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+#### 6.1.3 Media Variant - 图文样式
+
+**适用场景**：图片选择、图库、相册等以图片为主的场景
+
+```
+// Preset 1 - 小尺寸自适应
+<Selector
+  title="选择图片类型"
+  mode="multiple"
+  variant="media"
+  preset={{ variant: '1' }}
+  dataSource={[
+    { value: 1, label: '风景', cover: 'https://picsum.photos/300/200' },
+    { value: 2, label: '人物', cover: 'https://picsum.photos/300/200' },
+    { value: 3, label: '建筑', cover: 'https://picsum.photos/300/200' },
+  ]}
+  fieldNames={{ value: 'value', label: 'label', cover: 'cover' }}
+  value={[1]}
+  onChange={(value) => console.log(value)}
+/>
+
+// Preset 2 - 大尺寸 + 显示指示器
+<Selector
+  title="选择封面图"
+  mode="single"
+  variant="media"
+  preset={{ variant: '2' }}
+  dataSource={[
+    { value: 1, label: '图片A', cover: 'https://picsum.photos/400/300' },
+    { value: 2, label: '图片B', cover: 'https://picsum.photos/400/300' },
+  ]}
+  fieldNames={{ value: 'value', label: 'label', cover: 'cover' }}
+  value={1}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+#### 6.1.4 带数量选择的预设
+
+```
+// 单选 + 数量
+<Selector
+  title="选择饮品"
+  mode="single"
+  variant="card"
+  valueType="object"
+  showStepper={true}
+  preset={{ variant: '1' }}
+  dataSource={[
+    { value: 1, label: '可乐', price: 5, ruleConfig: { min: 1, max: 10 } },
+    { value: 2, label: '橙汁', price: 8, ruleConfig: { min: 1, max: 5 } },
+  ]}
+  value={{ value: 1, quantity: 2 }}
+  onChange={(value) => console.log(value)}
+/>
+
+// 多选 + 数量
+<Selector
+  title="选择配菜"
+  mode="multiple"
+  variant="card"
+  valueType="object"
+  showStepper={true}
+  preset={{ variant: '2' }}
+  dataSource={[
+    { value: 1, label: '青菜', ruleConfig: { min: 0, max: 3 } },
+    { value: 2, label: '豆腐', ruleConfig: { min: 0, max: 2 } },
+  ]}
+  value={[{ value: 1, quantity: 2 }]}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+### 6.2 基础用法（不使用预设）
+
+如果不使用预设，可以手动配置所有属性：
+
+```
+// 最简单的用法
+<Selector
+  title="主食选择"
+  dataSource={[
+    { value: 1, label: '米饭' },
+    { value: 2, label: '面条' },
+  ]}
+  mode="single"
+  value={1}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+### 6.3 SelectorGroup 使用示例
+
+```
+// 多分组管理（带联动规则）
+<SelectorGroup
+  dataSource={[
+    {
+      id: 1,
+      title: '主食',
+      mode: 'single',
+      valueType: 'primitive',
+      ruleConfig: { required: 1 },
+      dataSource: [
+        { value: 1, label: '米饭' },
+        { value: 2, label: '面条' },
+        { value: 3, label: '馒头' },
+      ],
+    },
+    {
+      id: 2,
+      title: '配菜',
+      mode: 'multiple',
+      valueType: 'object',
+      ruleConfig: { min: 1, max: 3 },
+      dataSource: [
+        { value: 1, label: '青菜', ruleConfig: { min: 0, max: 2 } },
+        { value: 2, label: '豆腐', ruleConfig: { min: 0, max: 1 } },
+      ],
+    },
+    {
+      id: 3,
+      title: '饮品',
+      mode: 'single',
+      valueType: 'primitive',
+      dataSource: [
+        { value: 1, label: '可乐' },
+        { value: 2, label: '橙汁' },
+      ],
+    },
+  ]}
+  linkageRules={[
+    {
+      // 选择米饭时显示饮品分组
+      type: 'expr',
+      when: { and: [{ groupId: '1', op: 'contains', value: 1 }] },
+      then: [
+        { type: 'show', groupId: '3' },
+      ],
+    },
+    {
+      // 选择面条时限制配菜选项和必选验证
+      type: 'expr',
+      when: { and: [{ groupId: '1', op: 'contains', value: 2 }] },
+      then: [
+        { type: 'allowOnly', groupId: '2', values: [1] }, // 只能选青菜
+        { type: 'requireOneOf', groupId: '2', values: [1], message: '面条必须配青菜' },
+      ],
+    },
+  ]}
+  tabProps={{ visible: true }}
+  value={{
+    '1': 1,
+    '2': [{ value: 1, quantity: 1 }],
+  }}
+  onChange={(values) => console.log('所有分组值:', values)}
+/>
+```
+
+### 6.4 嵌套数据源（预留功能）
+
+```
+// 嵌套数据（OptionItem.groups 预留，当前版本不参与渲染）
+<Selector
+  id="6"
+  title="饮料"
+  dataSource={[
+    { value: '11', label: '可乐' },
+    { value: '12', label: '咖啡' },
+    {
+      value: '13',
+      label: '奶茶',
+      groups: [
+        {
+          title: '规格',
+          dataSource: [
+            { value: '1311', label: '中' },
+            { value: '1312', label: '大' },
+          ],
+        },
+        {
+          title: '温度',
+          dataSource: [
+            { value: '1321', label: '热' },
+            { value: '1322', label: '冰' },
+          ],
+        },
+      ],
+    },
+  ]}
+  mode="single"
+  valueType="object"
+  value={{ value: '13' }}
+  onChange={(val) => console.log(val)}
+  titleProps={{
+    visible: true,
+    title: { text: '饮料' },
+  }}
+/>
+
+// 注意：`groups` 为预留字段，当前版本不会递归渲染内部分组，只以普通选项显示。
+```
+
+## 7. 高级功能（Advanced）
+
+当预设系统无法满足需求时，可以使用以下高级功能进行精细控制。
+
+### 7.1 手动配置布局（Layout）
+
+不使用预设时，可以通过 `layout` 属性手动配置布局：
+
+```
+// Flex 布局 - 行方向自适应
+<Selector
+  dataSource={dataSource}
+  layout={{
+    type: 'flex',
+    direction: 'row',
+    wrap: true,
+  }}
+/>
+
+// Flex 布局 - 列方向（单列）
+<Selector
+  dataSource={dataSource}
+  layout={{
+    type: 'flex',
+    direction: 'column',
+    wrap: false,
+  }}
+/>
+
+// Grid 布局 - 固定宽度响应式
+<Selector
+  dataSource={dataSource}
+  layout={{
+    type: 'grid',
+    baseWidth: '209px',  // 每列固定宽度
+    wrap: true,
+  }}
+/>
+
+// Grid 布局 - 大尺寸卡片
+<Selector
+  dataSource={dataSource}
+  layout={{
+    type: 'grid',
+    baseWidth: '325px',
+    wrap: true,
+  }}
+/>
+```
+
+**布局类型说明**：
+- **Flex 布局**：适合内容宽度不固定，需要自适应的场景
+  - `direction: 'row'`：横向排列
+  - `direction: 'column'`：纵向排列（单列）
+  - `wrap: true`：自动换行
+- **Grid 布局**：适合固定宽度的响应式网格
+  - `baseWidth`：设置列的基础宽度，系统会自动计算每行容纳的列数
+  - 响应式原理：`grid-template-columns: repeat(auto-fill, minmax(baseWidth, 1fr))`
+
+### 7.2 自定义选项内容（ItemProps）
+
+通过 `itemProps` 可以精细控制每个选项的展示：
+
+#### 7.2.1 Card 变体的自定义
+
+```
+<Selector
+  variant="card"
+  itemProps={{
+    // 布局方向
+    layout: 'vertical',  // 'vertical' | 'horizontal'
+    
+    // 选中态样式
+    selectedTypeVariant: 'filled',  // 'default' | 'bordered' | 'filled'
+    
+    // 指示器位置
+    indicatorPosition: 'topRight',  // 'left' | 'right' | 'bottom' | 'topRight'
+    
+    // 自定义内容渲染
+    renderContent: ({ dataSource }) => (
+      <div>
+        <h3>{dataSource.label}</h3>
+        <p>{dataSource.description}</p>
+      </div>
+    ),
+    
+    // 自定义样式
+    styles: {
+      container: { padding: 16, borderRadius: 8 },
+      cover: { width: 100, height: 100 },
+      label: { fontSize: 16, fontWeight: 600 },
+    },
+  }}
+/>
+```
+
+#### 7.2.2 Media 变体的自定义
+
+```
+<Selector
+  variant="media"
+  itemProps={{
+    // 尺寸
+    size: 'large',  // 'small' | 'middle' | 'large' | number(px)
+    
+    // 形状
+    shape: 'circle',  // 'circle' | 'square'
+    
+    // 是否显示指示器
+    showIndicator: true,
+    
+    // 封面类型
+    coverType: 'image',  // 'image' | 'text'
+  }}
+/>
+```
+
+#### 7.2.3 样式深度合并
+
+`itemProps.styles` 使用 lodash merge 进行深度合并，可以在预设基础上微调：
+
+```
+<Selector
+  variant="card"
+  preset={{ variant: '1' }}
+  itemProps={{
+    // 这些样式会与预设样式深度合并
+    styles: {
+      container: { 
+        padding: 12,  // 覆盖预设的 padding: 8
+        borderRadius: 8,  // 新增属性
+      },
+    },
+  }}
+/>
+```
+
+### 7.3 自定义指示器（IndicatorProps）
+
+```
+<Selector
+  indicatorProps={{
+    // 是否显示指示器
+    show: true,
+    
+    // 指示器样式变体
+    variant: 'filled',  // 'default' | 'filled'
+    
+    // 自定义指示器渲染
+    render: ({ option, selected, disabled, actions }) => (
+      <div onClick={() => !disabled && actions.toggle(option._key)}>
+        {selected ? '✓' : '○'}
+      </div>
+    ),
+  }}
+/>
+```
+
+### 7.4 自定义数量选择器（StepperProps）
+
+```
+<Selector
+  showStepper={true}
+  stepperProps={{
+    // 尺寸
+    size: 'middle',  // 'small' | 'middle' | 'large'
+    
+    // 形状
+    shape: 'round',  // 'round' | 'square'
+  }}
+/>
+```
+
+### 7.5 完全自定义渲染（RenderItem）
+
+当需要完全自定义选项的渲染逻辑时，可以使用 `renderItem`：
+
+```
+<Selector
+  renderItem={({ dataSource, actions, indicator, numberSelector, optionItemValue }) => {
+    const selected = !!optionItemValue;
+    
+    return (
+      <div
+        onClick={() => actions.toggle(dataSource._key)}
+        style={{
+          padding: 16,
+          border: `2px solid ${selected ? '#1890ff' : '#d9d9d9'}`,
+          borderRadius: 8,
+          cursor: 'pointer',
+        }}
+      >
+        <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+          {indicator}
+          <div style={{ flex: 1 }}>
+            <div style={{ fontSize: 16, fontWeight: 600 }}>{dataSource.label}</div>
+            <div style={{ color: '#999' }}>{dataSource.description}</div>
+          </div>
+          {numberSelector}
+        </div>
+      </div>
+    );
+  }}
+/>
+```
+
+**RenderItemProps 说明**：
+- `dataSource`: 当前选项的数据
+- `actions`: 操作方法（toggle/update/clear）
+- `indicator`: 系统生成的指示器（Radio/Checkbox）
+- `numberSelector`: 系统生成的数量选择器（仅在 showStepper=true 时有值）
+- `optionItemValue`: 当前选项的值（判断是否选中）
+
+### 7.6 手动配置与预设混合使用
+
+预设和手动配置可以混合使用，手动配置优先级更高：
+
+```
+<Selector
+  variant="card"
+  preset={{ variant: '1' }}  // 使用预设作为基础
+  
+  // 以下手动配置会覆盖预设配置
+  indicatorProps={{
+    variant: 'filled',  // 覆盖预设的指示器样式
+  }}
+  
+  itemProps={{
+    selectedTypeVariant: 'bordered',  // 覆盖预设的选中态
+    styles: {
+      container: { padding: 16 },  // 深度合并到预设样式
+    },
+  }}
+/>
+```
+
+**优先级顺序**（从高到低）：
+1. `renderItem` - 完全自定义渲染
+2. 手动配置的 `layout`、`itemProps`、`indicatorProps`
+3. `preset` 配置
+4. 组件默认值
+
+### 7.7 自定义标题配置
+
+```
+<Selector
+  title="选择配置"
+  titleProps={{
+    visible: true,  // 是否显示标题区域
+    
+    // 标题文本配置
+    title: {
+      visible: true,
+      text: '自定义标题',  // 覆盖 props.title
+      style: { fontSize: 18, fontWeight: 600 },
+    },
+    
+    // 图标配置
+    icon: {
+      visible: true,
+      icon: <StarOutlined />,
+      style: { color: '#faad14' },
+    },
+    
+    // 提示文本配置
+    tip: {
+      visible: true,
+      text: '请至少选择一项',
+      style: { color: '#999' },
+    },
+    
+    // 整体样式
+    style: { marginBottom: 16 },
+  }}
+/>
+```
+
+### 7.8 禁用状态控制
+
+```
+// 整体禁用
+<Selector
+  disabled={true}
+  dataSource={dataSource}
+/>
+
+// 单个选项禁用
+<Selector
+  dataSource={[
+    { value: 1, label: '可选项' },
+    { value: 2, label: '禁用项', disabled: true },
+  ]}
+/>
+```
+
+### 7.9 字段映射（FieldNames）
+
+当数据源字段名不是 `value`、`label`、`cover` 时，可以通过 `fieldNames` 映射：
+
+```
+<Selector
+  dataSource={[
+    { id: 1, name: '选项A', image: 'https://...' },
+    { id: 2, name: '选项B', image: 'https://...' },
+  ]}
+  fieldNames={{
+    value: 'id',
+    label: 'name',
+    cover: 'image',
+  }}
+/>
+```
+
+## 8. 最佳实践
+
+### 8.1 如何选择合适的预设
+
+#### 8.1.1 根据 Variant 选择
+
+| Variant   | 适用场景                                 | 推荐预设 | 说明                                           |
+| --------- | ---------------------------------------- | -------- | ---------------------------------------------- |
+| `default` | 纯文本选项、标签选择、简单列表           | '1', '2' | 最简单的样式，适合快速选择                     |
+| `select`  | 下拉选择器样式（表单场景）               | '1'      | 仅一种形态                                     |
+| `card`    | 套餐、商品规格、配置选项、复杂信息展示   | '1'-'5'  | 支持最丰富的变体，适合需要对比的场景           |
+| `media`   | 图片选择、图库、相册、视觉优先的内容     | '1', '2' | 专为图片内容优化                               |
+
+#### 8.1.2 根据选项数量选择
+
+- **1-3 个选项**：推荐 `default` + `preset={{ variant: '2' }}`，自适应宽度横向排列
+- **4-6 个选项**：推荐 `card` + `preset={{ variant: '1' }}`，固定宽度网格
+- **6+ 个选项**：推荐 `card` + `preset={{ variant: '3' }}`，单列布局便于滚动
+
+#### 8.1.3 根据内容复杂度选择
+
+- **纯文本**：`default` + `preset={{ variant: '1' }}`
+- **文本 + 图标**：`default` + `preset={{ variant: '2' }}` + 自定义 renderContent
+- **图片 + 文本**：`media` + `preset={{ variant: '2' }}`
+- **标题 + 描述**：`card` + `preset={{ variant: '3' }}`
+- **完整信息卡片**：`card` + `preset={{ variant: '4' }}` 或 `'5'`
+
+#### 8.1.4 根据场景选择
+
+| 场景               | Variant   | Preset       | ItemProps                              |
+| ------------------ | --------- | ------------ | -------------------------------------- |
+| 口味选择           | `default` | `'2'`        | -                                      |
+| 支付方式           | `card`    | `'3'`        | `{ layout: 'horizontal' }`             |
+| 套餐对比           | `card`    | `'4'`        | 自定义 `renderContent`                 |
+| 商品规格           | `card`    | `'1'`        | `{ layout: 'vertical' }`               |
+| 图片选择           | `media`   | `'1'`        | -                                      |
+| 配菜（带数量）     | `card`    | `'2'`        | `showStepper={true}`                   |
+
+#### 8.1.5 预设与手动配置的选择策略
+
+| 用户类型     | 推荐方式           | 原因                                   |
+| ------------ | ------------------ | -------------------------------------- |
+| 低代码用户   | 仅使用预设         | 简单快捷，无需了解底层属性             |
+| 设计师       | 预设 + renderContent | 预设提供布局，renderContent 定制内容   |
+| 前端开发者   | 预设 + 手动覆盖    | 基于预设，通过手动配置精细调整         |
+| 高级定制     | renderItem         | 完全自定义渲染逻辑                     |
+
+#### 8.1.6 常见场景预设组合
+
+**电商场景**：
+```
+// 商品规格选择
+<Selector
+  variant="card"
+  preset={{ variant: '1' }}
+  itemProps={{
+    layout: 'vertical',
+    indicatorPosition: 'topRight',
+  }}
+/>
+
+// 支付方式选择
+<Selector
+  variant="card"
+  preset={{ variant: '3' }}
+  itemProps={{
+    layout: 'horizontal',
+    indicatorPosition: 'right',
+  }}
+/>
+
+// 增值服务（多选）
+<Selector
+  mode="multiple"
+  variant="card"
+  preset={{ variant: '3' }}
+  itemProps={{
+    layout: 'horizontal',
+    indicatorPosition: 'left',
+  }}
+/>
+```
+
+**问卷调查场景**：
+```
+// 单选题
+<Selector
+  mode="single"
+  variant="default"
+  preset={{ variant: '1' }}
+/>
+
+// 多选题
+<Selector
+  mode="multiple"
+  variant="default"
+  preset={{ variant: '1' }}
+/>
+```
+
+**餐饮点餐场景**：
+```
+// 主食选择
+<Selector
+  mode="single"
+  variant="card"
+  preset={{ variant: '1' }}
+/>
+
+// 配菜（带数量）
+<Selector
+  mode="multiple"
+  variant="card"
+  valueType="object"
+  showStepper={true}
+  preset={{ variant: '2' }}
+/>
+
+// 饮品（单选带数量）
+<Selector
+  mode="single"
+  variant="card"
+  valueType="object"
+  showStepper={true}
+  preset={{ variant: '1' }}
+/>
+```
+
+**图片选择场景**：
+```
+// 图片类型选择（多选）
+<Selector
+  mode="multiple"
+  variant="media"
+  preset={{ variant: '1' }}
+/>
+
+// 封面图选择（单选）
+<Selector
+  mode="single"
+  variant="media"
+  preset={{ variant: '2' }}
+/>
+```
+
+### 8.2 套餐商品 SKU 选择
+
+```
+import React, { useEffect, useRef } from 'react';
+import { SelectorGroup } from '@pisell/private-materials';
+import { Form, Button } from 'antd';
+
+const BundleProductSelector = ({ dataSource, value = {}, onChange }) => {
+  const ref = useRef<SelectorGroup>(null);
+
+  return (
+    <Form.Item
+      rules={[
+        {
+          validator: async () => {
+            try {
+              await ref.current?.validate?.();
+              return Promise.resolve();
+            } catch (errors) {
+              return Promise.reject(new Error('请完成必填项'));
+            }
+          },
+        },
+      ]}
+    >
+      <SelectorGroup
+        ref={ref}
+        dataSource={dataSource}
+        value={value}
+        onChange={onChange}
+        tabProps={{ visible: true }}
+        linkageRules={[
+          {
+            // 示例：选择特定主食时显示特定配菜
+            type: 'expr',
+            when: { and: [{ groupId: '1', op: 'contains', value: 1 }] },
+            then: [
+              { type: 'show', groupId: '2' },
+              { type: 'allowOnly', groupId: '2', values: [1, 2, 3] },
+            ],
+          },
+        ]}
+      />
+    </Form.Item>
+  );
+};
+
+const BundleProductDetail = ({ dataSource, value = {}, onChange }) => {
+  const [form] = Form.useForm();
+
+  const handleSubmit = async () => {
+    const values = await form.validateFields();
+    onChange?.(values);
+  };
+
+  return (
+    <div>
+      <Form form={form}>
+        <BundleProductSelector
+          dataSource={dataSource}
+          value={value}
+          onChange={onChange}
+        />
+      </Form>
+      <Button type="primary" onClick={handleSubmit}>
+        提交
+      </Button>
+    </div>
+  );
+};
+```
+
+## 附录：联动规则详细说明
+
+### A.1 联动规则（linkageRules）
+
+联动规则使用 `when: ConditionExpr` + `then: Action[]` 的结构来定义条件和动作。
+
+#### A.1.1 条件表达式（ConditionExpr）
+
+递归结构：`ExprRule` 支持在 `allOf/anyOf/noneOf`（或别名 `and/or/not`）中嵌套 `ConditionExpr` 或子 `ExprRule`。
+
+**字段别名（推荐）**：
+- `and` = `allOf`
+- `or` = `anyOf` 
+- `not` = `noneOf`
+
+**条件表达式扩展**：
+
+```
+ConditionExpr: { 
+  groupId: string, 
+  op?: 'in'|'notIn'|'eq'|'neq'|'contains'|'range'|'exists', 
+  value?: any, 
+  values?: any[], 
+  min?: number, 
+  max?: number 
+}
+```
+
+**语义说明**：
+- `in`: 任一命中（集合有交集）
+- `notIn`: 全部不命中（集合无交集）
+- `eq`: 选择包含指定 `value`
+- `neq`: 选择不包含指定 `value`
+- `contains`: 等价于 `eq`，用于表意"包含某项"
+- `range`: 选择数量在 `[min,max]` 区间（闭区间）
+- `exists`: 当前分组已选择（数量>0）
+
+#### A.1.2 动作（Action）
+
+- `show`: `{ type: 'show', groupId }`
+- `allowOnly`: `{ type: 'allowOnly', groupId, values }`
+- `requireOneOf`: `{ type: 'requireOneOf', groupId, values, message?: string }`
+
+> **分组可见性约定**：凡在 `show` 中出现过的分组视为"受控分组"，默认隐藏；每次重算前先复位为隐藏，再应用命中的 `show`。
+
+#### A.1.3 规则项（Rule）扩展
+
+```
+Rule: { 
+  type?: 'expr', 
+  when: ExprRule | ConditionExpr, 
+  then: Action[], 
+  elseThen?: Action[], 
+  priority?: number, 
+  stopAfterApply?: boolean 
+}
+```
+
+- `elseThen`: 当 `when` 不满足时应用的动作，避免书写"反向规则"。
+- `stopAfterApply`: 当规则匹配并应用后，短路停止继续处理后续规则（按 `priority` 排序后的顺序）。
+
+### A.2 联动规则示例
+
+#### A.2.1 基础示例
+
+**当 `size=small` 时，`heat` 仅允许指定集合 `['room','hot','veryHot']`**
+
+```
+{
+  type: 'expr',
+  when: { and: [{ groupId: 'size', op: 'in', values: ['small'] }] }, // and 别名（等价 allOf）
+  then: [{ type: 'allowOnly', groupId: 'heat', values: ['room','hot','veryHot'] }],
+  priority: 20
+}
+```
+
+**当 `size=small` 时，`heat` 必须选择指定集合中的一个 `['room','hot','veryHot']`**
+
+```
+{
+  type: 'expr',
+  when: { and: [{ groupId: 'size', op: 'in', values: ['small'] }] },
+  then: [{ type: 'requireOneOf', groupId: 'heat', values: ['room','hot','veryHot'], message: '小杯必须选择 常温/热/烫 之一' }],
+  priority: 30
+}
+```
+
+**选了汉堡则出现汉堡的定制，选择 pizza 则出现 pizza 的定制**
+
+```
+{
+  type: 'expr',
+  when: { and: [{ groupId: 'main', op: 'eq', value: 'burger' }] },
+  then: [{ type: 'show', groupId: 'burger-custom' }],
+  priority: 10
+}
+{
+  type: 'expr',
+  when: { and: [{ groupId: 'main', op: 'eq', value: 'pizza' }] },
+  then: [{ type: 'show', groupId: 'pizza-custom' }],
+  priority: 10
+}
+```
+
+#### A.2.2 复杂嵌套与分支示例
+
+**当 `size` 为 `small|large` 且（`main=burger` 或 `heat in [hot,veryHot]`），同时 `sugar` 不为 `high` 时显示 `burger-custom`，否则显示 `default-custom`，并在命中后短路：**
+
+```
+{
+  type: 'expr',
+  when: {
+    and: [
+      { groupId: 'size', op: 'in', values: ['small', 'large'] },
+      { or: [
+        { groupId: 'main', op: 'eq', value: 'burger' }, 
+        { groupId: 'heat', op: 'in', values: ['hot','veryHot'] }
+      ] },
+      { not: [{ groupId: 'sugar', op: 'in', values: ['high'] }] }
+    ]
+  },
+  then: [{ type: 'show', groupId: 'burger-custom' }],
+  elseThen: [{ type: 'show', groupId: 'default-custom' }],
+  priority: 15,
+  stopAfterApply: true
+}
+```
+
+**范围与存在判断：当 `toppings` 选择数量在 2 到 4 之间，且包含 `cheese`，要求至少选一个 `sauce`。**
+
+```
+{
+  type: 'expr',
+  when: { 
+    and: [
+      { groupId: 'toppings', op: 'range', min: 2, max: 4 }, 
+      { groupId: 'toppings', op: 'contains', value: 'cheese' }
+    ]
+  },
+  then: [{ type: 'requireOneOf', groupId: 'sauce', values: ['ketchup','mustard','bbq'] }],
+  priority: 25
+}
+```