@pisell/materials 1.8.38 → 1.8.41

package/es/components/pisellSingleSelect/docs/pisellSingleSelect.md

@@ -3,7 +3,7 @@ nav:
   title: 组件
   order: 1
 group:
-  title: General
+  title: Form Fields
   order: 1
 title: PisellSingleSelect
 order: 1
@@ -12,92 +12,134 @@ 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 {PisellSingleSelect} from '@pisell/materials';
-import {useState} from 'react';
+import React, { useState } from 'react';
+import { PisellSingleSelect } 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 [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="请选择一种水果"
+    />
+  );
+};
 ```
 
 ### 非受控模式
 
-```
-<PisellSingleSelect
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+export default () => (
+  <PisellSingleSelect
     options={fruitOptions}
     defaultValue="apple"
     placeholder="请选择"
-/>
+  />
+);
 ```
 
 ### 带标签和辅助文本
 
-```
-<PisellSingleSelect
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+export default () => (
+  <PisellSingleSelect
     options={fruitOptions}
     label="最爱水果"
     helperText="请选择你最喜欢的水果"
     placeholder="请选择"
     required
-/>
+  />
+);
 ```
 
 ### 只读态展示
 
-```
-<PisellSingleSelect
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+export default () => (
+  <PisellSingleSelect
     options={fruitOptions}
     value="apple"
     readOnly
     label="已选择的水果"
-/>
-// 显示: 苹果
+  />
+);
 ```
 
 ### 禁用态
 
-```
-<PisellSingleSelect
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+export default () => (
+  <PisellSingleSelect
     options={fruitOptions}
     value="apple"
     disabled
-/>
+  />
+);
 ```
 
 ---
@@ -106,46 +148,84 @@ export default () => {
 
 ### 基础搜索
 
-```
-<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}
+    />
+  );
+};
 ```
 
 ### 自定义过滤逻辑
 
-```
-<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, { 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
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const options = [
+  { value: 'a', label: '选项 A' },
+  { value: 'b', label: '选项 B' },
+];
+
+export default () => (
+  <PisellSingleSelect
     options={options}
     showSearch
     onSearch={(keyword) => {
-        console.log('搜索关键词:', keyword);
-        // 可以在这里触发远程搜索
+      console.log('搜索关键词:', keyword);
     }}
-/>
+  />
+);
 ```
 
 ---
@@ -154,51 +234,70 @@ export default () => {
 
 ### 显示错误状态
 
-```
-<PisellSingleSelect
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+export default () => (
+  <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 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 type="button" onClick={handleSubmit}>提交</button>
+    </div>
+  );
+};
 ```
 
 ---
@@ -207,26 +306,48 @@ export default () => {
 
 ### 清空按钮
 
-```
-<PisellSingleSelect
-    options={fruitOptions}
-    value={value}
-    onChange={setValue}
-    allowClear
-/>
+```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} size="small"/>
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
 
-// 中等尺寸（默认）
-<PisellSingleSelect options={fruitOptions} size="medium"/>
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
 
-// 大尺寸
-<PisellSingleSelect options={fruitOptions} size="large"/>
+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>
+);
 ```
 
 ---
@@ -235,39 +356,68 @@ export default () => {
 
 ### 值变化回调
 
-```
-<PisellSingleSelect
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+export default () => (
+  <PisellSingleSelect
     options={fruitOptions}
     onChange={(value, option) => {
-        console.log('选中值:', value);
-        console.log('选中选项:', option);
+      console.log('选中值:', value);
+      console.log('选中选项:', option);
     }}
-/>
+  />
+);
 ```
 
 ### 焦点事件
 
-```
-<PisellSingleSelect
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+export default () => (
+  <PisellSingleSelect
     options={fruitOptions}
-    onFocus={(event) => {
-        console.log('获得焦点');
-    }}
-    onBlur={(event) => {
-        console.log('失去焦点');
-    }}
-/>
+    onFocus={() => console.log('获得焦点')}
+    onBlur={() => console.log('失去焦点')}
+  />
+);
 ```
 
 ### 下拉框显隐
 
-```
-<PisellSingleSelect
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+export default () => (
+  <PisellSingleSelect
     options={fruitOptions}
     onDropdownVisibleChange={(visible) => {
-        console.log('下拉框', visible ? '打开' : '关闭');
+      console.log('下拉框', visible ? '打开' : '关闭');
     }}
-/>
+  />
+);
 ```
 
 ---
@@ -277,55 +427,53 @@ export default () => {
 ### 在 Form 中使用
 
 ```tsx
-import {Form} from 'antd';
-import {PisellSingleSelect} from '@pisell/materials';
-import {useState} from 'react';
+import React, { useState } from 'react';
+import { Form } from 'antd';
+import { PisellSingleSelect } from '@pisell/materials';
 
 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>
+  );
+};
 ```
 
 ---
@@ -335,41 +483,37 @@ export default () => {
 ### 表格列中使用（只读态）
 
 ```tsx
-import {Table} from 'antd';
-import {PisellSingleSelect} from '@pisell/materials';
+import React from 'react';
+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 () => {
-    return <Table dataSource={dataSource} columns={columns}/>;
-}
+export default () => <Table dataSource={dataSource} columns={columns} rowKey="id" />;
 ```
 
 ---
@@ -379,45 +523,27 @@ export default () => {
 ### 使用 Ref 控制组件
 
 ```tsx
-import {useRef} from 'react';
-import {PisellSingleSelect} from '@pisell/materials';
-import type {SingleSelectRef} from '@pisell/materials';
+import React, { useRef } from 'react';
+import { PisellSingleSelect, 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);
-
-    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>
-    );
-}
+  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>
+  );
+};
 ```
 
 ---
@@ -426,79 +552,80 @@ export default () => {
 
 ### 自定义类名和样式
 
-```
-<PisellSingleSelect
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const fruitOptions = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+  { value: 'orange', label: '橙子' },
+];
+
+export default () => (
+  <PisellSingleSelect
     options={fruitOptions}
     className="custom-select"
-    style={{width: 300}}
-/>
+    style={{ width: 300 }}
+  />
+);
 ```
 
 ### 通过 Token 定制（全局）
 
-在 `packages/materials/src/theme/tokens.ts` 中修改 Select Token：
-
-```
-Select: {
-  fontSize: 16,
-  controlHeight: 48,
-  borderRadius: 8,
-  colorBorder: '#D0D5DD',
-  // ... 其他配置
-}
-```
+在项目的 theme tokens 中修改 Select 相关 Token（如 `fontSize`、`controlHeight`、`borderRadius`、`colorBorder` 等）。
 
 ### 通过 Less 定制（组件级别）
 
-在 `PisellSingleSelect.less` 中添加自定义样式。
+在组件 Less 或业务 Less 中覆盖 `.pisell-single-select` 相关类名实现组件级定制。
 
 ---
 
-## 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;   // 选项图标
 }
 ```
 
@@ -529,80 +656,71 @@ interface SelectOption<T = string | number> {
 ### 商品分类选择
 
 ```tsx
-import {Form} from 'antd';
-import {PisellSingleSelect} from '@pisell/materials';
-import {useState} from 'react';
+import React, { useState } from 'react';
+import { Form } from 'antd';
+import { PisellSingleSelect } from '@pisell/materials';
 
 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);
-
-    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>
-    );
-}
+  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>
+  );
+};
 ```
 
 ### 城市选择（带搜索）
 
-```
+```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)}
+    />
+  );
+};
 ```
 
 ---
