From fb80749156eee0d0c31f8ff81f1e62f238279ed8 Mon Sep 17 00:00:00 2001
From: YunaiV <zhijiantianya@gmail.com>
Date: Mon, 8 Jun 2026 22:17:52 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=20Vben=20=E8=A1=A8?=
 =?UTF-8?q?=E5=8D=95=E5=9C=B0=E5=8C=BA=E9=80=89=E6=8B=A9=E5=99=A8=E5=8F=AA?=
 =?UTF-8?q?=E5=B1=95=E7=A4=BA=E6=9C=AB=E7=BA=A7=E5=9C=B0=E5=8C=BA=E7=9A=84?=
 =?UTF-8?q?=E9=97=AE=E9=A2=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 antd、antdv-next、ele 三端 AreaCascader 组件
- 将表单值保持为末级 areaId，展示时回显完整省市区级联路径
- 替换会员、CRM、商城交易相关表单的地区选择字段
- 按组件库默认行为保留清空和搜索默认关闭，并在使用处显式开启
---
 .../src/components/area/area-cascader.vue     | 125 ++++++++++++++++++
 apps/web-antd/src/components/area/index.ts    |   1 +
 apps/web-antd/src/views/crm/clue/data.ts      |  11 +-
 apps/web-antd/src/views/crm/contact/data.ts   |  11 +-
 apps/web-antd/src/views/crm/customer/data.ts  |  12 +-
 .../mall/trade/delivery/pickUpStore/data.ts   |  11 +-
 .../src/views/mall/trade/order/data.ts        |  15 ++-
 apps/web-antd/src/views/member/user/data.ts   |  12 +-
 .../src/components/area/area-cascader.vue     | 125 ++++++++++++++++++
 .../src/components/area/index.ts              |   1 +
 .../web-antdv-next/src/views/crm/clue/data.ts |  11 +-
 .../src/views/crm/contact/data.ts             |  11 +-
 .../src/views/crm/customer/data.ts            |  12 +-
 .../mall/trade/delivery/pickUpStore/data.ts   |  11 +-
 .../src/views/mall/trade/order/data.ts        |  15 ++-
 .../src/views/member/user/data.ts             |  12 +-
 .../src/components/area/area-cascader.vue     | 124 +++++++++++++++++
 apps/web-ele/src/components/area/index.ts     |   1 +
 apps/web-ele/src/views/crm/clue/data.ts       |  13 +-
 apps/web-ele/src/views/crm/contact/data.ts    |  13 +-
 apps/web-ele/src/views/crm/customer/data.ts   |  14 +-
 .../mall/trade/delivery/pickUpStore/data.ts   |  13 +-
 .../src/views/mall/trade/order/data.ts        |  15 ++-
 apps/web-ele/src/views/member/user/data.ts    |  14 +-
 24 files changed, 506 insertions(+), 97 deletions(-)
 create mode 100644 apps/web-antd/src/components/area/area-cascader.vue
 create mode 100644 apps/web-antd/src/components/area/index.ts
 create mode 100644 apps/web-antdv-next/src/components/area/area-cascader.vue
 create mode 100644 apps/web-antdv-next/src/components/area/index.ts
 create mode 100644 apps/web-ele/src/components/area/area-cascader.vue
 create mode 100644 apps/web-ele/src/components/area/index.ts

