@pisell/materials 1.8.41 → 1.8.42

package/lib/components/pisellSingleSelect/docs/pisellSingleSelect.md

@@ -3,7 +3,7 @@ nav:
   title: 组件
   order: 1
 group:
-  title: Form Fields
+  title: General
   order: 1
 title: PisellSingleSelect
 order: 1
@@ -12,134 +12,92 @@ category: pro
 
 # PisellSingleSelect 单选下拉组件
 
-PisellSingleSelect 是基于 Ant Design Select 封装的单选表单组件，提供只读/编辑/禁用三种状态、搜索过滤、受控与非受控模式，适用于表单与表格中的单选场景。
+## 组件介绍
 
-## 何时使用
+PisellSingleSelect 是 Pisell 2.0 组件库中处理单选数据的基础表单组件。它基于 Ant Design Select 组件封装，提供了符合 Pisell
+设计规范的单选功能、搜索过滤、状态管理等核心能力，适用于各种单选场景。
 
-- 表单中需要单选一项（分类、状态、城市等）
-- 表格列中需要只读展示选项文案
-- 需要带搜索、清空、必填校验的单选控件
+**核心特性**：
 
-## 特性
+- ✅ 三种交互状态：只读、编辑、禁用
+- ✅ 搜索与过滤：支持防抖搜索和自定义过滤逻辑
+- ✅ 完整的状态管理：受控和非受控模式
+- ✅ 样式定制：基于 Token 系统和 Less
+- ✅ 基于 Ant Design Select 开发
+- ✅ 复用逻辑抽取到 @pisell/utils
 
-- 三种交互状态：只读、编辑、禁用
-- 搜索与过滤：支持防抖搜索和自定义 `filterOption`
-- 受控与非受控模式
-- 样式：Token、Less、className/style
-- 基于 Ant Design Select，逻辑复用 @pisell/utils
+---
 
 ## 基础用法
 
-### 受控模式
+### 基础示例（受控模式）
 
 ```tsx
-import React, { useState } from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
+import {PisellSingleSelect} from '@pisell/materials';
+import {useState} from 'react';
 
 const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
+    {value: 'apple', label: '苹果'},
+    {value: 'banana', label: '香蕉'},
+    {value: 'orange', label: '橙子'},
 ];
 
 export default () => {
-  const [value, setValue] = useState<string | null>(null);
-  return (
-    <PisellSingleSelect
-      options={fruitOptions}
-      value={value}
-      onChange={(val) => setValue(val)}
-      placeholder="请选择一种水果"
-    />
-  );
-};
+    const [value, setValue] = useState<string | null>(null);
+
+    return (
+        <PisellSingleSelect
+            options={fruitOptions}
+            value={value}
+            onChange={(val) => setValue(val)}
+            placeholder="请选择一种水果"
+        />
+    );
+}
 ```
 
 ### 非受控模式
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={fruitOptions}
     defaultValue="apple"
     placeholder="请选择"
-  />
-);
+/>
 ```
 
 ### 带标签和辅助文本
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={fruitOptions}
     label="最爱水果"
     helperText="请选择你最喜欢的水果"
     placeholder="请选择"
     required
-  />
-);
+/>
 ```
 
 ### 只读态展示
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={fruitOptions}
     value="apple"
     readOnly
     label="已选择的水果"
-  />
-);
+/>
+// 显示: 苹果
 ```
 
 ### 禁用态
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={fruitOptions}
     value="apple"
     disabled
-  />
-);
+/>
 ```
 
 ---
