ProPage 超级页面

ProPage 超级页面组件是在 ProSearch 超级搜索 和 ProTable 超级表格 的基础上进行拓展，因此完全兼容这些组件的所有 Props 配置、Emit 事件、Slots 插槽。

基础用法

用户姓名

性别

请选择

进度

生日

共 3 条

• 1

前往

页

<script setup lang="ts">
import type { PageColumn } from "@/components/pro/page";
import { ProPage } from "@/components/pro/page";

const data = [
  { username: "张三", gender: 1, progress: 20, birthday: "2023-01-01" },
  { username: "李四", gender: 2, progress: 40, birthday: "2023-02-01" },
  { username: "王五", gender: 1, progress: 60, birthday: "2023-03-01" },
];

const columns: PageColumn[] = [
  { prop: "username", label: "用户姓名", el: "copy", search: {} },
  {
    prop: "gender",
    label: "性别",
    el: "el-tag",
    elProps: (value: number) => {
      if (value === 1) return { type: "success" };
      return { type: "danger" };
    },
    options: async () => {
      return [
        { label: "男", value: 1 },
        { label: "女", value: 2 },
      ];
    },
    search: {
      el: "el-select",
    },
  },
  {
    prop: "progress",
    label: "进度",
    el: "el-progress",
    tooltip: "学习进度",
    elSlots: {
      default: ({ value }) => value + "%",
    },
    search: {
      el: "el-input",
    },
  },
  {
    prop: "birthday",
    label: "生日",
    search: {
      el: "el-date-picker",
    },
  },
];
</script>

<template>
  <ProPage :columns="columns" :data="data" />
</template>

隐藏源代码

搜索展示顺序

在 columns 中给每一个 column 使用 search.order，可以控制搜索展示顺序。

order 如果不设置也会在内部进行初始化赋值，默认两个相近的列 order 相差 5.

生日

进度

用户姓名

性别

请选择

共 3 条

• 1

前往

页

<script setup lang="ts">
import type { PageColumn } from "@/components/pro/page";
import { ProPage } from "@/components/pro/page";

const data = [
  { username: "张三", gender: 1, progress: 20, birthday: "2023-01-01" },
  { username: "李四", gender: 2, progress: 40, birthday: "2023-02-01" },
  { username: "王五", gender: 1, progress: 60, birthday: "2023-03-01" },
];

const columns: PageColumn[] = [
  { prop: "username", label: "用户姓名", el: "copy", search: {} },
  {
    prop: "gender",
    label: "性别",
    el: "el-tag",
    elProps: (value: number) => {
      if (value === 1) return { type: "success" };
      return { type: "danger" };
    },
    options: async () => {
      return [
        { label: "男", value: 1 },
        { label: "女", value: 2 },
      ];
    },
    search: {
      el: "el-select",
    },
  },
  {
    prop: "progress",
    label: "进度",
    el: "el-progress",
    tooltip: "学习进度",
    elSlots: {
      default: ({ value }) => value + "%",
    },
    search: {
      el: "el-input",
      order: 3,
    },
  },
  {
    prop: "birthday",
    label: "生日",
    search: {
      el: "el-date-picker",
      order: 1,
    },
  },
];
</script>

<template>
  <ProPage :columns="columns" :data="data" />
</template>

隐藏源代码

手动控制搜索值

通过 ProPage 组件的示例来获取相关方法控制搜索值。

ProPage 组件同时也暴露了 ProTable 和 ProSearch 的示例，你可以像正常使用 ProTable 和 ProSearch 组件一样来获取对应的方法使用。

用户姓名

性别

请选择

进度

生日

共 3 条

• 1

前往

页

<script setup lang="ts">
import type { PageColumn, ProPageInstance } from "@/components/pro/page";
import { ProPage } from "@/components/pro/page";
import { ElMessage } from "element-plus";
import { useTemplateRef } from "vue";

const proPageInstance = useTemplateRef<ProPageInstance>("proPageInstance");

