@pisell/private-materials 6.6.7 → 6.6.9

package/dist/es/pro/Selector/docs/selector.md

@@ -0,0 +1,1744 @@
+---
+nav:
+  title: 组件
+  order: 1
+group:
+  title: 基础组件
+  order: 1
+title: Selector
+order: 1
+category: pro
+---
+
+# Selector 选择器
+
+功能强大的选项选择组件，支持单选、多选、数量选择等多种模式，提供丰富的视觉样式和联动能力。
+
+## 何时使用
+
+- 需要从多个选项中选择一个或多个的场景
+- 需要控制选项数量的商品/套餐选择场景
+- 需要多组选项联动的复杂表单场景
+- 需要展示丰富视觉效果的选项卡片场景
+
+## 代码演示
+
+### 📦 快速上手 - Preset 预设模式
+
+适合非专业开发人员，通过 `preset` 属性快速应用预设样式，无需关心复杂的布局配置。
+
+#### Preset 快速入门
+
+使用 `preset={{ variant: '1' }}` 即可快速应用预设布局，无需任何 `layout` 配置。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  return (
+    <Selector
+      title="选择主菜"
+      dataSource={[
+        { id: 1, title: '汉堡' },
+        { id: 2, title: '披萨' },
+        { id: 3, title: '意面' },
+      ]}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="default"
+      preset={{ variant: '1' }}
+    />
+  );
+};
+```
+
+#### Default Variant - 基础样式预设
+
+Default 变体支持 4 种预设布局，适用于常规的选项选择场景。
+
+**Preset 1 - 单列布局**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  const dataSource = [
+    { id: 1, title: '选项A' },
+    { id: 2, title: '选项B' },
+    { id: 3, title: '选项C' },
+  ];
+
+  return (
+    <Selector
+      dataSource={dataSource}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="default"
+      preset={{ variant: '1' }} // 100% 宽度，垂直排列
+    />
+  );
+};
+```
+
+**Preset 2 - 自适应宽度**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  const dataSource = [
+    { id: 1, title: '选项A' },
+    { id: 2, title: '选项B' },
+    { id: 3, title: '选项C' },
+  ];
+
+  return (
+    <Selector
+      dataSource={dataSource}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="default"
+      preset={{ variant: '2' }} // Flex 布局，选项宽度自动适应内容
+    />
+  );
+};
+```
+
+#### Card Variant - 卡片样式预设
+
+Card 变体支持 5 种预设布局，适用于卡片式、套餐式的选项展示。
+
+**Preset 1 - 固定宽度网格（209px）**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  const cardDataSource = [
+    {
+      id: 1,
+      title: '基础版',
+      price: '¥99/月',
+      desc: '适合个人用户',
+    },
+    {
+      id: 2,
+      title: '专业版',
+      price: '¥299/月',
+      desc: '适合小团队',
+    },
+    {
+      id: 3,
+      title: '企业版',
+      price: '¥999/月',
+      desc: '适合大型企业',
+    },
+  ];
+
+  return (
+    <Selector
+      dataSource={cardDataSource}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '1' }} // CSS Grid 布局，每列固定 209px
+    />
+  );
+};
+```
+
+**Preset 2 - 固定宽度网格 + Filled 指示器**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  const cardDataSource = [
+    { id: 1, title: '基础版', price: '¥99/月' },
+    { id: 2, title: '专业版', price: '¥299/月' },
+    { id: 3, title: '企业版', price: '¥999/月' },
+  ];
+
+  return (
+    <Selector
+      dataSource={cardDataSource}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '2' }} // 209px Grid + filled 风格指示器
+    />
+  );
+};
+```
+
+**Preset 3 - 单列卡片布局**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  const cardDataSource = [
+    { id: 1, title: '基础版', price: '¥99/月', desc: '适合个人用户' },
+    { id: 2, title: '专业版', price: '¥299/月', desc: '适合小团队' },
+    { id: 3, title: '企业版', price: '¥999/月', desc: '适合大型企业' },
+  ];
+
+  return (
+    <Selector
+      dataSource={cardDataSource}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '3' }} // 100% 宽度，适合横向卡片
+      itemProps={{
+        layout: 'horizontal',
+        renderContent: (option) => (
+          <div style={{ flex: 1 }}>
+            <div style={{ fontSize: 16, fontWeight: 600 }}>
+              {option.dataSource.title}
+            </div>
+            <div style={{ color: '#ff4d4f', fontSize: 18, margin: '4px 0' }}>
+              {option.dataSource.price}
+            </div>
+            <div style={{ color: '#999', fontSize: 13 }}>
+              {option.dataSource.desc}
+            </div>
+          </div>
+        ),
+      }}
+    />
+  );
+};
+```
+
+**Preset 4 - 大尺寸网格（325px）**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  const cardDataSource = [
+    {
+      id: 1,
+      title: '基础版',
+      price: '¥99/月',
+      desc: '适合个人用户',
+      features: ['5GB 存储', '基础功能'],
+    },
+    {
+      id: 2,
+      title: '专业版',
+      price: '¥299/月',
+      desc: '适合小团队',
+      features: ['50GB 存储', '高级功能'],
+    },
+  ];
+
+  return (
+    <Selector
+      dataSource={cardDataSource}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '4' }} // 每列固定 325px（适合内容丰富的卡片）
+      itemProps={{
+        renderContent: (option) => (
+          <div>
+            <div style={{ fontSize: 20, fontWeight: 600, marginBottom: 12 }}>
+              {option.dataSource.title}
+            </div>
+            <div style={{ color: '#ff4d4f', fontSize: 24, marginBottom: 12 }}>
+              {option.dataSource.price}
+            </div>
+            <div style={{ color: '#666', fontSize: 14, marginBottom: 16 }}>
+              {option.dataSource.desc}
+            </div>
+            <div style={{ fontSize: 13, color: '#333', lineHeight: 1.8 }}>
+              {option.dataSource.features?.map((f, i) => (
+                <div key={i}>✓ {f}</div>
+              ))}
+            </div>
+          </div>
+        ),
+      }}
+    />
+  );
+};
+```
+
+**Preset 5 - 单列大卡片**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  const cardDataSource = [
+    { id: 1, title: '基础版', price: '¥99/月', desc: '适合个人用户' },
+    { id: 2, title: '专业版', price: '¥299/月', desc: '适合小团队' },
+  ];
+
+  return (
+    <Selector
+      dataSource={cardDataSource}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '5' }} // 100% 宽度，适合详细信息展示
+      itemProps={{
+        layout: 'horizontal',
+        renderContent: (option) => (
+          <div style={{ flex: 1 }}>
+            <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+              <div style={{ flex: 1 }}>
+                <div style={{ fontSize: 18, fontWeight: 600, marginBottom: 4 }}>
+                  {option.dataSource.title}
+                </div>
+                <div style={{ color: '#999', fontSize: 14 }}>
+                  {option.dataSource.desc}
+                </div>
+              </div>
+              <div style={{ color: '#ff4d4f', fontSize: 24, fontWeight: 600 }}>
+                {option.dataSource.price}
+              </div>
+            </div>
+          </div>
+        ),
+      }}
+    />
+  );
+};
+```
+
+#### Media Variant - 媒体样式预设
+
+Media 变体支持 2 种预设布局，适用于图片、视频等媒体内容的选择场景。
+
+**Preset 1 - 自适应媒体网格**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState([1]);
+
+  const mediaDataSource = [
+    {
+      id: 1,
+      label: '风景',
+      value: 'landscape',
+      cover: 'https://picsum.photos/seed/landscape/300/200',
+    },
+    {
+      id: 2,
+      label: '人物',
+      value: 'portrait',
+      cover: 'https://picsum.photos/seed/portrait/300/200',
+    },
+    {
+      id: 3,
+      label: '建筑',
+      value: 'architecture',
+      cover: 'https://picsum.photos/seed/architecture/300/200',
+    },
+  ];
+
+  return (
+    <Selector
+      dataSource={mediaDataSource}
+      mode="multiple"
+      valueType="primitive"
+      fieldNames={{ value: 'value', label: 'label', cover: 'cover' }}
+      value={value}
+      onChange={setValue}
+      variant="media"
+      preset={{ variant: '1' }} // Flex 布局，自动应用 filled 指示器
+    />
+  );
+};
+```
+
+**Preset 2 - 自适应媒体网格（变体）**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  const mediaDataSource = [
+    {
+      id: 1,
+      label: '风景',
+      value: 'landscape',
+      cover: 'https://picsum.photos/seed/landscape/300/200',
+    },
+    {
+      id: 2,
+      label: '人物',
+      value: 'portrait',
+      cover: 'https://picsum.photos/seed/portrait/300/200',
+    },
+  ];
+
+  return (
+    <Selector
+      dataSource={mediaDataSource}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'value', label: 'label', cover: 'cover' }}
+      value={value}
+      onChange={setValue}
+      variant="media"
+      preset={{ variant: '2' }} // 另一种 Flex 媒体布局
+    />
+  );
+};
+```
+
+#### Select Variant - 下拉选择预设
+
+Select 变体提供标准的下拉选择器样式。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState();
+
+  return (
+    <Selector
+      title="选择城市"
+      dataSource={[
+        { id: 1, title: '北京', value: 'beijing' },
+        { id: 2, title: '上海', value: 'shanghai' },
+        { id: 3, title: '广州', value: 'guangzhou' },
+      ]}
+      mode="single"
+      valueType="primitive"
+      variant="select"
+      preset={{ variant: '1' }}
+      fieldNames={{ value: 'value', label: 'title' }}
+      value={value}
+      onChange={setValue}
+    />
+  );
+};
+```
+
+#### 实际应用场景
+
+**场景1：电商商品规格选择**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+import { StarOutlined } from '@ant-design/icons';
+
+export default () => {
+  const [value, setValue] = useState({ value: 1, quantity: 1 });
+
+  const productSpecs = [
+    {
+      id: 1,
+      title: '128GB 黑色',
+      price: '¥5999',
+      stock: 156,
+      ruleConfig: { min: 1, max: 3 },
+    },
+    {
+      id: 2,
+      title: '256GB 白色',
+      price: '¥6999',
+      stock: 89,
+      ruleConfig: { min: 1, max: 5 },
+    },
+    {
+      id: 3,
+      title: '512GB 蓝色',
+      price: '¥7999',
+      stock: 23,
+      ruleConfig: { min: 1, max: 2 },
+    },
+  ];
+
+  return (
+    <Selector
+      title="选择商品规格"
+      dataSource={productSpecs}
+      mode="single"
+      valueType="object"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '1' }}
+      itemProps={{
+        layout: 'vertical',
+        renderContent: (option) => (
+          <div>
+            <div style={{ fontSize: 16, fontWeight: 600, marginBottom: 6 }}>
+              {option.dataSource.title}
+            </div>
+            <div
+              style={{
+                color: '#ff4d4f',
+                fontSize: 20,
+                fontWeight: 600,
+                marginBottom: 6,
+              }}
+            >
+              {option.dataSource.price}
+            </div>
+            <div style={{ color: '#999', fontSize: 13 }}>
+              库存：{option.dataSource.stock} 件
+            </div>
+          </div>
+        ),
+      }}
+      titleProps={{
+        visible: true,
+        icon: {
+          visible: true,
+          icon: <StarOutlined style={{ color: '#faad14' }} />,
+        },
+      }}
+    />
+  );
+};
+```
+
+**场景2：支付方式选择**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState('alipay');
+
+  const paymentMethods = [
+    { id: 1, value: 'alipay', title: '支付宝', icon: '💳' },
+    { id: 2, value: 'wechat', title: '微信支付', icon: '💚' },
+    { id: 3, value: 'card', title: '银行卡', icon: '🏦' },
+  ];
+
+  return (
+    <Selector
+      title="选择支付方式"
+      dataSource={paymentMethods}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'value', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '3' }}
+      itemProps={{
+        layout: 'horizontal',
+        renderContent: (option) => (
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: 12,
+              flex: 1,
+            }}
+          >
+            <div style={{ fontSize: 32 }}>{option.dataSource.icon}</div>
+            <div style={{ fontSize: 16, fontWeight: 500 }}>
+              {option.dataSource.title}
+            </div>
+          </div>
+        ),
+      }}
+    />
+  );
+};
+```
+
+**场景3：增值服务选择（多选）**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState([1, 2]);
+
+  const serviceOptionsList = [
+    { id: 1, title: '7天无理由退换', price: '免费' },
+    { id: 2, title: '延保服务', price: '+¥199' },
+    { id: 3, title: '碎屏险', price: '+¥299' },
+    { id: 4, title: '上门安装', price: '+¥99' },
+  ];
+
+  return (
+    <Selector
+      title="增值服务（可选）"
+      dataSource={serviceOptionsList}
+      mode="multiple"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '3' }}
+      ruleConfig={{ max: 3 }}
+      itemProps={{
+        layout: 'horizontal',
+        renderContent: (option) => (
+          <div
+            style={{
+              display: 'flex',
+              justifyContent: 'space-between',
+              alignItems: 'center',
+              flex: 1,
+            }}
+          >
+            <div style={{ fontSize: 15 }}>{option.dataSource.title}</div>
+            <div style={{ color: '#ff4d4f', fontSize: 15, fontWeight: 600 }}>
+              {option.dataSource.price}
+            </div>
+          </div>
+        ),
+      }}
+      titleProps={{
+        visible: true,
+        tip: {
+          visible: true,
+          text: '最多选择3项',
+        },
+      }}
+    />
+  );
+};
+```
+
+### 🔧 高级配置 - 专业开发模式
+
+适合专业开发人员，通过 `layout`、`renderItem` 等高级属性实现完全自定义。
+
+#### 自定义布局配置
+
+通过 `layout` 属性精确控制布局方式。
+
+**Flex 布局**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  return (
+    <Selector
+      title="自定义 Flex 布局"
+      dataSource={[
+        { id: 1, title: '选项A' },
+        { id: 2, title: '选项B' },
+        { id: 3, title: '选项C' },
+      ]}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="default"
+      layout={{
+        type: 'flex',
+        direction: 'row',
+        wrap: true,
+        gutter: 16,
+      }}
+    />
+  );
+};
+```
+
+**CSS Grid 布局**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  return (
+    <Selector
+      title="自定义 Grid 布局"
+      dataSource={[
+        { id: 1, title: '选项A' },
+        { id: 2, title: '选项B' },
+        { id: 3, title: '选项C' },
+        { id: 4, title: '选项D' },
+      ]}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      layout={{
+        type: 'grid',
+        baseWidth: '200px',
+        wrap: true,
+        gutter: 16,
+      }}
+    />
+  );
+};
+```
+
+**Ant Design Grid 布局**
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  return (
+    <Selector
+      title="Ant Design Grid 布局"
+      dataSource={[
+        { id: 1, title: '选项A' },
+        { id: 2, title: '选项B' },
+        { id: 3, title: '选项C' },
+      ]}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      layout={{
+        type: 'antdGrid',
+        columns: 3,
+        gutter: [16, 16],
+        colConfig: { xs: 24, sm: 12, md: 8 },
+      }}
+    />
+  );
+};
+```
+
+#### 完全自定义渲染
+
+通过 `renderItem` 完全控制每个选项的渲染。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  return (
+    <Selector
+      title="完全自定义渲染"
+      dataSource={[
+        {
+          id: 1,
+          title: '基础套餐',
+          price: '$9.99',
+          desc: '适合个人使用',
+          badge: 'HOT',
+        },
+        {
+          id: 2,
+          title: '标准套餐',
+          price: '$19.99',
+          desc: '适合小团队',
+        },
+      ]}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      renderItem={({ dataSource, indicator, actions }) => (
+        <div
+          onClick={() => actions.toggle(dataSource._key)}
+          style={{
+            border: '2px solid',
+            borderColor: dataSource.selected ? '#1890ff' : '#d9d9d9',
+            borderRadius: 12,
+            padding: 20,
+            marginBottom: 12,
+            cursor: 'pointer',
+            position: 'relative',
+            transition: 'all 0.3s',
+            backgroundColor: dataSource.selected ? '#e6f7ff' : '#fff',
+          }}
+        >
+          {dataSource.badge && (
+            <div
+              style={{
+                position: 'absolute',
+                top: -8,
+                right: 20,
+                background: '#ff4d4f',
+                color: '#fff',
+                padding: '2px 12px',
+                borderRadius: 10,
+                fontSize: 12,
+                fontWeight: 600,
+              }}
+            >
+              {dataSource.badge}
+            </div>
+          )}
+          <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+            {indicator}
+            <div style={{ flex: 1 }}>
+              <div style={{ fontSize: 18, fontWeight: 600, marginBottom: 4 }}>
+                {dataSource.title}
+              </div>
+              <div style={{ fontSize: 13, color: '#999' }}>
+                {dataSource.desc}
+              </div>
+            </div>
+            <div style={{ fontSize: 24, fontWeight: 700, color: '#1890ff' }}>
+              {dataSource.price}
+            </div>
+          </div>
+        </div>
+      )}
+    />
+  );
+};
+```
+
+#### 自定义指示器
+
+通过 `indicatorProps` 自定义选中指示器的样式和行为。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+import { CheckCircleFilled, StarFilled } from '@ant-design/icons';
+
+export default () => {
+  const [value, setValue] = useState(1);
+
+  return (
+    <Selector
+      title="自定义指示器"
+      dataSource={[
+        { id: 1, title: '选项A' },
+        { id: 2, title: '选项B' },
+        { id: 3, title: '选项C' },
+      ]}
+      mode="single"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '1' }}
+      indicatorProps={{
+        variant: 'filled',
+        render: ({ option, selected, disabled, actions }) => (
+          <div
+            onClick={() => !disabled && actions.toggle(option._key)}
+            style={{
+              fontSize: 24,
+              color: selected ? '#faad14' : '#d9d9d9',
+              cursor: disabled ? 'not-allowed' : 'pointer',
+            }}
+          >
+            {selected ? <StarFilled /> : <CheckCircleFilled />}
+          </div>
+        ),
+      }}
+    />
+  );
+};
+```
+
+#### 数量选择器配置
+
+配合 `valueType="object"` 使用数量选择器。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState([
+    { value: 1, quantity: 2 },
+    { value: 2, quantity: 1 },
+  ]);
+
+  return (
+    <Selector
+      title="选择商品和数量"
+      dataSource={[
+        {
+          id: 1,
+          title: '商品A',
+          price: '¥99',
+          ruleConfig: { min: 1, max: 5 },
+        },
+        {
+          id: 2,
+          title: '商品B',
+          price: '¥199',
+          ruleConfig: { min: 1, max: 3 },
+        },
+        {
+          id: 3,
+          title: '商品C',
+          price: '¥299',
+          ruleConfig: { min: 1, max: 10 },
+        },
+      ]}
+      mode="multiple"
+      valueType="object"
+      fieldNames={{ value: 'id', label: 'title' }}
+      value={value}
+      onChange={setValue}
+      variant="card"
+      preset={{ variant: '3' }}
+      showStepper={true}
+      stepperProps={{
+        size: 'middle',
+        shape: 'square',
+      }}
+      itemProps={{
+        layout: 'horizontal',
+        renderContent: (option) => (
+          <div
+            style={{
+              display: 'flex',
+              justifyContent: 'space-between',
+              alignItems: 'center',
+              flex: 1,
+            }}
+          >
+            <div>
+              <div style={{ fontSize: 16, fontWeight: 600 }}>
+                {option.dataSource.title}
+              </div>
+              <div style={{ color: '#ff4d4f', fontSize: 18 }}>
+                {option.dataSource.price}
+              </div>
+            </div>
+          </div>
+        ),
+      }}
+    />
+  );
+};
+```
+
+#### 必填校验
+
+通过 `ruleConfig` 配置校验规则。
+
+```tsx
+import React, { useState, useRef } from 'react';
+import { Selector } from '@pisell/private-materials';
+import { Button, message } from 'antd';
+
+export default () => {
+  const [value, setValue] = useState();
+  const selectorRef = useRef();
+
+  const handleValidate = async () => {
+    try {
+      await selectorRef.current?.validate();
+      message.success('校验通过');
+    } catch (error) {
+      message.error('校验失败');
+    }
+  };
+
+  return (
+    <>
+      <Selector
+        ref={selectorRef}
+        title="选择主菜（必选）"
+        dataSource={[
+          { id: 1, title: '汉堡' },
+          { id: 2, title: '披萨' },
+        ]}
+        mode="single"
+        valueType="primitive"
+        fieldNames={{ value: 'id', label: 'title' }}
+        ruleConfig={{
+          required: 1,
+          autoValidate: true,
+        }}
+        variant="default"
+        preset={{ variant: '1' }}
+        value={value}
+        onChange={setValue}
+      />
+      <Button onClick={handleValidate} style={{ marginTop: 16 }}>
+        校验
+      </Button>
+    </>
+  );
+};
+```
+
+#### 最小/最大选择数量
+
+限制多选模式下的选择数量范围。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState([]);
+
+  return (
+    <Selector
+      title="选择配料（至少2个，最多4个）"
+      dataSource={[
+        { id: 1, title: '生菜' },
+        { id: 2, title: '番茄' },
+        { id: 3, title: '洋葱' },
+        { id: 4, title: '芝士' },
+        { id: 5, title: '培根' },
+        { id: 6, title: '鸡蛋' },
+      ]}
+      mode="multiple"
+      valueType="primitive"
+      fieldNames={{ value: 'id', label: 'title' }}
+      variant="card"
+      preset={{ variant: '1' }}
+      ruleConfig={{
+        min: 2,
+        max: 4,
+        autoValidate: true,
+      }}
+      value={value}
+      onChange={setValue}
+    />
+  );
+};
+```
+
+#### 组内互斥
+
+通过 `mutex` 配置组内互斥规则。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+export default () => {
+  const [value, setValue] = useState([]);
+
+  return (
+    <Selector
+      title="选择配置（温度和糖度互斥）"
+      dataSource={[
+        { id: 1, title: '热', value: 'hot' },
+        { id: 2, title: '温', value: 'warm' },
+        { id: 3, title: '冷', value: 'cold' },
+        { id: 4, title: '少糖', value: 'less-sugar' },
+        { id: 5, title: '正常糖', value: 'normal-sugar' },
+        { id: 6, title: '多糖', value: 'more-sugar' },
+      ]}
+      mode="multiple"
+      valueType="primitive"
+      fieldNames={{ value: 'value', label: 'title' }}
+      variant="default"
+      preset={{ variant: '2' }}
+      ruleConfig={{
+        mutex: [
+          ['hot', 'warm', 'cold'], // 温度互斥组
+          ['less-sugar', 'normal-sugar', 'more-sugar'], // 糖度互斥组
+        ],
+      }}
+      value={value}
+      onChange={setValue}
+    />
+  );
+};
+```
+
+#### 自定义校验器
+
+通过 `customValidator` 实现复杂的校验逻辑。
+
+```tsx
+import React, { useState, useRef } from 'react';
+import { Selector } from '@pisell/private-materials';
+import { Button, message } from 'antd';
+
+export default () => {
+  const [value, setValue] = useState([]);
+  const selectorRef = useRef();
+
+  const handleValidate = async () => {
+    try {
+      await selectorRef.current?.validate();
+      message.success('校验通过');
+    } catch (error) {
+      message.error(error.message || '校验失败');
+    }
+  };
+
+  return (
+    <>
+      <Selector
+        ref={selectorRef}
+        title="选择配料（至少包含一个蔬菜）"
+        dataSource={[
+          { id: 1, title: '生菜', type: 'vegetable' },
+          { id: 2, title: '番茄', type: 'vegetable' },
+          { id: 3, title: '洋葱', type: 'vegetable' },
+          { id: 4, title: '培根', type: 'meat' },
+          { id: 5, title: '鸡蛋', type: 'protein' },
+        ]}
+        mode="multiple"
+        valueType="primitive"
+        fieldNames={{ value: 'id', label: 'title' }}
+        variant="default"
+        preset={{ variant: '2' }}
+        ruleConfig={{
+          customValidator: async (value) => {
+            const selectedItems = Array.isArray(value) ? value : [value];
+            const dataSource = [
+              { id: 1, title: '生菜', type: 'vegetable' },
+              { id: 2, title: '番茄', type: 'vegetable' },
+              { id: 3, title: '洋葱', type: 'vegetable' },
+              { id: 4, title: '培根', type: 'meat' },
+              { id: 5, title: '鸡蛋', type: 'protein' },
+            ];
+            const hasVegetable = selectedItems.some((id) => {
+              const item = dataSource.find((d) => d.id === id);
+              return item?.type === 'vegetable';
+            });
+            if (!hasVegetable) {
+              throw new Error('至少需要选择一个蔬菜');
+            }
+          },
+        }}
+        value={value}
+        onChange={setValue}
+      />
+      <Button onClick={handleValidate} style={{ marginTop: 16 }}>
+        校验
+      </Button>
+    </>
+  );
+};
+```
+
+## SelectorGroup 组联动
+
+`SelectorGroup` 组件支持多个选择器组之间的联动效果。
+
+### 基础组联动
+
+多个选择器组组合使用。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+const SelectorGroup = Selector.Group;
+
+export default () => {
+  const [values, setValues] = useState({});
+
+  const dataSource = [
+    {
+      id: 1,
+      title: '主菜',
+      mode: 'single',
+      valueType: 'primitive',
+      fieldNames: { value: 'id', label: 'title' },
+      dataSource: [
+        { id: 1, title: '汉堡' },
+        { id: 2, title: '披萨' },
+      ],
+      ruleConfig: {
+        required: 1,
+      },
+    },
+    {
+      id: 2,
+      title: '配料',
+      mode: 'multiple',
+      valueType: 'primitive',
+      fieldNames: { value: 'id', label: 'title' },
+      dataSource: [
+        { id: 1, title: '生菜' },
+        { id: 2, title: '番茄' },
+        { id: 3, title: '芝士' },
+      ],
+    },
+  ];
+
+  return (
+    <SelectorGroup
+      dataSource={dataSource}
+      value={values}
+      onChange={setValues}
+    />
+  );
+};
+```
+
+### 条件显示
+
+根据选择结果动态显示/隐藏分组。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+const SelectorGroup = Selector.Group;
+
+export default () => {
+  const [values, setValues] = useState({});
+
+  const dataSource = [
+    {
+      id: 1,
+      title: '主菜',
+      mode: 'single',
+      valueType: 'primitive',
+      fieldNames: { value: 'value', label: 'title' },
+      dataSource: [
+        { id: 1, title: '汉堡', value: 'burger' },
+        { id: 2, title: '披萨', value: 'pizza' },
+      ],
+    },
+    {
+      id: 2,
+      title: '汉堡定制',
+      mode: 'multiple',
+      valueType: 'primitive',
+      fieldNames: { value: 'value', label: 'title' },
+      dataSource: [
+        { id: 1, title: '加倍牛肉', value: 'double-meat' },
+        { id: 2, title: '额外芝士', value: 'extra-cheese' },
+      ],
+    },
+    {
+      id: 3,
+      title: '披萨定制',
+      mode: 'multiple',
+      valueType: 'primitive',
+      fieldNames: { value: 'value', label: 'title' },
+      dataSource: [
+        { id: 1, title: '薄底', value: 'thin-crust' },
+        { id: 2, title: '额外芝士', value: 'extra-cheese' },
+      ],
+    },
+  ];
+
+  const linkageRules = [
+    {
+      type: 'expr',
+      when: {
+        and: [{ groupId: '1', op: 'eq', value: 'burger' }],
+      },
+      then: [{ type: 'show', groupId: '2' }],
+    },
+    {
+      type: 'expr',
+      when: {
+        and: [{ groupId: '1', op: 'eq', value: 'pizza' }],
+      },
+      then: [{ type: 'show', groupId: '3' }],
+    },
+  ];
+
+  return (
+    <SelectorGroup
+      dataSource={dataSource}
+      linkageRules={linkageRules}
+      value={values}
+      onChange={setValues}
+    />
+  );
+};
+```
+
+### 选项联动
+
+一个组的选择影响另一个组的可选项。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+const SelectorGroup = Selector.Group;
+
+export default () => {
+  const [values, setValues] = useState({});
+
+  const dataSource = [
+    {
+      id: 1,
+      title: '饮品',
+      mode: 'single',
+      valueType: 'primitive',
+      fieldNames: { value: 'value', label: 'title' },
+      dataSource: [
+        { id: 1, title: 'Coffee', value: 'coffee' },
+        { id: 2, title: 'Tea', value: 'tea' },
+      ],
+    },
+    {
+      id: 2,
+      title: '加料',
+      mode: 'single',
+      valueType: 'primitive',
+      fieldNames: { value: 'value', label: 'title' },
+      dataSource: [
+        { id: 1, title: 'Milk', value: 'milk' },
+        { id: 2, title: 'Sugar', value: 'sugar' },
+        { id: 3, title: 'Lemon', value: 'lemon' },
+        { id: 4, title: 'Honey', value: 'honey' },
+      ],
+    },
+  ];
+
+  const linkageRules = [
+    {
+      type: 'expr',
+      when: { and: [{ groupId: '1', op: 'eq', value: 'coffee' }] },
+      then: [
+        {
+          type: 'allowOnly',
+          groupId: '2',
+          values: ['milk', 'sugar'],
+          tip: '加料仅允许 Milk/Sugar',
+        },
+      ],
+    },
+    {
+      type: 'expr',
+      when: { and: [{ groupId: '1', op: 'eq', value: 'tea' }] },
+      then: [
+        {
+          type: 'allowOnly',
+          groupId: '2',
+          values: ['lemon', 'honey'],
+          tip: '加料仅允许 Lemon/Honey',
+        },
+      ],
+    },
+  ];
+
+  return (
+    <SelectorGroup
+      dataSource={dataSource}
+      linkageRules={linkageRules}
+      allowedValuesPolicy="strict"
+      value={values}
+      onChange={setValues}
+    />
+  );
+};
+```
+
+### 标签页模式
+
+启用标签页导航，方便在多个分组间切换。
+
+```tsx
+import React, { useState } from 'react';
+import { Selector } from '@pisell/private-materials';
+
+const SelectorGroup = Selector.Group;
+
+export default () => {
+  const [values, setValues] = useState({});
+
+  const dataSource = [
+    {
+      id: 1,
+      title: '主菜',
+      mode: 'single',
+      valueType: 'primitive',
+      fieldNames: { value: 'id', label: 'title' },
+      dataSource: [
+        { id: 1, title: '汉堡' },
+        { id: 2, title: '披萨' },
+      ],
+    },
+    {
+      id: 2,
+      title: '饮品',
+      mode: 'single',
+      valueType: 'primitive',
+      fieldNames: { value: 'id', label: 'title' },
+      dataSource: [
+        { id: 1, title: '可乐' },
+        { id: 2, title: '雪碧' },
+      ],
+    },
+    {
+      id: 3,
+      title: '小食',
+      mode: 'multiple',
+      valueType: 'primitive',
+      fieldNames: { value: 'id', label: 'title' },
+      dataSource: [
+        { id: 1, title: '薯条' },
+        { id: 2, title: '鸡块' },
+      ],
+    },
+  ];
+
+  return (
+    <SelectorGroup
+      dataSource={dataSource}
+      value={values}
+      onChange={setValues}
+      tabProps={{ visible: true }}
+    />
+  );
+};
+```
+
+## API
+
+### Selector
+
+| 参数           | 说明                   | 类型                                                 | 默认值         |
+| -------------- | ---------------------- | ---------------------------------------------------- | -------------- |
+| id             | 选择器唯一标识         | `string \| number`                                   | -              |
+| title          | 选择器标题             | `string`                                             | -              |
+| mode           | 选择模式               | `'single' \| 'multiple'`                             | `'single'`     |
+| valueType      | 值类型                 | `'primitive' \| 'object'`                            | `'primitive'`  |
+| variant        | 显示变体               | `'default' \| 'card' \| 'select' \| 'media'`         | `'default'`    |
+| preset         | 预设配置（快速布局）   | `PresetConfig`                                       | -              |
+| dataSource     | 选项数据源             | `OptionItem[]`                                       | `[]`           |
+| value          | 当前值（受控）         | `SelectionValue`                                     | -              |
+| defaultValue   | 默认值（非受控）       | `SelectionValue`                                     | -              |
+| onChange       | 值变化回调             | `(value: SelectionValue) => void`                    | -              |
+| onClear        | 清空回调               | `() => void`                                         | -              |
+| disabled       | 是否禁用               | `boolean`                                            | `false`        |
+| fieldNames     | 自定义字段名           | `{ label?: string; value?: string; cover?: string }` | -              |
+| layout         | 布局配置（高级）       | `LayoutConfig`                                       | -              |
+| itemLayout     | 选项布局方向           | `'horizontal' \| 'vertical'`                         | `'horizontal'` |
+| itemProps      | 选项配置               | `ItemProps`                                          | -              |
+| titleProps     | 标题配置               | `TitleProps`                                         | -              |
+| ruleConfig     | 校验规则配置           | `RuleConfig`                                         | -              |
+| renderItem     | 自定义选项渲染         | `(props: RenderItemProps) => ReactNode`              | -              |
+| indicatorProps | 指示器配置             | `IndicatorProps`                                     | -              |
+| showStepper    | 是否显示数量选择       | `true \| false \| 'auto'`                            | `'auto'`       |
+| stepperProps   | 数量选择器配置         | `StepperProps`                                       | -              |
+| className      | 自定义类名             | `string`                                             | -              |
+| style          | 自定义样式             | `CSSProperties`                                      | -              |
+
+### SelectorGroup
+
+| 参数                | 说明               | 类型                                               | 默认值               |
+| ------------------- | ------------------ | -------------------------------------------------- | -------------------- |
+| dataSource          | 选择器组数据源     | `GroupItem[]`                                      | `[]`                 |
+| linkageRules        | 联动规则           | `ExprRule[] \| Record<string, any>`                | -                    |
+| allowedValuesPolicy | 允许值策略         | `'relaxed' \| 'strict'`                            | `'strict'`           |
+| preserve            | 是否保留隐藏组的值 | `boolean`                                          | `false`              |
+| value               | 当前值（受控）     | `Record<string, SelectionValue>`                   | -                    |
+| defaultValue        | 默认值（非受控）   | `Record<string, SelectionValue>`                   | -                    |
+| onChange            | 值变化回调         | `(values: Record<string, SelectionValue>) => void` | -                    |
+| tabProps            | 标签页配置         | `{ visible?: boolean }`                            | `{ visible: false }` |
+| customScrollParent  | 自定义滚动容器     | `HTMLElement \| string`                            | -                    |
+| className           | 自定义类名         | `string`                                           | -                    |
+| style               | 自定义样式         | `CSSProperties`                                    | -                    |
+
+### PresetConfig
+
+| 参数    | 说明                                                             | 类型                              | 默认值 |
+| ------- | ---------------------------------------------------------------- | --------------------------------- | ------ |
+| variant | 预设变体（不同 variant 支持的 preset 数量不同，详见下方说明） | `'1' \| '2' \| '3' \| '4' \| '5'` | -      |
+
+**支持的 Preset Variant：**
+- `default`: 支持 variant '1', '2', '3', '4'
+- `card`: 支持 variant '1', '2', '3', '4', '5'
+- `media`: 支持 variant '1', '2'（自动应用 filled 指示器）
+- `select`: 仅支持 variant '1'（下拉选择器）
+
+### LayoutConfig
+
+| 参数      | 说明                                               | 类型                                                                     | 默认值 |
+| --------- | -------------------------------------------------- | ------------------------------------------------------------------------ | ------ |
+| type      | 布局类型                                           | `'flex' \| 'grid' \| 'antdGrid'`                                         | -      |
+| gutter    | 子元素间距                                         | `number \| object \| Array<number>`                                      | `0`    |
+| wrap      | 是否换行                                           | `boolean`                                                                | `true` |
+| direction | Flex 布局方向（仅 type='flex' 时生效）            | `'row' \| 'column'`                                                      | -      |
+| baseWidth | CSS Grid 基础列宽（仅 type='grid' 时生效）        | `string`（如 '209px', 'auto', '100%'）                                   | -      |
+| columns   | 网格列数（仅 type='antdGrid' 时生效）             | `number`                                                                 | -      |
+| align     | 垂直对齐（仅 type='antdGrid' 时生效）             | `'top' \| 'middle' \| 'bottom' \| 'stretch'`                             | -      |
+| justify   | 水平对齐（仅 type='antdGrid' 时生效）             | `'start' \| 'end' \| 'center' \| 'space-between' \| 'space-around'`      | -      |
+| colConfig | 列配置（仅 type='antdGrid' 时生效）               | `object`（如 `{ xs: 24, sm: 12, md: 8 }`）                               | -      |
+
+### OptionItem
+
+| 参数       | 说明               | 类型                             | 默认值  |
+| ---------- | ------------------ | -------------------------------- | ------- |
+| id         | 选项唯一标识       | `number \| string`               | -       |
+| title      | 选项标题           | `string`                         | -       |
+| label      | 选项标签           | `string`                         | -       |
+| value      | 选项值             | `number \| string`               | -       |
+| cover      | 封面图片           | `string`                         | -       |
+| disabled   | 是否禁用           | `boolean`                        | `false` |
+| groups     | 选项组列表（预留） | `GroupItem[]`                    | -       |
+| ruleConfig | 选项级别的规则配置 | `{ min?: number; max?: number }` | -       |
+
+### RuleConfig
+
+| 参数            | 说明         | 类型                                       | 默认值  |
+| --------------- | ------------ | ------------------------------------------ | ------- |
+| required        | 是否必填     | `0 \| 1`                                   | `0`     |
+| autoValidate    | 是否自动校验 | `boolean`                                  | `false` |
+| min             | 最小选择数量 | `number`                                   | -       |
+| max             | 最大选择数量 | `number`                                   | -       |
+| mutex           | 互斥组配置   | `Array<Array<OptionKey>>`                  | -       |
+| customValidator | 自定义校验器 | `(value: SelectionValue) => Promise<void>` | -       |
+
+### RenderItemProps（自定义渲染参数）
+
+| 参数            | 说明           | 类型             |
+| --------------- | -------------- | ---------------- |
+| dataSource      | 选项数据       | `OptionItem`     |
+| actions         | 操作对象       | `any`            |
+| optionItemValue | 选项当前值     | `SelectionValue` |
+| indicator       | 指示器节点     | `ReactNode`      |
+| numberSelector  | 数量选择器节点 | `ReactNode`      |
+| values          | 当前所有值     | `SelectionValue` |
+| quantityInfo    | 数量信息       | `QuantityInfo`   |
+
+### ItemProps（选项配置）
+
+| 参数              | 说明             | 类型                                                                                        | 默认值         |
+| ----------------- | ---------------- | ------------------------------------------------------------------------------------------- | -------------- |
+| layout            | 布局方向         | `'horizontal' \| 'vertical'`                                                                | `'horizontal'` |
+| renderContent     | 自定义内容渲染   | `(props: { dataSource: OptionItem }) => ReactNode`                                          | -              |
+| styles            | 自定义样式       | `{ container?: CSSProperties; cover?: CSSProperties; label?: CSSProperties }`               | -              |
+
+### IndicatorProps（指示器配置）
+
+| 参数    | 说明           | 类型                                                                                              | 默认值      |
+| ------- | -------------- | ------------------------------------------------------------------------------------------------- | ----------- |
+| show    | 是否展示指示器 | `boolean`                                                                                         | `true`      |
+| variant | 指示器样式变体 | `'outlined' \| 'filled'`                                                                          | `'outlined'` |
+| render  | 自定义指示器   | `(props: { option: OptionItem; selected: boolean; disabled: boolean; actions: any }) => ReactNode` | -           |
+
+### StepperProps（数量选择器配置）
+
+| 参数  | 说明 | 类型                             | 默认值 |
+| ----- | ---- | -------------------------------- | ------ |
+| size  | 尺寸 | `'small' \| 'middle' \| 'large'` | -      |
+| shape | 形状 | `'round' \| 'square'`            | -      |
+
+### TitleProps
+
+| 参数        | 说明         | 类型                                                                         | 默认值 |
+| ----------- | ------------ | ---------------------------------------------------------------------------- | ------ |
+| visible     | 是否显示标题 | `boolean`                                                                    | `true` |
+| style       | 标题容器样式 | `CSSProperties`                                                              | -      |
+| title       | 标题文本配置 | `{ visible?: boolean; text?: ReactNode; style?: CSSProperties }`             | -      |
+| icon        | 图标配置     | `{ visible?: boolean; icon?: ReactNode; style?: CSSProperties }`             | -      |
+| tip         | 提示文本配置 | `{ visible?: boolean; text?: ReactNode; style?: CSSProperties }`             | -      |
+| renderExtra | 自定义额外内容 | `(props: { dataSource: OptionItem; values: SelectionValue }) => ReactNode` | -      |
+
+### LinkageRule（联动规则）
+
+| 参数           | 说明          | 类型                                      | 默认值   |
+| -------------- | ------------- | ----------------------------------------- | -------- |
+| type           | 规则类型      | `'expr'`                                  | `'expr'` |
+| when           | 触发条件      | `{ and?: Condition[]; or?: Condition[] }` | -        |
+| then           | 执行动作      | `Action[]`                                | -        |
+| elseThen       | else 分支动作 | `Action[]`                                | -        |
+| priority       | 优先级        | `number`                                  | `0`      |
+| stopAfterApply | 是否短路      | `boolean`                                 | `false`  |
+
+#### Condition（条件）
+
+| 参数    | 说明    | 类型                                                      |
+| ------- | ------- | --------------------------------------------------------- |
+| groupId | 分组 ID | `string`                                                  |
+| op      | 操作符  | `'eq' \| 'ne' \| 'in' \| 'notIn' \| 'hasAny' \| 'hasAll'` |
+| value   | 比较值  | `any \| any[]`                                            |
+
+#### Action（动作）
+
+**显示/隐藏分组：**
+
+```typescript
+{
+  type: 'show' | 'hide';
+  groupId: string;
+}
+```
+
+**限制可选项：**
+
+```typescript
+{
+  type: 'allowOnly';
+  groupId: string;
+  values: any[];
+  message?: string;  // 校验失败提示
+  tip?: string;      // 标题提示文本
+}
+```
+
+**必选指定项之一：**
+
+```typescript
+{
+  type: 'requireOneOf';
+  groupId: string;
+  values: any[];
+  message?: string;  // 校验失败提示
+  tip?: string;      // 标题提示文本
+}
+```
+
+### SelectionValue（值类型）
+
+根据 `mode` 和 `valueType` 的不同，值类型有以下几种形式：
+
+**单选 + primitive：**
+
+```typescript
+value: string | number;
+// 例如：'burger' 或 1
+```
+
+**单选 + object：**
+
+```typescript
+value: {
+  value: string | number;
+  quantity?: number;
+  [key: string]: any;
+}
+// 例如：{ value: 'burger', quantity: 2 }
+```
+
+**多选 + primitive：**
+
+```typescript
+value: Array<string | number>;
+// 例如：['lettuce', 'tomato', 'cheese'] 或 [1, 2, 3]
+```
+
+**多选 + object：**
+
+```typescript
+value: Array<{
+  value: string | number;
+  quantity?: number;
+  [key: string]: any;
+}>;
+// 例如：[
+//   { value: 'lettuce', quantity: 1 },
+//   { value: 'tomato', quantity: 2 }
+// ]
+```
+
+### Ref 方法
+
+#### Selector Ref
+
+| 方法      | 说明         | 类型                  |
+| --------- | ------------ | --------------------- |
+| validate  | 执行校验     | `() => Promise<void>` |
+| getErrors | 获取错误信息 | `() => any[]`         |
+| reset     | 重置为默认值 | `() => void`          |
+| clear     | 清空值       | `() => void`          |
+
+#### SelectorGroup Ref
+
+| 方法      | 说明           | 类型                                                          |
+| --------- | -------------- | ------------------------------------------------------------- |
+| getValues | 获取所有值     | `(includeHidden?: boolean) => Record<string, SelectionValue>` |
+| setValues | 设置所有值     | `(values: Record<string, SelectionValue>) => void`            |
+| validate  | 执行所有组校验 | `() => Promise<Record<string, never>>`                        |
+| reset     | 重置所有组     | `() => void`                                                  |
+| clear     | 清空所有组     | `() => void`                                                  |
+
+## 注意事项
+
+1. **Preset vs Layout**：
+   - 使用 `preset` 时无需配置 `layout`，系统会自动应用预设布局
+   - 如果同时指定 `preset` 和 `layout`，`layout` 的配置优先级更高
+   - 建议非专业用户使用 `preset`，专业开发者根据需要使用 `layout` 精确控制
+
+2. **valueType 选择**：当需要记录数量信息时，使用 `valueType="object"`；否则使用 `valueType="primitive"` 可获得更简洁的数据结构。
+
+3. **fieldNames 配置**：确保 `fieldNames` 中的字段名与 `dataSource` 中的实际字段名一致。
+
+4. **联动规则优先级**：多条规则同时生效时，`priority` 值越大优先级越高。
+
+5. **allowedValuesPolicy**：
+   - `strict` 模式：当选项被禁用时，会自动清除该选项的已选状态
+   - `relaxed` 模式：保留已选状态，但选项会被禁用
+
+6. **性能优化**：大量选项时建议使用虚拟滚动或分组展示。
+
+7. **校验时机**：设置 `autoValidate: true` 后会在值变化时自动校验，否则需要手动调用 `validate()` 方法。
+
+8. **Preset 自动应用的 indicator 样式**：
+   - `media` variant 的所有 preset 会自动应用 `filled` 风格的指示器
+   - `card` variant 的 preset '2' 会自动应用 `filled` 风格的指示器