---
nav:
  title: 组件
  order: 1
group:
  title: Data Entry
  order: 1
title: PisellSort
order: 15
category: pro
---

# PisellSort - 排序选择组件

PisellSort 基于 Ant Design Form 封装，提供排序字段与排序方式的下拉选择，适用于列表、表格等需要排序能力的场景。

## 何时使用

- 列表/表格需要「按某字段升序/降序」的筛选入口
- 需要与 Form 联动的排序字段（字段名可配置）
- 需要支持多类型字段（数字、日期、字符串）的排序配置

## 特性

- 表单集成：基于 Ant Design Form，支持表单联动
- 灵活配置：自定义排序字段列表与排序方式
- 类型支持：支持 `date`、`string`、`number` 等类型
- 受控模式：支持 `value` + `onChange` 受控
- TypeScript：完整类型定义

## 基础用法

```tsx
import React, { useState } from 'react';
import { PisellSort } from '@pisell/materials';

const sortList = [
  { type: 'number', label: '价格', name: 'price', isCustom: false, columnKey: 'price' },
  { type: 'date', label: '创建时间', name: 'created_at', isCustom: false, columnKey: 'created_at' },
  { type: 'string', label: '名称', name: 'name', isCustom: false, columnKey: 'name' },
];

export default () => {
  const [sortValue, setSortValue] = useState<string>('price_asc');
  return (
    <PisellSort
      list={sortList}
      value={sortValue}
      onChange={(val) => {
        console.log('排序改变:', val);
        setSortValue(val);
      }}
    />
  );
};
```

## API

### PisellSort Props

| 参数            | 说明               | 类型                                                               | 默认值       | 必填 |
| --------------- | ------------------ | ------------------------------------------------------------------ | ------------ | ---- |
| list            | 排序字段列表       | `SortItemProps[]`                                                  | `[]`         | ❌   |
| value           | 当前选中的排序值   | `string`                                                           | -            | ❌   |
| onChange        | 排序变化回调       | `(val: string, detail: MenuInfo) => void`                          | -            | ❌   |
| name            | 表单字段名         | `string`                                                           | `'sort_key'` | ❌   |
| button          | 自定义触发按钮     | `ReactNode`                                                        | -            | ❌   |
| style           | 自定义样式         | `CSSProperties`                                                    | -            | ❌   |
| placement       | 下拉菜单弹出位置   | `'bottom' \| 'bottomLeft' \| 'bottomRight' \| 'top' \| 'topLeft' \| 'topRight'` | -            | ❌   |
| localPagination | 是否使用本地分页   | `boolean`                                                          | -            | ❌   |

### SortItemProps

```ts
interface SortItemProps {
  type: 'date' | 'string' | 'number'; // 排序字段类型
  label?: string;                    // 显示标签
  name?: string | string[];          // 字段名称
  isCustom: boolean;                  // 是否为自定义排序
  columnKey?: string;                 // 列键值
  localFilter?: boolean;              // 是否本地过滤
  isHidden?: boolean;                 // 是否隐藏
}
```

## 进阶用法

### 自定义触发按钮

```tsx
import React from 'react';
import { Button } from 'antd';
import { PisellSort } from '@pisell/materials';

const sortList = [
  { type: 'number', label: '价格', name: 'price', isCustom: false, columnKey: 'price' },
];

export default () => (
  <PisellSort
    list={sortList}
    button={<Button type="primary">排序</Button>}
  />
);
```

### 自定义下拉位置

```tsx
import React from 'react';
import { PisellSort } from '@pisell/materials';

const sortList = [
  { type: 'number', label: '价格', name: 'price', isCustom: false, columnKey: 'price' },
];

export default () => (
  <PisellSort list={sortList} placement="topLeft" />
);
```

### 隐藏特定排序项

```tsx
import React from 'react';
import { PisellSort } from '@pisell/materials';

const sortList = [
  { type: 'number', label: '价格', name: 'price', isCustom: false, columnKey: 'price' },
  {
    type: 'date',
    label: '创建时间',
    name: 'created_at',
    isCustom: false,
    columnKey: 'created_at',
    isHidden: true,
  },
];

export default () => <PisellSort list={sortList} />;
```

### 本地排序模式

```tsx
import React from 'react';
import { PisellSort } from '@pisell/materials';

const sortList = [
  {
    type: 'number',
    label: '价格',
    name: 'price',
    isCustom: false,
    columnKey: 'price',
    localFilter: true,
  },
];

export default () => (
  <PisellSort list={sortList} localPagination />
);
```

## 注意事项

1. **表单集成**：组件内部已集成 Form，无需再包一层 Form
2. **字段名称**：默认表单字段名为 `sort_key`，可通过 `name` 自定义
3. **数据类型**：`list` 中每项的 `type`（`date` / `string` / `number`）会影响排序行为，需与实际数据一致
4. **回调参数**：`onChange(val, detail)` 返回当前排序值与菜单详情，便于联动请求或表格排序

## 相关文档

- [设计文档](./PisellSort.$tab-design.md)
- [开发文档](./PisellSort.$tab-dev.md)
- [测试文档](./PisellSort.$tab-test.md)