const data = [
  { username: "张三", gender: 1, progress: 20, birthday: "2023-01-01" },
  { username: "李四", gender: 2, progress: 40, birthday: "2023-02-01" },
  { username: "王五", gender: 1, progress: 60, birthday: "2023-03-01" },
];

const columns: PageColumn[] = [
  { prop: "username", label: "用户姓名", el: "copy", search: {} },
  {
    prop: "gender",
    label: "性别",
    el: "el-tag",
    elProps: (value: number) => {
      if (value === 1) return { type: "success" };
      return { type: "danger" };
    },
    options: async () => {
      return [
        { label: "男", value: 1 },
        { label: "女", value: 2 },
      ];
    },
    search: {
      el: "el-select",
    },
  },
  {
    prop: "progress",
    label: "进度",
    el: "el-progress",
    tooltip: "学习进度",
    elSlots: {
      default: ({ value }) => value + "%",
    },
    search: {
      el: "el-input",
    },
  },
  {
    prop: "birthday",
    label: "生日",
    search: {
      el: "el-date-picker",
    },
  },
];

/**
 * 设置搜索值
 */
const setSearchParams = () => {
  proPageInstance.value?.setSearchParams({ username: "小明", gender: 1 });
};

/**
 * 获取搜索值
 */
const getSearchParams = () => {
  ElMessage.info(JSON.stringify(proPageInstance.value?.searchParams));
};
/**
 * 清空搜索值
 */
const clearSearchParams = () => {
  proPageInstance.value?.clearSearchParams();
};
</script>

<template>
  <div style="margin-bottom: 10px">
    <el-button @click="setSearchParams">设置搜索值</el-button>
    <el-button @click="getSearchParams">获取搜索值</el-button>
    <el-button @click="clearSearchParams">清空搜索值</el-button>
  </div>

  <ProPage ref="proPageInstance" :columns="columns" :data="data" />
</template>

隐藏源代码

搜索列占位

通过 span 配置项，可以控制搜索项所占用的列数，默认为 1。

通过 offset 配置项，可以控制搜索列的离左侧偏移列数，默认为 0。

用户姓名

性别

请选择

进度

生日

共 3 条

• 1

前往

页

<script setup lang="ts">
import type { PageColumn } from "@/components/pro/page";
import { ProPage } from "@/components/pro/page";

const data = [
  { username: "张三", gender: 1, progress: 20, birthday: "2023-01-01" },
  { username: "李四", gender: 2, progress: 40, birthday: "2023-02-01" },
  { username: "王五", gender: 1, progress: 60, birthday: "2023-03-01" },
];

const columns: PageColumn[] = [
  { prop: "username", label: "用户姓名", el: "copy", search: {} },
  {
    prop: "gender",
    label: "性别",
    el: "el-tag",
    elProps: (value: number) => {
      if (value === 1) return { type: "success" };
      return { type: "danger" };
    },
    options: async () => {
      return [
        { label: "男", value: 1 },
        { label: "女", value: 2 },
      ];
    },
    search: {
      el: "el-select",
    },
  },
  {
    prop: "progress",
    label: "进度",
    el: "el-progress",
    tooltip: "学习进度",
    elSlots: {
      default: ({ value }) => value + "%",
    },
    search: {
      el: "el-input",
    },
  },
  {
    prop: "birthday",
    label: "生日",
    search: {
      el: "el-date-picker",
      span: 2,
      offset: 1,
    },
  },
];
</script>

<template>
  <ProPage :columns="columns" :data="data" />
</template>

隐藏源代码

搜索默认值

在 columns 中给每一个 column 使用 search.defaultValue，可以设置搜索项的默认值。

同时支持全局传入 defaultValues，但是优先级低于单个 column 的 search.defaultValue。

用户姓名

共 3 条

• 1

前往

页

<script setup lang="ts">
import type { PageColumn } from "@/components/pro/page";
import { ProPage } from "@/components/pro/page";

