---
nav:
  title: 组件
  order: 1
group:
  title: DataDisplay
  order: 3
title: PisellSort
order: 15
category: pro
---

# PisellSort - 排序选择组件

## 简介

PisellSort 是一个排序选择组件，基于 Ant Design Form 封装，提供了便捷的排序字段选择和排序方式配置功能。适用于列表、表格等需要排序功能的场景。

## 特性

- 🎯 **表单集成**: 基于 Ant Design Form 封装，支持表单联动
- 🎨 **灵活配置**: 支持自定义排序字段和排序方式
- 📱 **类型支持**: 支持日期、字符串、数字等多种数据类型排序
- 🔄 **受控模式**: 支持完全受控的选中状态管理
- ⚡ **轻量级**: 基于已有 Sort 组件封装，体积小巧
- 🎭 **TypeScript**: 完整的 TypeScript 类型定义

## 基础用法

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

const Demo = () => {
  const [sortValue, setSortValue] = useState('price_asc');

  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',
    },
  ];

  return (
    <PisellSort
      list={sortList}
      value={sortValue}
      onChange={(val) => {
        console.log('排序改变:', val);
        setSortValue(val);
      }}
    />
  );
};

export default Demo;
```

## API

### PisellSort Props

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

### SortItemProps

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

## 进阶用法

### 自定义触发按钮

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

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

const Demo = () => {
  return (
    <PisellSort
      list={sortList}
      button={
        <Button type="primary" icon={<SortAscendingOutlined />}>
          排序
        </Button>
      }
    />
  );
};

export default Demo;
```

### 自定义下拉位置

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

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

const Demo = () => {
  return (
    <PisellSort
      list={sortList}
      placement="topLeft"
    />
  );
};

export default Demo;
```

### 隐藏特定排序项

```tsx
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, // 隐藏此项
  },
];

const Demo = () => {
  return <PisellSort list={sortList} />;
};

export default Demo;
```

### 本地排序模式

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

const sortList = [
  {
    type: 'number',
    label: '价格',
    name: 'price',
    isCustom: false,
    columnKey: 'price',
    localFilter: true, // 启用本地过滤
  },
];

const Demo = () => {
  return (
    <PisellSort
      list={sortList}
      localPagination={true}
    />
  );
};

export default Demo;
```

## 注意事项

1. **表单集成**: PisellSort 组件内部已集成 Form，使用时无需再包裹 Form 组件
2. **字段名称**: 默认表单字段名为 `sort_key`，可通过 `name` 属性自定义
3. **数据类型**: 不同的 `type` 类型会影响排序的行为，请根据实际数据类型选择
4. **回调参数**: `onChange` 回调会返回排序值和详细的菜单信息，方便进行更复杂的处理

## 设计指南

详见 [设计文档](./PisellSort.$tab-design.md)

## 开发指南

详见 [开发文档](./PisellSort.$tab-dev.md)

## 测试指南

详见 [测试文档](./PisellSort.$tab-test.md)