@@ -148,84 +106,46 @@ export default () => (
 
 ### 基础搜索
 
-```tsx
-import React, { useState } from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const cityOptions = [
-  { value: 'beijing', label: '北京' },
-  { value: 'shanghai', label: '上海' },
-  { value: 'guangzhou', label: '广州' },
-  { value: 'shenzhen', label: '深圳' },
-];
-
-export default () => {
-  const [value, setValue] = useState<string | null>(null);
-  return (
-    <PisellSingleSelect
-      options={cityOptions}
-      label="选择城市"
-      placeholder="搜索城市..."
-      showSearch
-      value={value}
-      onChange={setValue}
-    />
-  );
-};
+```
+<PisellSingleSelect
+    options={cityOptions}
+    label="选择城市"
+    placeholder="搜索城市..."
+    showSearch
+    value={value}
+    onChange={setValue}
+/>
 ```
 
 ### 自定义过滤逻辑
 
-```tsx
-import React, { useState } from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const cityOptions = [
-  { value: 'beijing', label: '北京' },
-  { value: 'shanghai', label: '上海' },
-  { value: 'guangzhou', label: '广州' },
-  { value: 'shenzhen', label: '深圳' },
-];
-
-export default () => {
-  const [value, setValue] = useState<string | null>(null);
-  return (
-    <PisellSingleSelect
-      options={cityOptions}
-      label="选择城市"
-      placeholder="输入城市名..."
-      showSearch
-      value={value}
-      onChange={setValue}
-      filterOption={(input, option) =>
-        option.label.toLowerCase().includes(input.toLowerCase()) ||
-        String(option.value).includes(input)
-      }
-    />
-  );
-};
+```
+<PisellSingleSelect
+    options={cityOptions}
+    label="选择城市"
+    placeholder="输入城市名..."
+    showSearch
+    value={value}
+    onChange={setValue}
+    filterOption={(input, option) => {
+        // 自定义过滤：支持模糊匹配
+        return option.label.toLowerCase().includes(input.toLowerCase()) ||
+            option.value.toString().includes(input);
+    }}
+/>
 ```
 
 ### 搜索回调
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const options = [
-  { value: 'a', label: '选项 A' },
-  { value: 'b', label: '选项 B' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={options}
     showSearch
     onSearch={(keyword) => {
-      console.log('搜索关键词:', keyword);
+        console.log('搜索关键词:', keyword);
+        // 可以在这里触发远程搜索
     }}
-  />
-);
+/>
 ```
 
 ---
@@ -234,70 +154,51 @@ export default () => (
 
 ### 显示错误状态
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={fruitOptions}
     label="选择水果"
     value={null}
     required
     error
     errorText="此项为必填项，请选择"
-  />
-);
+/>
 ```
 
 ### 表单校验场景
 
-```tsx
-import React, { useState } from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
+```
 export default () => {
-  const [value, setValue] = useState<string | null>(null);
-  const [error, setError] = useState(false);
-
-  const handleSubmit = () => {
-    if (!value) setError(true);
-    else {
-      setError(false);
-      console.log('提交值:', value);
-    }
-  };
-
-  return (
-    <div>
-      <PisellSingleSelect
-        options={fruitOptions}
-        label="选择水果（必填）"
-        value={value}
-        onChange={(val) => {
-          setValue(val);
-          setError(false);
-        }}
-        required
-        error={error}
-        errorText="请选择一个选项"
-      />
-      <button type="button" onClick={handleSubmit}>提交</button>
-    </div>
-  );
-};
+    const [value, setValue] = useState<string | null>(null);
+    const [error, setError] = useState(false);
+
+    const handleSubmit = () => {
+        if (!value) {
+            setError(true);
+        } else {
+            setError(false);
+            console.log('提交值:', value);
+        }
+    };
+
+    return (
+        <div>
+            <PisellSingleSelect
+                options={fruitOptions}
+                label="选择水果（必填）"
+                value={value}
+                onChange={(val) => {
+                    setValue(val);
+                    setError(false); // 清除错误
+                }}
+                required
+                error={error}
+                errorText="请选择一个选项"
+            />
+            <button onClick={handleSubmit}>提交</button>
+        </div>
+    );
+}
 ```
 
 ---
@@ -306,48 +207,26 @@ export default () => {
 
 ### 清空按钮
 
-```tsx
-import React, { useState } from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => {
-  const [value, setValue] = useState<string | null>(null);
-  return (
-    <PisellSingleSelect
-      options={fruitOptions}
-      value={value}
-      onChange={setValue}
-      allowClear
-    />
-  );
-};
+```
+<PisellSingleSelect
+    options={fruitOptions}
+    value={value}
+    onChange={setValue}
+    allowClear
+/>
 ```
 
 ### 不同尺寸
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
+```
+// 小尺寸
+<PisellSingleSelect options={fruitOptions} size="small"/>
 
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
+// 中等尺寸（默认）
+<PisellSingleSelect options={fruitOptions} size="medium"/>
 
-export default () => (
-  <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap' }}>
-    <PisellSingleSelect options={fruitOptions} size="small" placeholder="小" />
-    <PisellSingleSelect options={fruitOptions} size="medium" placeholder="中" />
-    <PisellSingleSelect options={fruitOptions} size="large" placeholder="大" />
-  </div>
-);
+// 大尺寸
+<PisellSingleSelect options={fruitOptions} size="large"/>
 ```
 
 ---
@@ -356,68 +235,39 @@ export default () => (
 
 ### 值变化回调
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={fruitOptions}
     onChange={(value, option) => {
-      console.log('选中值:', value);
-      console.log('选中选项:', option);
+        console.log('选中值:', value);
+        console.log('选中选项:', option);
     }}
-  />
-);
+/>
 ```
 
 ### 焦点事件
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={fruitOptions}
-    onFocus={() => console.log('获得焦点')}
-    onBlur={() => console.log('失去焦点')}
-  />
-);
+    onFocus={(event) => {
+        console.log('获得焦点');
+    }}
+    onBlur={(event) => {
+        console.log('失去焦点');
+    }}
+/>
 ```
 
 ### 下拉框显隐
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={fruitOptions}
     onDropdownVisibleChange={(visible) => {
-      console.log('下拉框', visible ? '打开' : '关闭');
+        console.log('下拉框', visible ? '打开' : '关闭');
     }}
-  />
-);
+/>
 ```
 
 ---
@@ -427,53 +277,55 @@ export default () => (
 ### 在 Form 中使用
 
 ```tsx