diff --git a/apps/web-antd/src/components/area/area-cascader.vue b/apps/web-antd/src/components/area/area-cascader.vue
new file mode 100644
index 000000000..d015cc922
--- /dev/null
+++ b/apps/web-antd/src/components/area/area-cascader.vue
@@ -0,0 +1,125 @@
+<script lang="ts" setup>
+import type { CascaderProps } from 'ant-design-vue';
+
+import type { SystemAreaApi } from '#/api/system/area';
+
+import { onMounted, ref, watch } from 'vue';
+
+import { Cascader } from 'ant-design-vue';
+
+import { getAreaTree } from '#/api/system/area';
+
+defineOptions({ name: 'AreaCascader' });
+
+const props = withDefaults(defineProps<Props>(), {
+  allowClear: false,
+  changeOnSelect: false,
+  modelValue: undefined,
+  placeholder: '请选择省市区',
+  showSearch: false,
+});
+
+const emit = defineEmits<{
+  'update:modelValue': [value?: number];
+}>();
+
+interface Props {
+  allowClear?: boolean;
+  changeOnSelect?: boolean;
+  modelValue?: number;
+  placeholder?: string;
+  showSearch?: boolean;
+}
+
+type AreaTreeNode = SystemAreaApi.Area & {
+  children?: AreaTreeNode[];
+};
+
+const areaTree = ref<AreaTreeNode[]>([]); // 地区树
+const loading = ref(false); // 加载状态
+const selectedPath = ref<number[]>(); // 选中的地区路径
+
+const fieldNames = {
+  children: 'children', // 子级字段
+  label: 'name', // 标签字段
+  value: 'id', // 值字段
+};
+
+/**
+ * 查找地区编号对应的级联路径
+ *
+ * @param tree 地区树
+ * @param areaId 地区编号
+ * @returns 省市区编号路径
+ */
+function findAreaPath(
+  tree: AreaTreeNode[],
+  areaId?: number,
+): number[] | undefined {
+  if (areaId === undefined || areaId === null) {
+    return undefined;
+  }
+
+  for (const area of tree) {
+    if (area.id === undefined) {
+      continue;
+    }
+    if (area.id === areaId) {
+      return [area.id];
+    }
+
+    const childPath = area.children?.length
+      ? findAreaPath(area.children, areaId)
+      : undefined;
+    if (childPath) {
+      return [area.id, ...childPath];
+    }
+  }
+}
+
+/** 同步级联选择器展示路径 */
+function syncSelectedPath() {
+  selectedPath.value = findAreaPath(areaTree.value, props.modelValue);
+}
+
+/** 选择地区后回写最后一级地区编号 */
+const handleChange: NonNullable<CascaderProps['onChange']> = (value) => {
+  if (!value?.length) {
+    emit('update:modelValue', undefined);
+    return;
+  }
+
+  const path = Array.isArray(value[0]) ? value[0] : value;
+  const leafValue = path.at(-1);
+  const areaId =
+    typeof leafValue === 'number' ? leafValue : Number(leafValue);
+  emit('update:modelValue', Number.isNaN(areaId) ? undefined : areaId);
+};
+
+watch(() => props.modelValue, syncSelectedPath);
+
+/** 初始化 */
+onMounted(async () => {
+  loading.value = true;
+  try {
+    areaTree.value = (await getAreaTree()) as AreaTreeNode[];
+    syncSelectedPath();
+  } finally {
+    loading.value = false;
+  }
+});
+</script>
+
+<template>
+  <Cascader
+    v-model:value="selectedPath"
+    :allow-clear="allowClear"
+    :change-on-select="changeOnSelect"
+    :field-names="fieldNames"
+    :loading="loading"
+    :options="areaTree"
+    :placeholder="placeholder"
+    :show-search="showSearch"
+    @change="handleChange"
+  />
+</template>
diff --git a/apps/web-antd/src/components/area/index.ts b/apps/web-antd/src/components/area/index.ts
new file mode 100644
index 000000000..013c0735a
--- /dev/null
+++ b/apps/web-antd/src/components/area/index.ts
@@ -0,0 +1 @@
+export { default as AreaCascader } from './area-cascader.vue';
diff --git a/apps/web-antd/src/views/crm/clue/data.ts b/apps/web-antd/src/views/crm/clue/data.ts
index 2cd328dde..018c0791d 100644
--- a/apps/web-antd/src/views/crm/clue/data.ts
+++ b/apps/web-antd/src/views/crm/clue/data.ts
@@ -1,12 +1,14 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { useUserStore } from '@vben/stores';
 
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -119,11 +121,12 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '地址',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
+        allowClear: true,
+        class: '!w-full',
         placeholder: '请选择地址',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-antd/src/views/crm/contact/data.ts b/apps/web-antd/src/views/crm/contact/data.ts