const defaultValues = {
  username: "张三",
  gender: 2,
};

const data = [
  { username: "张三", gender: 1, progress: 20, birthday: "2023-01-01" },
  { username: "李四", gender: 2, progress: 40, birthday: "2023-02-01" },
  { username: "王五", gender: 1, progress: 60, birthday: "2023-03-01" },
];

const columns: PageColumn[] = [
  {
    prop: "username",
    label: "用户姓名",
    el: "copy",
    search: {},
  },
  {
    prop: "gender",
    label: "性别",
    el: "el-tag",
    elProps: (value: number) => {
      if (value === 1) return { type: "success" };
      return { type: "danger" };
    },
    options: async () => {
      return [
        { label: "男", value: 1 },
        { label: "女", value: 2 },
      ];
    },
    search: {
      el: "el-select",
      defaultValue: (model, optionsMap) => {
        console.log(optionsMap);
        if (model.username === "张三") return 2;
        else return 1;
      },
    },
  },
  {
    prop: "progress",
    label: "进度",
    el: "el-progress",
    tooltip: "学习进度",
    elSlots: {
      default: ({ value }) => value + "%",
    },
    search: {
      el: "el-input",
      defaultValue: async () => 40,
    },
  },
  {
    prop: "birthday",
    label: "生日",
    search: {
      el: "el-date-picker",
      defaultValue: () => "2023-01-01",
    },
  },
];
</script>

<template>
  <ProPage :columns="columns" :data="data" :default-values />
</template>

隐藏源代码

搜索前置事件

在 columns 中给每一个 column 使用 search.beforeSearch，可以设置搜索前置事件，返回 当前 prop 的新的搜索参数。

同时支持全局传入 beforeSearch，但是优先级低于单个 column 的 search.beforeSearch。

相比较单个 column 的 search.beforeSearch，beforeSearch 需要返回 boolean 或者一个新的搜索表单，如果返回 false 则取消搜索。

用户姓名

性别

请选择

进度

创建事件

至

共 3 条

• 1

前往

页

<script setup lang="ts">
import type { PageColumn } from "@/components/pro/page";
import { ProPage } from "@/components/pro/page";
import { ElMessage } from "element-plus";

const data = [
  { username: "张三", gender: 1, progress: 20, createTime: "2023-01-01" },
  { username: "李四", gender: 2, progress: 40, createTime: "2023-02-01" },
  { username: "王五", gender: 1, progress: 60, createTime: "2023-03-01" },
];

const columns: PageColumn[] = [
  {
    prop: "username",
    label: "用户姓名",
    el: "copy",
    search: {
      beforeSearch: value => {
        if (value) return "%" + value + "%";
      },
    },
  },
  {
    prop: "gender",
    label: "性别",
    el: "el-tag",
    elProps: (value: number) => {
      if (value === 1) return { type: "success" };
      return { type: "danger" };
    },
    options: async () => {
      return [
        { label: "男", value: 1 },
        { label: "女", value: 2 },
      ];
    },
    search: {
      el: "el-select",
    },
  },
  {
    prop: "progress",
    label: "进度",
    el: "el-progress",
    tooltip: "学习进度",
    elSlots: {
      default: ({ value }) => value + "%",
    },
    search: {
      el: "el-input",
    },
  },
  {
    prop: "createTime",
    label: "创建事件",
    search: {
      el: "el-date-picker",
      span: 2,
      elProps: {
        type: "daterange",
      },
      beforeSearch: (value, searchParams) => {
        if (value) {
          searchParams.startTime = value[0];
          searchParams.endTime = value[1];
          delete searchParams.createTime;
        }
      },
    },
  },
];

const beforeSearch = (searchParams: Record<string, any>) => {
  // 饭 false 代表取消发送请求
  return false;
};

const handleSearch = (model: Record<string, any>) => {
  ElMessage.info("搜索条件：" + JSON.stringify(model));
};
</script>

<template>
  <ProPage :columns="columns" :data="data" :before-search="beforeSearch" @search="handleSearch" />