-import React, { useState } from 'react';
-import { Form } from 'antd';
-import { PisellSingleSelect } from '@pisell/materials';
+import {Form} from 'antd';
+import {PisellSingleSelect} from '@pisell/materials';
+import {useState} from 'react';
 
 const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
+    {value: 'apple', label: '苹果'},
+    {value: 'banana', label: '香蕉'},
+    {value: 'orange', label: '橙子'},
 ];
 
 const cityOptions = [
-  { value: 'beijing', label: '北京' },
-  { value: 'shanghai', label: '上海' },
-  { value: 'guangzhou', label: '广州' },
-  { value: 'shenzhen', label: '深圳' },
-  { value: 'chengdu', label: '成都' },
-  { value: 'hangzhou', label: '杭州' },
+    {value: 'beijing', label: '北京'},
+    {value: 'shanghai', label: '上海'},
+    {value: 'guangzhou', label: '广州'},
+    {value: 'shenzhen', label: '深圳'},
+    {value: 'chengdu', label: '成都'},
+    {value: 'hangzhou', label: '杭州'},
+    // ... 更多城市
 ];
 
 export default () => {
-  const [fruit, setFruit] = useState<string | null>(null);
-  const [city, setCity] = useState<string | null>(null);
-
-  return (
-    <Form layout="vertical" style={{ maxWidth: 400 }}>
-      <Form.Item label="最爱水果（必填）">
-        <PisellSingleSelect
-          options={fruitOptions}
-          value={fruit}
-          onChange={setFruit}
-          placeholder="请选择水果"
-          required
-        />
-      </Form.Item>
-      <Form.Item label="所在城市">
-        <PisellSingleSelect
-          options={cityOptions}
-          value={city}
-          onChange={setCity}
-          placeholder="请选择城市"
-          showSearch
-          allowClear
-        />
-      </Form.Item>
-    </Form>
-  );
-};
+    const [fruit, setFruit] = useState<string | null>(null);
+    const [city, setCity] = useState<string | null>(null);
+
+    return (
+        <Form layout="vertical" style={{maxWidth: 400}}>
+            <Form.Item label="最爱水果（必填）">
+                <PisellSingleSelect
+                    options={fruitOptions}
+                    value={fruit}
+                    onChange={setFruit}
+                    placeholder="请选择水果"
+                    required
+                />
+            </Form.Item>
+
+            <Form.Item label="所在城市">
+                <PisellSingleSelect
+                    options={cityOptions}
+                    value={city}
+                    onChange={setCity}
+                    placeholder="请选择城市"
+                    showSearch
+                    allowClear
+                />
+            </Form.Item>
+        </Form>
+    );
+}
 ```
 
 ---
@@ -483,37 +335,41 @@ export default () => {
 ### 表格列中使用（只读态）
 
 ```tsx