index 61a68c44c..b798a1227 100644
--- a/apps/web-antd/src/views/crm/contact/data.ts
+++ b/apps/web-antd/src/views/crm/contact/data.ts
@@ -1,14 +1,16 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { useUserStore } from '@vben/stores';
 
 import { getSimpleContactList } from '#/api/crm/contact';
 import { getCustomerSimpleList } from '#/api/crm/customer';
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 
 /** 新增/修改的表单 */
 export function useFormSchema(): VbenFormSchema[] {
@@ -143,11 +145,12 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '地址',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
+        allowClear: true,
+        class: '!w-full',
         placeholder: '请选择地址',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-antd/src/views/crm/customer/data.ts b/apps/web-antd/src/views/crm/customer/data.ts
index baabb5685..199eac0d9 100644
--- a/apps/web-antd/src/views/crm/customer/data.ts
+++ b/apps/web-antd/src/views/crm/customer/data.ts
@@ -1,13 +1,15 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { z } from '@vben/common-ui';
 import { DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { useUserStore } from '@vben/stores';
 
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -128,12 +130,12 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '地址',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
-        placeholder: '请选择地址',
         allowClear: true,
+        class: '!w-full',
+        placeholder: '请选择地址',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-antd/src/views/mall/trade/delivery/pickUpStore/data.ts b/apps/web-antd/src/views/mall/trade/delivery/pickUpStore/data.ts
index 666db4f8f..ab6c04ba9 100644
--- a/apps/web-antd/src/views/mall/trade/delivery/pickUpStore/data.ts
+++ b/apps/web-antd/src/views/mall/trade/delivery/pickUpStore/data.ts
@@ -1,12 +1,14 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 
 import { z } from '#/adapter/form';
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -62,12 +64,13 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '门店所在地区',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       rules: 'required',
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
+        allowClear: true,
+        class: '!w-full',
         placeholder: '请选择省市区',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-antd/src/views/mall/trade/order/data.ts b/apps/web-antd/src/views/mall/trade/order/data.ts
index 9b38da130..de2716f99 100644
--- a/apps/web-antd/src/views/mall/trade/order/data.ts
+++ b/apps/web-antd/src/views/mall/trade/order/data.ts
@@ -2,13 +2,15 @@ import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeGridPropTypes } from '#/adapter/vxe-table';
 import type { MallDeliveryPickUpStoreApi } from '#/api/mall/trade/delivery/pickUpStore';
 
+import { markRaw } from 'vue';
+
 import { DeliveryTypeEnum, DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { convertToInteger, formatToFraction } from '@vben/utils';
 
 import { getSimpleDeliveryExpressList } from '#/api/mall/trade/delivery/express';
 import { getSimpleDeliveryPickUpStoreList } from '#/api/mall/trade/delivery/pickUpStore';
-import { getAreaTree } from '#/api/system/area';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 关联数据 */
@@ -368,14 +370,13 @@ export function useAddressFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'receiverAreaId',
       label: '所在地',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        labelField: 'name',
-        valueField: 'id',
-        childrenField: 'children',
+        allowClear: true,
+        changeOnSelect: true,
+        class: '!w-full',
         placeholder: '请选择收件人所在地',
-        treeDefaultExpandAll: true,
+        showSearch: true,
       },
       rules: 'required',
     },
diff --git a/apps/web-antd/src/views/member/user/data.ts b/apps/web-antd/src/views/member/user/data.ts
index 414227f46..155b7f5aa 100644
--- a/apps/web-antd/src/views/member/user/data.ts
+++ b/apps/web-antd/src/views/member/user/data.ts
@@ -1,7 +1,7 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
-import { h } from 'vue';
+import { h, markRaw } from 'vue';
 
 import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
@@ -13,7 +13,7 @@ import { z } from '#/adapter/form';
 import { getSimpleGroupList } from '#/api/member/group';
 import { getSimpleLevelList } from '#/api/member/level';
 import { getSimpleTagList } from '#/api/member/tag';