@@ -611,105 +729,78 @@ export default () => {
 
 ### 1. 如何处理空值？
 
-只读态会显示 `-`，编辑态会显示占位符：
+只读态空值显示为 `-`，编辑态显示占位符。
 
-```
-// 只读态显示空值
-<PisellSingleSelect
-    options={fruitOptions}
-    value={null}
-    readOnly
-/>
-// 显示: -
+```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="只读空值" />
+);
 ```
 
 ### 2. 如何实现搜索功能？
 
-设置 `showSearch={true}`：
+设置 `showSearch` 即可，组件内置防抖。
 
-```
-<PisellSingleSelect
-    options={options}
-    showSearch
-    placeholder="搜索..."
-/>
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
+
+const options = [
+  { value: 'a', label: '选项 A' },
+  { value: 'b', label: '选项 B' },
+];
+
+export default () => (
+  <PisellSingleSelect options={options} showSearch placeholder="搜索..." />
+);
 ```
 
 ### 3. 如何自定义过滤逻辑？
 
-使用 `filterOption` 属性：
+使用 `filterOption` 属性。
 
-```
-<PisellSingleSelect
-    options={options}
-    showSearch
-    filterOption={(input, option) => {
-        // 自定义过滤逻辑
-        return option.label.includes(input);
-    }}
-/>
-```
-
-### 4. 受控模式和非受控模式有什么区别？
+```tsx
+import React from 'react';
+import { PisellSingleSelect } from '@pisell/materials';
 
-**受控模式**：值由外部管理
+const options = [
+  { value: 'apple', label: '苹果' },
+  { value: 'banana', label: '香蕉' },
+];
 
-```
-const [value, setValue] = useState<string | null>(null);
-<PisellSingleSelect value={value} onChange={setValue}/>
+export default () => (
+  <PisellSingleSelect
+    options={options}
+    showSearch
+    filterOption={(input, option) => option.label.includes(input)}
+  />
+);
 ```
 
-**非受控模式**：值由组件内部管理
+### 4. 受控与非受控区别
 
-```
-<PisellSingleSelect defaultValue="apple"/>
-```
+- **受控**：外部通过 `value` + `onChange` 管理。
+- **非受控**：使用 `defaultValue`，组件内部管理。
 
 ### 5. 如何在表格中使用？
 
-只读态适合在表格中展示：
-
-```
-{
-  title: '状态',
-  dataIndex: 'status',
-  render: (value) => (
-    <PisellSingleSelect
-      options={statusOptions}
-      value={value}
-      readOnly
-    />
-  ),
-}
-```
+表格列中用 `readOnly` 展示选项文案，见上文「表格列中使用（只读态）」示例。
 
 ### 6. 如何使用 Ref 方法？
 
-```
-const ref = useRef<SingleSelectRef>(null);
-
-// 聚焦
-ref.current?.focus();
-
-// 获取值
-const value = ref.current?.getValue();
-
-// 清空
-ref.current?.clearValue();
-```
+通过 `ref` 调用 `focus()`、`getValue()`、`clearValue()` 等，见上文「使用 Ref 控制组件」示例。
 
 ### 7. 如何自定义样式？
 
-```
-// 方式1：通过 className
-<PisellSingleSelect className="custom-select"/>
-
-// 方式2：通过 style
-<PisellSingleSelect style={{width: 300}}/>
-
-// 方式3：通过 Token（全局）
-// 在 tokens.ts 中修改 Select Token
-```
+通过 `className`、`style` 传入，或通过项目 Token / Less 覆盖。
 
 ---
 
@@ -742,6 +833,12 @@ ref.current?.clearValue();
 
 ---
 
+## 相关文档
+
+- [设计文档](./pisellSingleSelect.$tab-design.md)
+- [开发文档](./pisellSingleSelect.$tab-dev.md)
+- [测试文档](./pisellSingleSelect.$tab-test.md)
+
 ## 相关组件
 
 - **PisellMultipleSelect** - 多选下拉组件