-import React from 'react';
-import { Table } from 'antd';
-import { PisellSingleSelect } from '@pisell/materials';
+import {Table} from 'antd';
+import {PisellSingleSelect} from '@pisell/materials';
 
 const statusOptions = [
-  { value: 'active', label: '激活' },
-  { value: 'inactive', label: '未激活' },
-  { value: 'pending', label: '待审核' },
+    {value: 'active', label: '激活'},
+    {value: 'inactive', label: '未激活'},
+    {value: 'pending', label: '待审核'},
 ];
 
 const columns = [
-  { title: '用户名', dataIndex: 'name' },
-  {
-    title: '状态',
-    dataIndex: 'status',
-    render: (value: string) => (
-      <PisellSingleSelect
-        options={statusOptions}
-        value={value}
-        readOnly
-      />
-    ),
-  },
+    {
+        title: '用户名',
+        dataIndex: 'name',
+    },
+    {
+        title: '状态',
+        dataIndex: 'status',
+        render: (value: string) => (
+            <PisellSingleSelect
+                options={statusOptions}
+                value={value}
+                readOnly
+            />
+        ),
+    },
 ];
 
 const dataSource = [
-  { id: 1, name: '张三', status: 'active' },
-  { id: 2, name: '李四', status: 'pending' },
+    {id: 1, name: '张三', status: 'active'},
+    {id: 2, name: '李四', status: 'pending'},
 ];
 
-export default () => <Table dataSource={dataSource} columns={columns} rowKey="id" />;
+export default () => {
+    return <Table dataSource={dataSource} columns={columns}/>;
+}
 ```
 
 ---
@@ -523,27 +379,45 @@ export default () => <Table dataSource={dataSource} columns={columns} rowKey="id
 ### 使用 Ref 控制组件
 
 ```tsx
-import React, { useRef } from 'react';
-import { PisellSingleSelect, type SingleSelectRef } from '@pisell/materials';
+import {useRef} from 'react';
+import {PisellSingleSelect} from '@pisell/materials';
+import type {SingleSelectRef} from '@pisell/materials';
 
 const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
+    {value: 'apple', label: '苹果'},
+    {value: 'banana', label: '香蕉'},
+    {value: 'orange', label: '橙子'},
 ];
 
-export default () => {
-  const selectRef = useRef<SingleSelectRef>(null);
 
-  return (
-    <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
-      <PisellSingleSelect ref={selectRef} options={fruitOptions} />
-      <button type="button" onClick={() => selectRef.current?.focus()}>聚焦</button>
-      <button type="button" onClick={() => selectRef.current?.clearValue()}>清空</button>
-      <button type="button" onClick={() => console.log(selectRef.current?.getValue())}>获取值</button>
-    </div>
-  );
-};
+export default () => {
+    const selectRef = useRef<SingleSelectRef>(null);
+
+    const handleFocus = () => {
+        selectRef.current?.focus();
+    };
+
+    const handleClear = () => {
+        selectRef.current?.clearValue();
+    };
+
+    const handleGetValue = () => {
+        const currentValue = selectRef.current?.getValue();
+        console.log('当前值:', currentValue);
+    };
+
+    return (
+        <div>
+            <PisellSingleSelect
+                ref={selectRef}
+                options={fruitOptions}
+            />
+            <button onClick={handleFocus}>聚焦</button>
+            <button onClick={handleClear}>清空</button>
+            <button onClick={handleGetValue}>获取值</button>
+        </div>
+    );
+}
 ```
 
 ---
@@ -552,80 +426,79 @@ export default () => {
 
 ### 自定义类名和样式
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-  { value: 'orange', label: '橙子' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={fruitOptions}
     className="custom-select"
-    style={{ width: 300 }}
-  />
-);
+    style={{width: 300}}
+/>
 ```
 
 ### 通过 Token 定制（全局）
 
-在项目的 theme tokens 中修改 Select 相关 Token（如 `fontSize`、`controlHeight`、`borderRadius`、`colorBorder` 等）。
+在 `packages/materials/src/theme/tokens.ts` 中修改 Select Token：
+
+```
+Select: {
+  fontSize: 16,
+  controlHeight: 48,
+  borderRadius: 8,
+  colorBorder: '#D0D5DD',
+  // ... 其他配置
+}
+```
 
 ### 通过 Less 定制（组件级别）
 
-在组件 Less 或业务 Less 中覆盖 `.pisell-single-select` 相关类名实现组件级定制。
+在 `PisellSingleSelect.less` 中添加自定义样式。
 
 ---
 