</template>

隐藏源代码

插槽

ProPage 默认与 ProTable 的插槽命名一致，而 ProSearch 插槽需要添加 -search 结尾来进行识别。

• 通过 {prop}-search 插槽，可以自定义搜索表单的组件
• 通过 {prop}-label-search 插槽，可以自定义表单 Label
• 通过 {prop} 插槽，可以自定义表格单元格内容
• 通过 {prop}-header 插槽，可以自定义表格表头内容

插槽渲染用户姓名

插槽渲染：张三

性别

请选择

进度

生日

我是通过插槽渲染的：

共 3 条

• 1

前往

页

<script setup lang="ts">
import type { PageColumn } from "@/components/pro/page";
import { ArrowDown, ArrowUp, Refresh, Search } from "@element-plus/icons-vue";
import { ProPage } from "@/components/pro/page";

const data = [
  { username: "张三", gender: 1, progress: 20, birthday: "2023-01-01" },
  { username: "李四", gender: 2, progress: 40, birthday: "2023-02-01" },
  { username: "王五", gender: 1, progress: 60, birthday: "2023-03-01" },
];

const columns: PageColumn[] = [
  {
    prop: "username",
    label: "用户姓名",
    el: "copy",
    search: {
      defaultValue: "张三",
    },
  },
  {
    prop: "gender",
    label: "性别",
    el: "el-tag",
    elProps: (value: number) => {
      if (value === 1) return { type: "success" };
      return { type: "danger" };
    },
    options: async () => {
      return [
        { label: "男", value: 1 },
        { label: "女", value: 2 },
      ];
    },
    search: {
      el: "el-select",
    },
  },
  {
    prop: "progress",
    label: "进度",
    el: "el-progress",
    tooltip: "学习进度",
    elSlots: {
      default: ({ value }) => value + "%",
    },
    search: {
      el: "el-input",
    },
  },
  {
    prop: "birthday",
    label: "生日",
    search: {
      el: "el-date-picker",
    },
  },
];
</script>

<template>
  <ProPage :columns="columns" :data="data">
    <template #username="{ value }">我是通过插槽渲染的：{{ value }}</template>
    <template #username-header>插槽渲染</template>

    <template #username-search="{ value }">插槽渲染：{{ value }}</template>
    <template #username-label-search="{ label }">插槽渲染{{ label }}</template>

    <template #action="{ search, reset, collapse, showCollapseButton, toggleCollapse }">
      <el-button type="primary" :icon="Search" @click="search">搜索</el-button>
      <el-button :icon="Refresh" @click="reset">重置</el-button>

      <el-button v-if="showCollapseButton" :icon="collapse ? ArrowUp : ArrowDown" @click="toggleCollapse()">
        {{ collapse ? "收起" : "展开" }}
      </el-button>
    </template>
  </ProPage>
</template>

隐藏源代码

API 获取数据

超级页面支持手动传入 data 数据，同时也支持传入 request-api 函数来获取数据。

用户姓名

性别

请选择

进度

生日

暂无数据

共 0 条

• 1

前往

页

<script setup lang="ts">
import type { PageColumn } from "@/components/pro/page";
import { ProPage } from "@/components/pro/page";

// 模拟后端 API
const DataService = {
  getList: async (searchParams: Record<string, any>) => {
    console.log("搜索条件: ", searchParams);

    const data = [
      { username: "张三", gender: 1, progress: 20, birthday: "2023-01-01" },
      { username: "李四", gender: 2, progress: 40, birthday: "2023-02-01" },
      { username: "王五", gender: 1, progress: 60, birthday: "2023-03-01" },
    ];

    return Promise.resolve({
      code: 200,
      message: "success",
      data,
    });
  },
};

