Grid Cascader 网格选择器

用于表单选取网格区域。

全局配置

在全局配置组件属性。

GridCascader组件属性配置

app.provide(GRID_CASCADER_KEY, {
  placeholder: '请选择网格',
  clearable: true,
  showAllLevels: true,
  collapseTags: true,
  collapseTagsTooltip: true,
  separator: '/',
  props: {
    id: 'gridId',
    label: 'gridName',
    value: 'gridCode',
    leaf: 'leaf',
    children: 'children',
    disabled: 'disabled',
  },
  // others props...
});

业务注入

在全局注入网格加载业务。

注入加载根网格业务

app.provide(LOAD_ROOT_GRID_KEY, () =>
  axios
    .get('/api/grid/getByCode', {
      params: {
        gridCode: '36',
      },
    })
    .then(res => res.data),
);

注入加载用户所属网格业务

app.provide(LOAD_USER_GRID_KEY, () =>
  axios
    .get('/api/grid/getByCode', {
      params: {
        gridCode: '3601',
      },
    })
    .then(res => res.data),
);

注入根据网格编码加载网格业务

app.provide(LOAD_GRID_BY_CODE_KEY, gridCode =>
  axios
    .get('/api/grid/getByCode', {
      params: {
        gridCode: gridCode,
      },
    })
    .then(res => res.data),
);

注入根据网格ID加载网格业务

app.provide(LOAD_GRID_BY_ID_KEY, gridId =>
  axios
    .get('/api/grid/getById', {
      params: {
        id: gridId,
      },
    })
    .then(res => res.data),
);

注入根据网格编码加载子级网格业务

app.provide(LOAD_GRID_CHILDREN_BY_CODE_KEY, gridCode =>
  axios
    .get('/api/grid/getChildren', {
      params: {
        gridCode: gridCode,
      },
    })
    .then(res => res.data),
);

注入查询起始网格编码到目标网格编码对应的网格树业务

app.provide(LOAD_GRID_TREE_BY_CODE_KEY, (rootCode, targetCode) =>
  axios
    .get('/api/grid/getExpandedTree', {
      params: {
        rootCode: rootCode,
        targetCode: targetCode,
      },
    })
    .then(res => [res.data.areaTree]),
);

提示

演示数据只展示到区县。

基础用法

v-model参数

v-model支持多个参数的双向绑定。

起始网格

组件默认起始网格为用户所属网格，通过root属性可以设置起始网格为根网格。

设置默认值

通过v-model和v-model:grid-id可以设置默认选中的网格。

控制网格级别

通过透传ElCascader组件的props.leaf属性可以控制网格数据展示级别。

属性&事件&插槽透传

Grid Cascader基于ElCascader封装，所以你可以传入ElCascader的所有属性、事件和插槽。

属性

属性名	说明	类型	默认值
model-value / v-model	选中项绑定值，默认绑定props.value属性对应的值	CascaderValue	—
grid-id / v-model:grid-id	选中项绑定值，默认绑定props.id属性对应的值	CascaderValue	—
grid-name / v-model:grid-name	选中项绑定值，默认绑定props.label属性对应的值	CascaderValue	—
grid / v-model:grid	选中项绑定值，绑定数据对象	T / T[] / T[][]	—
root	是否从根节点开始查询，为false表示从用户所属网格开始查询	boolean	false
root-code2.1.0	指定起始节点的网格编码	string	—
show-level2.2.0	用于控制展示到某个层级	number	99

类型声明

import type { ExtractPropTypes } from 'vue';
import type { ComponentExposed } from 'vue-component-type-helpers';
import { cascaderProps, type CascaderProps as ElCascaderPropsProps } from 'element-plus';
import GridCascader from './grid-cascader.vue';

/**
 * 网格级联选择器属性
 * @template T 网格的数据类型
 */
export interface GridCascaderProps<T = Record<string | number | symbol, any>> {
  /**
   * 是否从根网格开始查询，默认从用户所属网格开始查询。
   * @defaultValue false
   */
  root?: boolean;
  /**
   * 指定起始节点的网格编码
   */
  rootCode?: string;
  /**
   * 用于控制展示到某个层级
   * @deafultValue 99
   */
  showLevel?: number;
}

/**
 * 网格级联选择器实例
 * @template T 网格类型
 */
export type GridCascaderInstance<
  T extends Record<string | number | symbol, any> = Record<string | number | symbol, any>,
> = ComponentExposed<typeof GridCascader<T>>;

/**
 * el-cascader属性类型
 * @remarks 修改了原生`props`属性的类型。
 */
type ElCascaderProps = Omit<ExtractPropTypes<typeof cascaderProps>, 'props'> & {
  /**
   * 配置选项, 请参阅[el-cascader](https://element-plus.org/zh-CN/component/cascader.html)组件的[props属性](https://element-plus.org/zh-CN/component/cascader.html#cascaderprops)。
   */
  props: CascaderPropsProps;
};

/**
 * 网格级联选择器组件配置选项
 * @remarks 扩展`id`属性。
 */
export type CascaderPropsProps = ElCascaderPropsProps & {
  /**
   * 指定选项的id为选项对象的某个属性值。
   * @remarks el-cascader没有提供该属性，为实现网格id的双向绑定，故扩展该属性。
   */
  id?: string;
  /**
   * 指定选项的level为选项对象的某个属性值。
   * @remarks el-cascader没有提供该属性，为实现控制网格选择层级，故扩展该属性。
   */
  level?: string;
};

/**
 * 网格级联选择器包含透传属性在内的全部属性
 * @template T 网格的数据类型
 */
export type GridCascaderFullProps<T> = Partial<ElCascaderProps & GridCascaderProps<T>>;