-## API
-
-### Props
-
-| 属性名              | 类型                               | 默认值        | 必填 | 说明           |
-|------------------|----------------------------------|------------|-----|--------------|
-| **核心数据**         |                                  |            |     |              |
-| options          | `SelectOption<T>[]`              | -          | ✅  | 选项列表       |
-| value            | `T \| null`                      | -          | ❌  | 当前选中值（受控）    |
-| defaultValue     | `T`                              | -          | ❌  | 默认值（非受控）     |
-| **交互控制**         |                                  |            |     |              |
-| placeholder      | `string`                         | `'请选择'`    | ❌  | 占位符文本        |
-| showSearch       | `boolean`                        | `false`    | ❌  | 是否显示搜索框      |
-| allowClear       | `boolean`                        | `false`    | ❌  | 是否显示清空按钮     |
-| disabled         | `boolean`                        | `false`    | ❌  | 是否禁用         |
-| readOnly         | `boolean`                        | `false`    | ❌  | 是否只读         |
-| **样式与布局**        |                                  |            |     |              |
-| size             | `'small' \| 'medium' \| 'large'` | `'medium'` | ❌  | 尺寸           |
-| className        | `string`                         | -          | ❌  | 自定义类名        |
-| style            | `CSSProperties`                  | -          | ❌  | 自定义样式        |
-| **表单标签与校验**      |                                  |            |     |              |
-| label            | `string`                         | -          | ❌  | 标签文本         |
-| helperText       | `string`                         | -          | ❌  | 辅助提示文本       |
-| required         | `boolean`                        | `false`    | ❌  | 是否必填         |
-| error            | `boolean`                        | `false`    | ❌  | 是否显示错误状态     |
-| errorText        | `string`                         | -          | ❌  | 错误提示文本       |
-| **筛选与排序**        |                                  |            |     |              |
-| filterable       | `boolean`                        | `false`    | ❌  | 是否启用过滤       |
-| filterOption     | `(input, option) => boolean`     | -          | ❌  | 自定义过滤函数      |
-| sortable         | `boolean`                        | `false`    | ❌  | 是否启用排序       |
-| sortDirection    | `'asc' \| 'desc'`                | -          | ❌  | 排序方向         |
-| **无障碍访问**        |                                  |            |     |              |
-| aria-label       | `string`                         | -          | ❌  | ARIA 标签      |
-| aria-required    | `boolean`                        | -          | ❌  | ARIA 是否必填    |
-| aria-invalid     | `boolean`                        | -          | ❌  | ARIA 是否无效    |
-| aria-describedby | `string`                         | -          | ❌  | ARIA 描述关联 ID |
+## API 文档
+
+### Props 属性
+
+| 属性名              | 类型                               | 默认值        | 说明           |
+|------------------|----------------------------------|------------|--------------|
+| **核心数据**         |                                  |            |              |
+| options          | `SelectOption<T>[]`              | -          | 选项列表（必填）     |
+| value            | `T \| null`                      | -          | 当前选中值（受控）    |
+| defaultValue     | `T`                              | -          | 默认值（非受控）     |
+| **交互控制**         |                                  |            |              |
+| placeholder      | `string`                         | `'请选择'`    | 占位符文本        |
+| showSearch       | `boolean`                        | `false`    | 是否显示搜索框      |
+| allowClear       | `boolean`                        | `false`    | 是否显示清空按钮     |
+| disabled         | `boolean`                        | `false`    | 是否禁用         |
+| readOnly         | `boolean`                        | `false`    | 是否只读         |
+| **样式与布局**        |                                  |            |              |
+| size             | `'small' \| 'medium' \| 'large'` | `'medium'` | 尺寸           |
+| className        | `string`                         | -          | 自定义类名        |
+| style            | `CSSProperties`                  | -          | 自定义样式        |
+| **表单标签与校验**      |                                  |            |              |
+| label            | `string`                         | -          | 标签文本         |
+| helperText       | `string`                         | -          | 辅助提示文本       |
+| required         | `boolean`                        | `false`    | 是否必填         |
+| error            | `boolean`                        | `false`    | 是否显示错误状态     |
+| errorText        | `string`                         | -          | 错误提示文本       |
+| **筛选与排序**        |                                  |            |              |
+| filterable       | `boolean`                        | `false`    | 是否启用过滤       |
+| filterOption     | `(input, option) => boolean`     | -          | 自定义过滤函数      |
+| sortable         | `boolean`                        | `false`    | 是否启用排序       |
+| sortDirection    | `'asc' \| 'desc'`                | -          | 排序方向         |
+| **无障碍访问**        |                                  |            |              |
+| aria-label       | `string`                         | -          | ARIA 标签      |
+| aria-required    | `boolean`                        | -          | ARIA 是否必填    |
+| aria-invalid     | `boolean`                        | -          | ARIA 是否无效    |
+| aria-describedby | `string`                         | -          | ARIA 描述关联 ID |
 
 ### SelectOption 类型
 