-import { getAreaTree } from '#/api/system/area';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -102,11 +102,13 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '所在地',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
+        allowClear: true,
+        changeOnSelect: true,
+        class: '!w-full',
         placeholder: '请选择所在地',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-antdv-next/src/components/area/area-cascader.vue b/apps/web-antdv-next/src/components/area/area-cascader.vue
new file mode 100644
index 000000000..d015cc922
--- /dev/null
+++ b/apps/web-antdv-next/src/components/area/area-cascader.vue
@@ -0,0 +1,125 @@
+<script lang="ts" setup>
+import type { CascaderProps } from 'ant-design-vue';
+
+import type { SystemAreaApi } from '#/api/system/area';
+
+import { onMounted, ref, watch } from 'vue';
+
+import { Cascader } from 'ant-design-vue';
+
+import { getAreaTree } from '#/api/system/area';
+
+defineOptions({ name: 'AreaCascader' });
+
+const props = withDefaults(defineProps<Props>(), {
+  allowClear: false,
+  changeOnSelect: false,
+  modelValue: undefined,
+  placeholder: '请选择省市区',
+  showSearch: false,
+});
+
+const emit = defineEmits<{
+  'update:modelValue': [value?: number];
+}>();
+
+interface Props {
+  allowClear?: boolean;
+  changeOnSelect?: boolean;
+  modelValue?: number;
+  placeholder?: string;
+  showSearch?: boolean;
+}
+
+type AreaTreeNode = SystemAreaApi.Area & {
+  children?: AreaTreeNode[];
+};
+
+const areaTree = ref<AreaTreeNode[]>([]); // 地区树
+const loading = ref(false); // 加载状态
+const selectedPath = ref<number[]>(); // 选中的地区路径
+
+const fieldNames = {
+  children: 'children', // 子级字段
+  label: 'name', // 标签字段
+  value: 'id', // 值字段
+};
+
+/**
+ * 查找地区编号对应的级联路径
+ *
+ * @param tree 地区树
+ * @param areaId 地区编号
+ * @returns 省市区编号路径
+ */
+function findAreaPath(
+  tree: AreaTreeNode[],
+  areaId?: number,
+): number[] | undefined {
+  if (areaId === undefined || areaId === null) {
+    return undefined;
+  }
+
+  for (const area of tree) {
+    if (area.id === undefined) {
+      continue;
+    }
+    if (area.id === areaId) {
+      return [area.id];
+    }
+
+    const childPath = area.children?.length
+      ? findAreaPath(area.children, areaId)
+      : undefined;
+    if (childPath) {
+      return [area.id, ...childPath];
+    }
+  }
+}
+
+/** 同步级联选择器展示路径 */
+function syncSelectedPath() {
+  selectedPath.value = findAreaPath(areaTree.value, props.modelValue);
+}
+
+/** 选择地区后回写最后一级地区编号 */
+const handleChange: NonNullable<CascaderProps['onChange']> = (value) => {
+  if (!value?.length) {
+    emit('update:modelValue', undefined);
+    return;
+  }
+
+  const path = Array.isArray(value[0]) ? value[0] : value;
+  const leafValue = path.at(-1);
+  const areaId =
+    typeof leafValue === 'number' ? leafValue : Number(leafValue);
+  emit('update:modelValue', Number.isNaN(areaId) ? undefined : areaId);
+};
+
+watch(() => props.modelValue, syncSelectedPath);
+
+/** 初始化 */
+onMounted(async () => {
+  loading.value = true;
+  try {
+    areaTree.value = (await getAreaTree()) as AreaTreeNode[];
+    syncSelectedPath();
+  } finally {
+    loading.value = false;
+  }
+});
+</script>
+
+<template>
+  <Cascader
+    v-model:value="selectedPath"
+    :allow-clear="allowClear"
+    :change-on-select="changeOnSelect"
+    :field-names="fieldNames"
+    :loading="loading"
+    :options="areaTree"
+    :placeholder="placeholder"
+    :show-search="showSearch"
+    @change="handleChange"
+  />
+</template>
diff --git a/apps/web-antdv-next/src/components/area/index.ts b/apps/web-antdv-next/src/components/area/index.ts
new file mode 100644
index 000000000..013c0735a
--- /dev/null
+++ b/apps/web-antdv-next/src/components/area/index.ts
@@ -0,0 +1 @@
+export { default as AreaCascader } from './area-cascader.vue';
diff --git a/apps/web-antdv-next/src/views/crm/clue/data.ts b/apps/web-antdv-next/src/views/crm/clue/data.ts
index 0cef1f17a..896439ca4 100644
--- a/apps/web-antdv-next/src/views/crm/clue/data.ts
+++ b/apps/web-antdv-next/src/views/crm/clue/data.ts
@@ -1,12 +1,14 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { useUserStore } from '@vben/stores';
 
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -119,11 +121,12 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '地址',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
+        allowClear: true,
+        class: '!w-full',
         placeholder: '请选择地址',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-antdv-next/src/views/crm/contact/data.ts b/apps/web-antdv-next/src/views/crm/contact/data.ts