const columns: PageColumn[] = [
  { prop: "username", label: "用户姓名", el: "copy", search: {} },
  {
    prop: "gender",
    label: "性别",
    el: "el-tag",
    elProps: (value: number) => {
      if (value === 1) return { type: "success" };
      return { type: "danger" };
    },
    options: async () => {
      return [
        { label: "男", value: 1 },
        { label: "女", value: 2 },
      ];
    },
    search: {
      el: "el-select",
    },
  },
  {
    prop: "progress",
    label: "进度",
    el: "el-progress",
    tooltip: "学习进度",
    elSlots: {
      default: ({ value }) => value + "%",
    },
    search: {
      el: "el-input",
    },
  },
  {
    prop: "birthday",
    label: "生日",
    search: {
      el: "el-date-picker",
    },
  },
];

// 请求数据后的回调
const handleTransformData = (data: Record<string, any>[]) => {
  return [...data, { username: "赵六", gender: 2, progress: 80, birthday: "2023-04-01" }];
};

// 请求错误的回调
const handleRequestError = (error: unknown) => {
  console.log(error);
};
</script>

<template>
  <ProPage
    :columns="columns"
    :request-api="DataService.getList"
    :default-request-params="{ username: '张三' }"
    :request-error="handleRequestError"
    :transform-data="handleTransformData"
  />
</template>

隐藏源代码

PageColumn 配置项

属性名	说明	类型	默认值
search	搜索相关配置	object	—
...	其他扩展属性，支持所有 FormColumn 配置项	...	...

search 配置项在 SearchColumn 配置项 基础上拓展了如下类型：

export interface PageColumn<T extends Recordable = any> extends TableColumn<T> {
  search?: {
    /**
     * 搜索事件前置处理，可以返回新的搜索值
     */
    beforeSearch?: (value: any, searchParams: Recordable, column: TableColumn) => unknown | false | undefined;
    /**
     * 搜索项所占用的列数，默认为 1 列
     */
    span?: number;
    /**
     * 搜索字段左侧偏移列数
     */
    offset?: number;
  } & Partial<SearchColumn> &
    Partial<Record<BreakPoint, Responsive>>;
}

BreakPoint 类型如下：

export type BreakPoint = "xs" | "sm" | "md" | "lg" | "xl";

Responsive 类型如下：

export type Responsive = {
  /**
   * 偏移量
   *
   * @default 1
   */
  span?: number;
  /**
   * 占位量
   *
   * @default 0
   */
  offset?: number;
};

Attributes

属性名	说明	类型	默认值
columns	页面列配置	array	[]
searchProps	搜索项配置	object	—
initShowSearch	初始化时是否显示搜索模块	boolean / function	true
defaultValues	默认搜索参数，优先级低于 column.defaultValue	object	—
...	其他扩展属性，支持所有 ProTable Attributes	...	...

Events

名称	说明	类型
searchRegister	ProSearch 的注册事件	function
tableRegister	ProTable 的注册事件	function
...	其他扩展属性，支持所有 ProTable Events 和 ProSearch Events	...

Slots

插槽名	说明	作用域插槽参数
action	自定义搜索操作按钮区域	object
'prop'-search	自定义搜索表单项组件，自动根据配置项的 prop 生成对应的插槽	object
'prop'-label-search	自定义表单项 label，自动根据配置项的 prop 生成对应的插槽	object
'prop'	自定义表格单元格，自动根据配置项的 prop 生成对应的插槽	object
'prop-header'	自定义表格项 header，自动根据配置项的 prop 生成对应的插槽	object
...	其他扩展属性，支持所有 ProTable Slots	...

Exposes

名称	说明	类型
searchParams	搜索参数	object
searchDefaultParams	搜索默认参数	object
proSearchInstance	ProSearch 组件实例	object
proTableInstance	ProTable 组件实例	object
search	触发搜索事件	function
reset	重置搜索表单	function
toggleCollapse	切换搜索表单展开收起状态	function
getTableData	获取表格数据	function
getPageInfo	获取分页信息	function
setSearchParams	设置搜索参数	function
clearSearchParams	清空搜索参数	function
...	其他扩展属性，支持所有 ProTable Exposes	...