-```ts
+```
 interface SelectOption<T = string | number> {
-  value: T;           // 选项值（唯一标识）
-  label: string;      // 选项显示文本
-  disabled?: boolean; // 是否禁用该选项
-  icon?: ReactNode;   // 选项图标
+    value: T;           // 选项值（唯一标识）
+    label: string;      // 选项显示文本
+    disabled?: boolean; // 是否禁用该选项
+    icon?: ReactNode;   // 选项图标
 }
 ```
 
@@ -656,71 +529,80 @@ interface SelectOption<T = string | number> {
 ### 商品分类选择
 
 ```tsx
-import React, { useState } from 'react';
-import { Form } from 'antd';
-import { PisellSingleSelect } from '@pisell/materials';
+import {Form} from 'antd';
+import {PisellSingleSelect} from '@pisell/materials';
+import {useState} from 'react';
 
 const categoryOptions = [
-  { value: 'electronics', label: '电子产品' },
-  { value: 'clothing', label: '服装' },
-  { value: 'food', label: '食品' },
-  { value: 'books', label: '图书' },
+    {value: 'electronics', label: '电子产品'},
+    {value: 'clothing', label: '服装'},
+    {value: 'food', label: '食品'},
+    {value: 'books', label: '图书'},
 ];
 
 export default () => {
-  const [category, setCategory] = useState<string | null>(null);
-  const [error, setError] = useState(false);
-
-  return (
-    <Form.Item label="商品分类" required>
-      <PisellSingleSelect
-        options={categoryOptions}
-        value={category}
-        onChange={(val) => {
-          setCategory(val);
-          setError(false);
-        }}
-        placeholder="请选择商品分类"
-        error={error}
-        errorText="请选择商品分类"
-        allowClear
-      />
-    </Form.Item>
-  );
-};
+    const [category, setCategory] = useState<string | null>(null);
+    const [error, setError] = useState(false);
+
+    const handleSubmit = () => {
+        if (!category) {
+            setError(true);
+            return;
+        }
+        console.log('选中分类:', category);
+    };
+
+    return (
+        <Form.Item label="商品分类" required>
+            <PisellSingleSelect
+                options={categoryOptions}
+                value={category}
+                onChange={(val) => {
+                    setCategory(val);
+                    setError(false);
+                }}
+                placeholder="请选择商品分类"
+                error={error}
+                errorText="请选择商品分类"
+                allowClear
+            />
+        </Form.Item>
+    );
+}
 ```
 
 ### 城市选择（带搜索）
 
-```tsx
-import React, { useState } from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
+```
 const cityOptions = [
-  { value: 'beijing', label: '北京' },
-  { value: 'shanghai', label: '上海' },
-  { value: 'guangzhou', label: '广州' },
-  { value: 'shenzhen', label: '深圳' },
-  { value: 'chengdu', label: '成都' },
-  { value: 'hangzhou', label: '杭州' },
+    {value: 'beijing', label: '北京'},
+    {value: 'shanghai', label: '上海'},
+    {value: 'guangzhou', label: '广州'},
+    {value: 'shenzhen', label: '深圳'},
+    {value: 'chengdu', label: '成都'},
+    {value: 'hangzhou', label: '杭州'},
+    // ... 更多城市
 ];
 
 export default () => {
-  const [city, setCity] = useState<string | null>(null);
-  return (
-    <PisellSingleSelect
-      options={cityOptions}
-      label="所在城市"
-      helperText="输入城市名快速查找"
-      value={city}
-      onChange={setCity}
-      placeholder="搜索城市..."
-      showSearch
-      allowClear
-      onSearch={(keyword) => console.log('搜索关键词:', keyword)}
-    />
-  );
-};
+    const [city, setCity] = useState<string | null>(null);
+
+    return (
+        <PisellSingleSelect
+            options={cityOptions}
+            label="所在城市"
+            helperText="输入城市名快速查找"
+            value={city}
+            onChange={setCity}
+            placeholder="搜索城市..."
+            showSearch
+            allowClear
+            onSearch={(keyword) => {
+                console.log('搜索关键词:', keyword);
+            }}
+        />
+    );
+}
 ```
 
 ---