index 584ad0ead..f6e49e07e 100644
--- a/apps/web-antdv-next/src/views/crm/contact/data.ts
+++ b/apps/web-antdv-next/src/views/crm/contact/data.ts
@@ -1,14 +1,16 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { useUserStore } from '@vben/stores';
 
 import { getSimpleContactList } from '#/api/crm/contact';
 import { getCustomerSimpleList } from '#/api/crm/customer';
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 
 /** 新增/修改的表单 */
 export function useFormSchema(): VbenFormSchema[] {
@@ -143,11 +145,12 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '地址',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
+        allowClear: true,
+        class: '!w-full',
         placeholder: '请选择地址',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-antdv-next/src/views/crm/customer/data.ts b/apps/web-antdv-next/src/views/crm/customer/data.ts
index 3dc41570b..cb2ca7528 100644
--- a/apps/web-antdv-next/src/views/crm/customer/data.ts
+++ b/apps/web-antdv-next/src/views/crm/customer/data.ts
@@ -1,13 +1,15 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { z } from '@vben/common-ui';
 import { DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { useUserStore } from '@vben/stores';
 
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -128,12 +130,12 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '地址',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
-        placeholder: '请选择地址',
         allowClear: true,
+        class: '!w-full',
+        placeholder: '请选择地址',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-antdv-next/src/views/mall/trade/delivery/pickUpStore/data.ts b/apps/web-antdv-next/src/views/mall/trade/delivery/pickUpStore/data.ts
index fadb062ad..4af395e1b 100644
--- a/apps/web-antdv-next/src/views/mall/trade/delivery/pickUpStore/data.ts
+++ b/apps/web-antdv-next/src/views/mall/trade/delivery/pickUpStore/data.ts
@@ -1,12 +1,14 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 
 import { z } from '#/adapter/form';
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -62,12 +64,13 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '门店所在地区',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       rules: 'required',
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
+        allowClear: true,
+        class: '!w-full',
         placeholder: '请选择省市区',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-antdv-next/src/views/mall/trade/order/data.ts b/apps/web-antdv-next/src/views/mall/trade/order/data.ts
index 9b38da130..de2716f99 100644
--- a/apps/web-antdv-next/src/views/mall/trade/order/data.ts
+++ b/apps/web-antdv-next/src/views/mall/trade/order/data.ts
@@ -2,13 +2,15 @@ import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeGridPropTypes } from '#/adapter/vxe-table';
 import type { MallDeliveryPickUpStoreApi } from '#/api/mall/trade/delivery/pickUpStore';
 
+import { markRaw } from 'vue';
+
 import { DeliveryTypeEnum, DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { convertToInteger, formatToFraction } from '@vben/utils';
 
 import { getSimpleDeliveryExpressList } from '#/api/mall/trade/delivery/express';
 import { getSimpleDeliveryPickUpStoreList } from '#/api/mall/trade/delivery/pickUpStore';
-import { getAreaTree } from '#/api/system/area';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 关联数据 */
@@ -368,14 +370,13 @@ export function useAddressFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'receiverAreaId',
       label: '所在地',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        labelField: 'name',
-        valueField: 'id',
-        childrenField: 'children',
+        allowClear: true,
+        changeOnSelect: true,
+        class: '!w-full',
         placeholder: '请选择收件人所在地',
-        treeDefaultExpandAll: true,
+        showSearch: true,
       },
       rules: 'required',
     },
