---
nav:
  title: Plus组件
  order: 3
group:
  title: 业务组件
  order: 3
title: OrderList 订单列表
order: 1
category: plus
---

# OrderList 订单列表

订单列表组件，用于展示和管理电商系统中的订单数据。支持多维度筛选、排序、分页等功能，提供完整的订单管理能力。

## 何时使用

- 需要展示和管理订单列表时
- 需要对订单进行多维度筛选时
- 需要查看订单的详细信息时
- 需要对订单进行批量操作时

## 功能特性

- 📋 **丰富的列展示**：支持订单号、客户信息、联系人信息、标签、配送方式、支付信息等多个维度的数据展示
- 🔍 **强大的筛选功能**：支持关键字搜索、时间范围、订单状态、支付状态、处理状态等多维度筛选
- 📊 **灵活的排序**：支持按订单号、创建时间、更新时间、客户名称、订单金额等多个字段排序
- 🎯 **快捷筛选**：提供今日订单、今日待支付、今日退款订单、近7天订单等快捷筛选按钮
- 🌍 **多语言支持**：支持中文简体、中文繁体、英文三种语言
- 📑 **分页展示**：支持大量数据的分页加载
- 🎨 **状态可视化**：通过不同颜色标签直观展示订单状态、支付状态、处理状态

## 代码演示

### 基础用法

```tsx
import React from 'react';
import { OrderList } from '@pisell/private-materials';

export default () => {
  return <OrderList business_type="retail" />;
};
```

## API

### OrderList Props

| 参数 | 说明 | 类型 | 默认值 | 必填 |
| --- | --- | --- | --- | --- |
| business_type | 业务类型，用于区分不同业务场景的订单 | `string` | - | 是 |

## 数据字段说明

### 表格列字段

| 列名 | 字段 | 说明 |
| --- | --- | --- |
| 订单号 | shop_order_number | 订单编号，支持备注显示 |
| 客户信息 | customer | 包含客户姓名、电话、邮箱 |
| 联系人信息 | contacts_info | 包含联系人姓名、电话、邮箱 |
| 标签 | tag | 订单标签，支持多个标签 |
| 配送方式 | delivery_type | 包括物流配送、本地配送、到店自提、到店服务等 |
| 支付信息 | payment_status | 支付状态，带有详细的金额信息提示 |
| 下单渠道 | platform | 包括 Online Store、Terminal、Kiosk、Merchant Portal 等 |
| 商品数量 | product_quantity | 订单中的商品数量（默认隐藏） |
| 业务 | business_code | 业务代码（默认隐藏） |
| 订单状态 | status | 未完成、已完成、已取消（默认隐藏） |
| 处理状态 | shipping_status | 未处理、处理中、部分处理、已处理（默认隐藏） |
| 创建信息 | create_account | 创建人和创建时间（默认隐藏） |
| 更多信息 | last_edit_account | 最后编辑人和编辑时间（默认隐藏） |

### 筛选字段

#### 快速筛选

- **关键字搜索**：支持订单号等关键字搜索
- **下单时间**：支持时间范围筛选

#### 详细筛选

- **订单状态**：未完成、已完成、已取消
- **支付状态**：已授权、已付款、部分付款、部分退款、等待付款、已退款、未付款、已作废、待支付
- **处理状态**：未处理、处理中、部分处理、已处理
- **客户**：支持搜索选择客户
- **销售渠道**：支持多选销售渠道
- **支付方式**：支持多选支付方式
- **订单金额区间**：支持金额范围筛选
- **标签**：支持搜索选择订单标签
- **配送方式**：物流配送、本地配送、到店自提
- **配送区域**：文本输入配送区域名称
- **自提点**：选择自提点
- **物流单号**：文本输入物流单号
- **快递公司**：支持多选快递公司
- **邮编**：文本输入邮编

### 排序字段

支持以下字段的升序/降序排序：

- 订单号
- 创建时间
- 更新时间
- 客户名称
- 付款状态
- 发货状态
- 订单金额
- 预约时间

### 状态映射

#### 配送方式

- `nil`: 无需配送
- `shipping`: 物流配送
- `local_delivery`: 本地配送
- `pickup`: 到店自提
- `shop_service`: 到店服务
  - `dine-in`: 堂食
  - `takeaway`: 外带

#### 订单状态

- `open`: 未完成（蓝色边框）
- `completed`: 已完成（绿色边框）
- `cancelled`: 已取消（红色边框）

#### 处理状态

- `unfulfilled`: 未处理（橙色边框）
- `fulfilling`: 处理中（橙色边框）
- `partial_fulfilled`: 部分处理（青色边框）
- `falseulfilled`: 已处理（灰色边框）

#### 支付状态

- `unpaid`: 未付款（蓝色背景）
- `payment_processing`: 待支付（黄色背景）
- `payment_pending`: 等待付款（黄色背景）
- `authorized`: 已授权（绿色背景）
- `paid`: 已付款（绿色背景）
- `partially_paid`: 部分付款（浅绿背景）
- `refunded`: 已退款（红色背景）
- `partially_refunded`: 部分退款（粉色背景）
- `voided`: 已作废（灰色背景）

## 组件组成

OrderList 组件由以下子组件构成：

- **PisellDataSourceContainer**: 数据源容器，管理数据的获取、分页、筛选等
- **PisellGridPro**: 网格布局容器，提供标题、工具栏、内容区、底部区域
- **PisellToolBar**: 工具栏，容纳筛选和操作按钮
- **QuickFilter**: 快速筛选组件（关键字、时间）
- **FilterList**: 快捷筛选按钮组（今日订单、今日待支付等）
- **HandleActions**: 操作按钮组（列设置、排序、筛选）
- **Reset**: 重置按钮
- **Table**: 表格组件，展示订单列表数据
- **Pagination**: 分页组件

## 注意事项

1. **业务类型必传**：`business_type` 参数是必填的，用于区分不同业务场景
2. **依赖上下文**：组件依赖 `useEngineContext` 获取应用上下文，需要在正确的上下文环境中使用
3. **多语言配置**：组件会根据引擎的 locale 配置自动切换语言，支持 `zh-CN`、`zh-HK`、`en`
4. **请求配置**：组件使用 `appHelper.utils.request` 进行接口请求，需要确保请求工具正确配置
5. **列显示配置**：部分列默认隐藏，可通过列设置功能自定义显示
6. **支付信息提示**：支付信息列鼠标悬停会显示详细的金额信息（总金额、已付金额、待付金额、已退金额等）

## 技术依赖

- `@pisell/materials`: 基础物料库
- `@pisell/utils`: 工具库（多语言支持）
- `antd`: UI 组件库
- `dayjs`: 时间处理库
- `react`: React 框架

## 相关组件

- [PisellDataSourceContainer](/components/pisell-data-source-container) - 数据源容器
- [PisellGridPro](/components/pisell-grid-pro) - 网格布局
- [PisellToolBar](/components/pisell-tool-bar) - 工具栏
- [PisellQuickFilter](/components/pisell-quick-filter) - 快速筛选
- [PisellSort](/components/pisell-sort) - 排序组件
- [PisellFilter](/components/pisell-filter) - 筛选组件