@@ -729,78 +611,105 @@ export default () => {
 
 ### 1. 如何处理空值？
 
-只读态空值显示为 `-`，编辑态显示占位符。
+只读态会显示 `-`，编辑态会显示占位符：
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const fruitOptions = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-];
-
-export default () => (
-  <PisellSingleSelect options={fruitOptions} value={null} readOnly label="只读空值" />
-);
+```
+// 只读态显示空值
+<PisellSingleSelect
+    options={fruitOptions}
+    value={null}
+    readOnly
+/>
+// 显示: -
 ```
 
 ### 2. 如何实现搜索功能？
 
-设置 `showSearch` 即可，组件内置防抖。
-
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const options = [
-  { value: 'a', label: '选项 A' },
-  { value: 'b', label: '选项 B' },
-];
+设置 `showSearch={true}`：
 
-export default () => (
-  <PisellSingleSelect options={options} showSearch placeholder="搜索..." />
-);
+```
+<PisellSingleSelect
+    options={options}
+    showSearch
+    placeholder="搜索..."
+/>
 ```
 
 ### 3. 如何自定义过滤逻辑？
 
-使用 `filterOption` 属性。
+使用 `filterOption` 属性：
 
-```tsx
-import React from 'react';
-import { PisellSingleSelect } from '@pisell/materials';
-
-const options = [
-  { value: 'apple', label: '苹果' },
-  { value: 'banana', label: '香蕉' },
-];
-
-export default () => (
-  <PisellSingleSelect
+```
+<PisellSingleSelect
     options={options}
     showSearch
-    filterOption={(input, option) => option.label.includes(input)}
-  />
-);
+    filterOption={(input, option) => {
+        // 自定义过滤逻辑
+        return option.label.includes(input);
+    }}
+/>
+```
+
+### 4. 受控模式和非受控模式有什么区别？
+
+**受控模式**：值由外部管理
+
+```
+const [value, setValue] = useState<string | null>(null);
+<PisellSingleSelect value={value} onChange={setValue}/>
 ```
 
-### 4. 受控与非受控区别
+**非受控模式**：值由组件内部管理
 
-- **受控**：外部通过 `value` + `onChange` 管理。
-- **非受控**：使用 `defaultValue`，组件内部管理。
+```
+<PisellSingleSelect defaultValue="apple"/>
+```
 
 ### 5. 如何在表格中使用？
 
-表格列中用 `readOnly` 展示选项文案，见上文「表格列中使用（只读态）」示例。
+只读态适合在表格中展示：
+
+```
+{
+  title: '状态',
+  dataIndex: 'status',
+  render: (value) => (
+    <PisellSingleSelect
+      options={statusOptions}
+      value={value}
+      readOnly
+    />
+  ),
+}
+```
 
 ### 6. 如何使用 Ref 方法？
 
-通过 `ref` 调用 `focus()`、`getValue()`、`clearValue()` 等，见上文「使用 Ref 控制组件」示例。
+```
+const ref = useRef<SingleSelectRef>(null);
+
+// 聚焦
+ref.current?.focus();
+
+// 获取值
+const value = ref.current?.getValue();
+
+// 清空
+ref.current?.clearValue();
+```
 
 ### 7. 如何自定义样式？
 
-通过 `className`、`style` 传入，或通过项目 Token / Less 覆盖。
+```
+// 方式1：通过 className
+<PisellSingleSelect className="custom-select"/>
+
+// 方式2：通过 style
+<PisellSingleSelect style={{width: 300}}/>
+
+// 方式3：通过 Token（全局）
+// 在 tokens.ts 中修改 Select Token
+```
 
 ---
 
@@ -833,12 +742,6 @@ export default () => (
 
 ---
 
-## 相关文档
-
-- [设计文档](./pisellSingleSelect.$tab-design.md)
-- [开发文档](./pisellSingleSelect.$tab-dev.md)
-- [测试文档](./pisellSingleSelect.$tab-test.md)
-
 ## 相关组件
 
 - **PisellMultipleSelect** - 多选下拉组件