diff --git a/apps/web-antdv-next/src/views/member/user/data.ts b/apps/web-antdv-next/src/views/member/user/data.ts
index 9b49c8d6b..7baf28deb 100644
--- a/apps/web-antdv-next/src/views/member/user/data.ts
+++ b/apps/web-antdv-next/src/views/member/user/data.ts
@@ -1,7 +1,7 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
-import { h } from 'vue';
+import { h, markRaw } from 'vue';
 
 import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
@@ -13,7 +13,7 @@ import { z } from '#/adapter/form';
 import { getSimpleGroupList } from '#/api/member/group';
 import { getSimpleLevelList } from '#/api/member/level';
 import { getSimpleTagList } from '#/api/member/tag';
-import { getAreaTree } from '#/api/system/area';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -102,11 +102,13 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '所在地',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        fieldNames: { label: 'name', value: 'id', children: 'children' },
+        allowClear: true,
+        changeOnSelect: true,
+        class: '!w-full',
         placeholder: '请选择所在地',
+        showSearch: true,
       },
     },
     {
diff --git a/apps/web-ele/src/components/area/area-cascader.vue b/apps/web-ele/src/components/area/area-cascader.vue
new file mode 100644
index 000000000..8850b6e00
--- /dev/null
+++ b/apps/web-ele/src/components/area/area-cascader.vue
@@ -0,0 +1,124 @@
+<script lang="ts" setup>
+import type { CascaderValue } from 'element-plus';
+
+import type { SystemAreaApi } from '#/api/system/area';
+
+import { onMounted, ref, watch } from 'vue';
+
+import { ElCascader } from 'element-plus';
+
+import { getAreaTree } from '#/api/system/area';
+
+defineOptions({ name: 'AreaCascader' });
+
+const props = withDefaults(defineProps<Props>(), {
+  checkStrictly: false,
+  clearable: false,
+  filterable: false,
+  modelValue: undefined,
+  placeholder: '请选择省市区',
+});
+
+const emit = defineEmits<{
+  'update:modelValue': [value?: number];
+}>();
+
+interface Props {
+  checkStrictly?: boolean;
+  clearable?: boolean;
+  filterable?: boolean;
+  modelValue?: number;
+  placeholder?: string;
+}
+
+type AreaTreeNode = SystemAreaApi.Area & {
+  children?: AreaTreeNode[];
+};
+
+const areaTree = ref<AreaTreeNode[]>([]); // 地区树
+const loading = ref(false); // 加载状态
+const selectedPath = ref<number[]>(); // 选中的地区路径
+
+/**
+ * 查找地区编号对应的级联路径
+ *
+ * @param tree 地区树
+ * @param areaId 地区编号
+ * @returns 省市区编号路径
+ */
+function findAreaPath(
+  tree: AreaTreeNode[],
+  areaId?: number,
+): number[] | undefined {
+  if (areaId === undefined || areaId === null) {
+    return undefined;
+  }
+
+  for (const area of tree) {
+    if (area.id === undefined) {
+      continue;
+    }
+    if (area.id === areaId) {
+      return [area.id];
+    }
+
+    const childPath = area.children?.length
+      ? findAreaPath(area.children, areaId)
+      : undefined;
+    if (childPath) {
+      return [area.id, ...childPath];
+    }
+  }
+}
+
+/** 同步级联选择器展示路径 */
+function syncSelectedPath() {
+  selectedPath.value = findAreaPath(areaTree.value, props.modelValue);
+}
+
+/** 选择地区后回写最后一级地区编号 */
+function handleChange(value?: CascaderValue | null) {
+  if (!Array.isArray(value) || value.length === 0) {
+    emit('update:modelValue', undefined);
+    return;
+  }
+
+  const path = Array.isArray(value[0]) ? value[0] : value;
+  const leafValue = path.at(-1);
+  const areaId =
+    typeof leafValue === 'number' ? leafValue : Number(leafValue);
+  emit('update:modelValue', Number.isNaN(areaId) ? undefined : areaId);
+}
+
+watch(() => props.modelValue, syncSelectedPath);
+
+/** 初始化 */
+onMounted(async () => {
+  loading.value = true;
+  try {
+    areaTree.value = (await getAreaTree()) as AreaTreeNode[];
+    syncSelectedPath();
+  } finally {
+    loading.value = false;
+  }
+});
+</script>
+
+<template>
+  <ElCascader
+    v-model="selectedPath"
+    :clearable="clearable"
+    :filterable="filterable"
+    :loading="loading"
+    :options="areaTree"
+    :placeholder="placeholder"
+    :props="{
+      checkStrictly,
+      children: 'children',
+      emitPath: true,
+      label: 'name',
+      value: 'id',
+    }"
+    @change="handleChange"
+  />
+</template>
diff --git a/apps/web-ele/src/components/area/index.ts b/apps/web-ele/src/components/area/index.ts
new file mode 100644
index 000000000..013c0735a
--- /dev/null
+++ b/apps/web-ele/src/components/area/index.ts
@@ -0,0 +1 @@
+export { default as AreaCascader } from './area-cascader.vue';
diff --git a/apps/web-ele/src/views/crm/clue/data.ts b/apps/web-ele/src/views/crm/clue/data.ts
index 36dab785b..af6f906b8 100644
--- a/apps/web-ele/src/views/crm/clue/data.ts
+++ b/apps/web-ele/src/views/crm/clue/data.ts
@@ -1,12 +1,14 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { useUserStore } from '@vben/stores';
 
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -119,12 +121,11 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '地址',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        labelField: 'name',
-        valueField: 'id',
-        childrenField: 'children',
+        class: '!w-full',
+        clearable: true,
+        filterable: true,
         placeholder: '请选择地址',
       },
     },
diff --git a/apps/web-ele/src/views/crm/contact/data.ts b/apps/web-ele/src/views/crm/contact/data.ts
index 6b3a2f9d6..a3631d915 100644
--- a/apps/web-ele/src/views/crm/contact/data.ts
+++ b/apps/web-ele/src/views/crm/contact/data.ts
@@ -1,14 +1,16 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { useUserStore } from '@vben/stores';
 
 import { getSimpleContactList } from '#/api/crm/contact';
 import { getCustomerSimpleList } from '#/api/crm/customer';
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 
 /** 新增/修改的表单 */
 export function useFormSchema(): VbenFormSchema[] {
@@ -141,12 +143,11 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '地址',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        labelField: 'name',
-        valueField: 'id',
-        childrenField: 'children',
+        class: '!w-full',
+        clearable: true,
+        filterable: true,
         placeholder: '请选择地址',
       },
     },
diff --git a/apps/web-ele/src/views/crm/customer/data.ts b/apps/web-ele/src/views/crm/customer/data.ts
index 322352e76..098c2deb6 100644
--- a/apps/web-ele/src/views/crm/customer/data.ts
+++ b/apps/web-ele/src/views/crm/customer/data.ts
@@ -1,13 +1,15 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { z } from '@vben/common-ui';
 import { DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { useUserStore } from '@vben/stores';
 
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -128,14 +130,12 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '地址',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        labelField: 'name',
-        valueField: 'id',
-        childrenField: 'children',
+        class: '!w-full',
+        clearable: true,
+        filterable: true,
         placeholder: '请选择地址',
-        allowClear: true,
       },
     },
     {
diff --git a/apps/web-ele/src/views/mall/trade/delivery/pickUpStore/data.ts b/apps/web-ele/src/views/mall/trade/delivery/pickUpStore/data.ts
index 19922a003..6a061196c 100644
--- a/apps/web-ele/src/views/mall/trade/delivery/pickUpStore/data.ts
+++ b/apps/web-ele/src/views/mall/trade/delivery/pickUpStore/data.ts
@@ -1,12 +1,14 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
+import { markRaw } from 'vue';
+
 import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 
 import { z } from '#/adapter/form';
-import { getAreaTree } from '#/api/system/area';
 import { getSimpleUserList } from '#/api/system/user';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -62,13 +64,12 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '门店所在地区',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       rules: 'required',
       componentProps: {
-        api: getAreaTree,
-        labelField: 'name',
-        valueField: 'id',
-        childrenField: 'children',
+        class: '!w-full',
+        clearable: true,
+        filterable: true,
         placeholder: '请选择省市区',
       },
     },
diff --git a/apps/web-ele/src/views/mall/trade/order/data.ts b/apps/web-ele/src/views/mall/trade/order/data.ts
index e94a07b4e..15a592672 100644
--- a/apps/web-ele/src/views/mall/trade/order/data.ts
+++ b/apps/web-ele/src/views/mall/trade/order/data.ts
@@ -2,13 +2,15 @@ import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeGridPropTypes } from '#/adapter/vxe-table';
 import type { MallDeliveryPickUpStoreApi } from '#/api/mall/trade/delivery/pickUpStore';
 
+import { markRaw } from 'vue';
+
 import { DeliveryTypeEnum, DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
 import { convertToInteger, formatToFraction } from '@vben/utils';
 
 import { getSimpleDeliveryExpressList } from '#/api/mall/trade/delivery/express';
 import { getSimpleDeliveryPickUpStoreList } from '#/api/mall/trade/delivery/pickUpStore';
-import { getAreaTree } from '#/api/system/area';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 关联数据 */
@@ -369,14 +371,13 @@ export function useAddressFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'receiverAreaId',
       label: '所在地',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        labelField: 'name',
-        valueField: 'id',
-        childrenField: 'children',
+        checkStrictly: true,
+        class: '!w-full',
+        clearable: true,
+        filterable: true,
         placeholder: '请选择收件人所在地',
-        defaultExpandAll: true,
       },
       rules: 'required',
     },
diff --git a/apps/web-ele/src/views/member/user/data.ts b/apps/web-ele/src/views/member/user/data.ts
index 5099ddf92..424fd1ac0 100644
--- a/apps/web-ele/src/views/member/user/data.ts
+++ b/apps/web-ele/src/views/member/user/data.ts
@@ -1,7 +1,7 @@
 import type { VbenFormSchema } from '#/adapter/form';
 import type { VxeTableGridOptions } from '#/adapter/vxe-table';
 
-import { h } from 'vue';
+import { h, markRaw } from 'vue';
 
 import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
 import { getDictOptions } from '@vben/hooks';
@@ -13,7 +13,7 @@ import { z } from '#/adapter/form';
 import { getSimpleGroupList } from '#/api/member/group';
 import { getSimpleLevelList } from '#/api/member/level';
 import { getSimpleTagList } from '#/api/member/tag';
-import { getAreaTree } from '#/api/system/area';
+import { AreaCascader } from '#/components/area';
 import { getRangePickerDefaultProps } from '#/utils';
 
 /** 新增/修改的表单 */
@@ -99,12 +99,12 @@ export function useFormSchema(): VbenFormSchema[] {
     {
       fieldName: 'areaId',
       label: '所在地',
-      component: 'ApiTreeSelect',
+      component: markRaw(AreaCascader),
       componentProps: {
-        api: getAreaTree,
-        labelField: 'name',
-        valueField: 'id',
-        childrenField: 'children',
+        checkStrictly: true,
+        class: '!w-full',
+        clearable: true,
+        filterable: true,
         placeholder: '请选择所在地',
       },
     },