From 51bca253457fc5d3a92eeb37063dce871ce30a57 Mon Sep 17 00:00:00 2001
From: ppxb <317842449@qq.com>
Date: Sat, 10 Jan 2026 14:06:03 +0800
Subject: [PATCH 01/10] fix(lint): pnpm format lint warning (#7080)

---
 apps/web-antd/src/adapter/component/index.ts         |  2 ++
 .../composables/src/__tests__/use-sortable.test.ts   |  5 ++---
 packages/@core/preferences/src/preferences.ts        |  5 +++--
 packages/@core/ui-kit/form-ui/src/types.ts           |  6 +++---
 .../ui-kit/shadcn-ui/src/components/button/button.ts |  6 ++++--
 .../common-ui/src/components/captcha/types.ts        |  3 +--
 playground/src/adapter/component/index.ts            |  2 ++
 playground/src/router/routes/modules/demos.ts        | 12 +++---------
 playground/src/views/examples/context-menu/index.vue |  5 ++---
 9 files changed, 22 insertions(+), 24 deletions(-)

diff --git a/apps/web-antd/src/adapter/component/index.ts b/apps/web-antd/src/adapter/component/index.ts
index 79b9bf6f8..34c821cb5 100644
--- a/apps/web-antd/src/adapter/component/index.ts
+++ b/apps/web-antd/src/adapter/component/index.ts
@@ -3,6 +3,8 @@
  * 可用于 vben-form、vben-modal、vben-drawer 等组件使用,
  */
 
+/* eslint-disable vue/one-component-per-file */
+
 import type {
   UploadChangeParam,
   UploadFile,
diff --git a/packages/@core/composables/src/__tests__/use-sortable.test.ts b/packages/@core/composables/src/__tests__/use-sortable.test.ts
index e7ba1f134..b244067e1 100644
--- a/packages/@core/composables/src/__tests__/use-sortable.test.ts
+++ b/packages/@core/composables/src/__tests__/use-sortable.test.ts
@@ -29,9 +29,8 @@ describe('useSortable', () => {
     await initializeSortable();
 
     // Import sortablejs to access the mocked create function
-    const Sortable = await import(
-      'sortablejs/modular/sortable.complete.esm.js'
-    );
+    const Sortable =
+      await import('sortablejs/modular/sortable.complete.esm.js');
 
     // Verify that Sortable.create was called with the correct parameters
     expect(Sortable.default.create).toHaveBeenCalledTimes(1);
diff --git a/packages/@core/preferences/src/preferences.ts b/packages/@core/preferences/src/preferences.ts
index 93487d2c2..1dfd530c7 100644
--- a/packages/@core/preferences/src/preferences.ts
+++ b/packages/@core/preferences/src/preferences.ts
@@ -63,8 +63,9 @@ class PreferenceManager {
 
   /**
    * 初始化偏好设置
-   * @param namespace - 命名空间，用于隔离不同应用的配置
-   * @param overrides - 要覆盖的偏好设置
+   * @param options - 初始化配置项
+   * @param options.namespace - 命名空间，用于隔离不同应用的配置
+   * @param options.overrides - 要覆盖的偏好设置
    */
   initPreferences = async ({ namespace, overrides }: InitialOptions) => {
     // 防止重复初始化
diff --git a/packages/@core/ui-kit/form-ui/src/types.ts b/packages/@core/ui-kit/form-ui/src/types.ts
index 6d704145e..b5c5a4fbc 100644
--- a/packages/@core/ui-kit/form-ui/src/types.ts
+++ b/packages/@core/ui-kit/form-ui/src/types.ts
@@ -350,9 +350,9 @@ export interface ActionButtonOptions extends VbenButtonProps {
 export interface VbenFormProps<
   T extends BaseFormComponentType = BaseFormComponentType,
 > extends Omit<
-    FormRenderProps<T>,
-    'componentBindEventMap' | 'componentMap' | 'form'
-  > {
+  FormRenderProps<T>,
+  'componentBindEventMap' | 'componentMap' | 'form'
+> {
   /**
    * 操作按钮是否反转（提交按钮前置）
    */
diff --git a/packages/@core/ui-kit/shadcn-ui/src/components/button/button.ts b/packages/@core/ui-kit/shadcn-ui/src/components/button/button.ts
index e12729a4e..a55a4d238 100644
--- a/packages/@core/ui-kit/shadcn-ui/src/components/button/button.ts
+++ b/packages/@core/ui-kit/shadcn-ui/src/components/button/button.ts
@@ -27,8 +27,10 @@ export type CustomRenderType = (() => Component | string) | string;
 
 export type ValueType = boolean | number | string;
 
-export interface VbenButtonGroupProps
-  extends Pick<VbenButtonProps, 'disabled'> {
+export interface VbenButtonGroupProps extends Pick<
+  VbenButtonProps,
+  'disabled'
+> {
   /** 单选模式下允许清除选中 */
   allowClear?: boolean;
   /** 值改变前的回调 */
diff --git a/packages/effects/common-ui/src/components/captcha/types.ts b/packages/effects/common-ui/src/components/captcha/types.ts
index cd1efdf48..f73877eef 100644
--- a/packages/effects/common-ui/src/components/captcha/types.ts
+++ b/packages/effects/common-ui/src/components/captcha/types.ts
@@ -54,8 +54,7 @@ export interface PointSelectionCaptchaCardProps {
   width?: number | string;
 }
 
-export interface PointSelectionCaptchaProps
-  extends PointSelectionCaptchaCardProps {
+export interface PointSelectionCaptchaProps extends PointSelectionCaptchaCardProps {
   /**
    * 是否展示确定按钮
    * @default false
diff --git a/playground/src/adapter/component/index.ts b/playground/src/adapter/component/index.ts
index b0e43c9ac..48ce2fcc8 100644
--- a/playground/src/adapter/component/index.ts
+++ b/playground/src/adapter/component/index.ts
@@ -3,6 +3,8 @@
  * 可用于 vben-form、vben-modal、vben-drawer 等组件使用,
  */
 
+/* eslint-disable vue/one-component-per-file */
+
 import type {
   UploadChangeParam,
   UploadFile,
diff --git a/playground/src/router/routes/modules/demos.ts b/playground/src/router/routes/modules/demos.ts
index 3df4f0ad6..b8d27ef5a 100644
--- a/playground/src/router/routes/modules/demos.ts
+++ b/playground/src/router/routes/modules/demos.ts
@@ -157,9 +157,7 @@ const routes: RouteRecordRaw[] = [
                 name: 'HideChildrenInMenuDemo',
                 path: '',
                 component: () =>
-                  import(
-                    '#/views/demos/features/hide-menu-children/parent.vue'
-                  ),
+                  import('#/views/demos/features/hide-menu-children/parent.vue'),
                 meta: {
                   // hideInMenu: true,
                   title: $t('demos.features.hideChildrenInMenu'),
@@ -169,9 +167,7 @@ const routes: RouteRecordRaw[] = [
                 name: 'HideChildrenInMenuChildrenDemo',
                 path: '/demos/features/hide-menu-children/children',
                 component: () =>
-                  import(
-                    '#/views/demos/features/hide-menu-children/children.vue'
-                  ),
+                  import('#/views/demos/features/hide-menu-children/children.vue'),
                 meta: {
                   activePath: '/demos/features/hide-menu-children',
                   title: $t('demos.features.hideChildrenInMenu'),
@@ -247,9 +243,7 @@ const routes: RouteRecordRaw[] = [
             name: 'RequestParamsSerializerDemo',
             path: '/demos/features/request-params-serializer',
             component: () =>
-              import(
-                '#/views/demos/features/request-params-serializer/index.vue'
-              ),
+              import('#/views/demos/features/request-params-serializer/index.vue'),
             meta: {
               icon: 'lucide:git-pull-request-arrow',
               title: $t('demos.features.requestParamsSerializer'),
diff --git a/playground/src/views/examples/context-menu/index.vue b/playground/src/views/examples/context-menu/index.vue
index 4688015a6..711b4c6d4 100644
--- a/playground/src/views/examples/context-menu/index.vue
+++ b/playground/src/views/examples/context-menu/index.vue
@@ -43,15 +43,14 @@ const contextMenus = () => {
     },
   ];
 };
-
 </script>
 
 <template>
   <Page title="Context Menu 上下文菜单">
     <Card title="基本使用">
       <div>一共四个菜单（刷新、关闭当前、关闭其他、关闭所有）</div>
-      <br/>
-      <br/>
+      <br />
+      <br />
       <VbenContextMenu :menus="contextMenus" :modal="true" item-class="pr-6">
         <Button> 右键点击我打开上下文菜单(有隐藏项) </Button>
       </VbenContextMenu>

From 0d9e260a6a21e19d77c7778720cc13a503ab400f Mon Sep 17 00:00:00 2001
From: ppxb <317842449@qq.com>
Date: Sat, 10 Jan 2026 14:07:28 +0800
Subject: [PATCH 02/10] fix: vite.config.mts type error (#7081)

---
 internal/vite-config/src/config/index.ts |  4 ++--
 internal/vite-config/src/typing.ts       | 10 +++++++++-
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/internal/vite-config/src/config/index.ts b/internal/vite-config/src/config/index.ts
index d04a84a86..b8c770a95 100644
--- a/internal/vite-config/src/config/index.ts
+++ b/internal/vite-config/src/config/index.ts
@@ -1,4 +1,4 @@
-import type { DefineConfig } from '../typing';
+import type { DefineConfig, VbenViteConfig } from '../typing';
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -12,7 +12,7 @@ export * from './library';
 function defineConfig(
   userConfigPromise?: DefineConfig,
   type: 'application' | 'auto' | 'library' = 'auto',
-) {
+): VbenViteConfig {
   let projectType = type;
 
   // 根据包是否存在 index.html,自动判断类型
diff --git a/internal/vite-config/src/typing.ts b/internal/vite-config/src/typing.ts
index f730bdb91..2dd048306 100644
--- a/internal/vite-config/src/typing.ts
+++ b/internal/vite-config/src/typing.ts
@@ -1,5 +1,10 @@
 import type { PluginVisualizerOptions } from 'rollup-plugin-visualizer';
-import type { ConfigEnv, PluginOption, UserConfig } from 'vite';
+import type {
+  ConfigEnv,
+  PluginOption,
+  UserConfig,
+  UserConfigFnPromise,
+} from 'vite';
 import type { PluginOptions } from 'vite-plugin-dts';
 import type { Options as PwaPluginOptions } from 'vite-plugin-pwa';
 
@@ -327,6 +332,8 @@ type DefineLibraryOptions = (config?: ConfigEnv) => Promise<{
  */
 type DefineConfig = DefineApplicationOptions | DefineLibraryOptions;
 
+type VbenViteConfig = Promise<UserConfig> | UserConfig | UserConfigFnPromise;
+
 export type {
   ApplicationPluginOptions,
   ArchiverPluginOptions,
@@ -340,4 +347,5 @@ export type {
   LibraryPluginOptions,
   NitroMockPluginOptions,
   PrintPluginOptions,
+  VbenViteConfig,
 };

From 9480f8272a16025c59a1c6564ada9a8f97c5f2ef Mon Sep 17 00:00:00 2001
From: JyQAQ <45193678+jyqwq@users.noreply.github.com>
Date: Sat, 10 Jan 2026 14:08:15 +0800
Subject: [PATCH 03/10] feat(common-ui cropper): Implement the image cropping
 component VCropper (#7082)

* feat(common-ui cropper): Implement the image cropping component VCropper

* feat(common-ui cropper): Implement the image cropping component VCropper

* feat(common-ui cropper): Implement the image cropping component VCropper

* feat(common-ui cropper): Implement the image cropping component VCropper

* feat(common-ui cropper): Implement the image cropping component VCropper
---
 .../src/components/cropper/cropper.vue        | 956 ++++++++++++++++++
 .../common-ui/src/components/cropper/index.ts |   1 +
 .../effects/common-ui/src/components/index.ts |   1 +
 .../src/locales/langs/en-US/examples.json     |   3 +
 .../src/locales/langs/zh-CN/examples.json     |   3 +
 .../src/router/routes/modules/examples.ts     |   9 +
 .../src/views/examples/cropper/index.vue      | 138 +++
 7 files changed, 1111 insertions(+)
 create mode 100644 packages/effects/common-ui/src/components/cropper/cropper.vue
 create mode 100644 packages/effects/common-ui/src/components/cropper/index.ts
 create mode 100644 playground/src/views/examples/cropper/index.vue

diff --git a/packages/effects/common-ui/src/components/cropper/cropper.vue b/packages/effects/common-ui/src/components/cropper/cropper.vue
new file mode 100644
index 000000000..dc79d463c
--- /dev/null
+++ b/packages/effects/common-ui/src/components/cropper/cropper.vue
@@ -0,0 +1,956 @@
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref, watch } from 'vue';
+
+// 定义组件参数
+const props = defineProps<{
+  /** 裁剪比例 格式如 '1:1', '16:9', '3:4' 等（非必填） */
+  aspectRatio?: string;
+  /** 容器高度（默认400） */
+  height?: number;
+  /** 图片地址 */
+  img: string;
+  /** 容器宽度（默认500） */
+  width?: number;
+}>();
+
+const CROPPER_CONSTANTS = {
+  MIN_WIDTH: 60 as const,
+  MIN_HEIGHT: 60 as const,
+  DEFAULT_WIDTH: 500 as const,
+  DEFAULT_HEIGHT: 400 as const,
+  PADDING_RATIO: 0.1 as const,
+  MAX_PADDING: 50 as const,
+} as const;
+
+type Point = [number, number]; // [clientX, clientY]
+type Dimension = [number, number, number, number]; // [top, right, bottom, left]
+
+// 拖拽点类型
+type DragAction =
+  | 'bottom'
+  | 'bottom-left'
+  | 'bottom-right'
+  | 'left'
+  | 'move'
+  | 'right'
+  | 'top'
+  | 'top-left'
+  | 'top-right';
+
+// DOM 引用
+const containerRef = ref<HTMLDivElement | null>(null);
+const bgImageRef = ref<HTMLImageElement | null>(null);
+const maskRef = ref<HTMLDivElement | null>(null);
+const maskViewRef = ref<HTMLDivElement | null>(null);
+const cropperRef = ref<HTMLDivElement | null>(null);
+const cropperViewRef = ref<HTMLDivElement | null>(null);
+
+// 响应式数据
+const isCropperVisible = ref<boolean>(false);
+const validAspectRatio = ref<null | number>(null); // 有效比例值（null表示无固定比例）
+const containerWidth = ref<number>(
+  props.width ?? CROPPER_CONSTANTS.DEFAULT_WIDTH,
+);
+const containerHeight = ref<number>(
+  props.height ?? CROPPER_CONSTANTS.DEFAULT_HEIGHT,
+);
+
+// 裁剪区域尺寸（top, right, bottom, left）
+const currentDimension = ref<Dimension>([50, 50, 50, 50]);
+const initDimension = ref<Dimension>([50, 50, 50, 50]);
+
+// 拖拽状态
+const dragging = ref<boolean>(false);
+const startPoint = ref<Point>([0, 0]);
+const startDimension = ref<Dimension>([0, 0, 0, 0]);
+const direction = ref<Dimension>([0, 0, 0, 0]);
+const moving = ref<boolean>(false);
+
+/**
+ * 计算图片的适配尺寸，保证完整显示且不超过最大宽高限制
+ */
+const calculateImageFitSize = () => {
+  if (!bgImageRef.value) return;
+
+  // 获取图片原始尺寸
+  const imgWidth = bgImageRef.value.naturalWidth;
+  const imgHeight = bgImageRef.value.naturalHeight;
+
+  if (imgWidth === 0 || imgHeight === 0) return;
+
+  // 计算缩放比例（使用传入的width/height，默认500/400）
+  const widthRatio =
+    (props.width ?? CROPPER_CONSTANTS.DEFAULT_WIDTH) / imgWidth;
+  const heightRatio =
+    (props.height ?? CROPPER_CONSTANTS.DEFAULT_HEIGHT) / imgHeight;
+  const scaleRatio = Math.min(widthRatio, heightRatio, 1); // 不放大图片，只缩小
+
+  // 计算适配后的容器尺寸
+  const fitWidth = Math.floor(imgWidth * scaleRatio);
+  const fitHeight = Math.floor(imgHeight * scaleRatio);
+
+  containerWidth.value = fitWidth;
+  containerHeight.value = fitHeight;
+
+  // 重置裁剪框初始尺寸（基于新的容器尺寸）
+  const padding = Math.min(
+    CROPPER_CONSTANTS.MAX_PADDING,
+    Math.floor(fitWidth * CROPPER_CONSTANTS.PADDING_RATIO),
+    Math.floor(fitHeight * CROPPER_CONSTANTS.PADDING_RATIO),
+  );
+
+  initDimension.value = [padding, padding, padding, padding];
+  currentDimension.value = [padding, padding, padding, padding];
+};
+
+/**
+ * 验证并解析比例字符串
+ * @returns {number|null} 比例值 (width/height)，解析失败返回null
+ */
+const parseAndValidateAspectRatio = (): null | number => {
+  // 如果未传入比例参数，直接返回null
+  if (!props.aspectRatio) {
+    return null;
+  }
+
+  // 验证比例格式
+  const ratioRegex = /^[1-9]\d*:[1-9]\d*$/;
+  if (!ratioRegex.test(props.aspectRatio)) {
+    console.warn('裁剪比例格式错误，应为 "数字:数字" 格式，如 "16:9"');
+    return null;
+  }
+
+  // 解析比例
+  const [width, height] = props.aspectRatio.split(':').map(Number);
+
+  // 验证解析结果有效性
+  if (Number.isNaN(width) || Number.isNaN(height) || !width || !height) {
+    console.warn('裁剪比例解析失败，宽高必须为正整数');
+    return null;
+  }
+
+  return width / height;
+};
+
+/**
+ * 设置裁剪区域尺寸
+ * @param {Dimension} dimension - [top, right, bottom, left]
+ */
+const setDimension = (dimension: Dimension) => {
+  currentDimension.value = [...dimension];
+  if (maskViewRef.value) {
+    maskViewRef.value.style.clipPath = `inset(${dimension[0]}px ${dimension[1]}px ${dimension[2]}px ${dimension[3]}px)`;
+  }
+};
+
+/**
+ * 调整裁剪区域至指定比例
+ */
+const adjustCropperToAspectRatio = () => {
+  if (!cropperRef.value) return;
+
+  // 验证并解析比例
+  validAspectRatio.value = parseAndValidateAspectRatio();
+
+  // 如果无有效比例，使用初始尺寸，不强制固定比例
+  if (validAspectRatio.value === null) {
+    setDimension(initDimension.value);
+    return;
+  }
+
+  // 有有效比例，按比例调整裁剪框
+  const ratio = validAspectRatio.value;
+  const containerWidthVal = containerWidth.value;
+  const containerHeightVal = containerHeight.value;
+
+  // 根据比例计算裁剪框尺寸
+  let newHeight: number, newWidth: number;
+
+  // 先按宽度优先计算
+  newWidth = containerWidthVal;
+  newHeight = newWidth / ratio;
+
+  // 如果高度超出容器，按高度优先计算
+  if (newHeight > containerHeightVal) {
+    newHeight = containerHeightVal;
+    newWidth = newHeight * ratio;
+  }
+
+  // 居中显示
+  const leftRight = (containerWidthVal - newWidth) / 2;
+  const topBottom = (containerHeightVal - newHeight) / 2;
+
+  const newDimension: Dimension = [topBottom, leftRight, topBottom, leftRight];
+
+  setDimension(newDimension);
+};
+
+/**
+ * 创建裁剪器
+ */
+const createCropper = () => {
+  // 计算图片适配尺寸
+  calculateImageFitSize();
+
+  isCropperVisible.value = true;
+  adjustCropperToAspectRatio();
+};
+
+/**
+ * 处理鼠标按下事件
+ * @param {MouseEvent} e - 鼠标事件
+ * @param {DragAction} action - 操作类型
+ */
+const handleMouseDown = (e: MouseEvent, action: DragAction) => {
+  dragging.value = true;
+  startPoint.value = [e.clientX, e.clientY];
+  startDimension.value = [...currentDimension.value];
+  direction.value = [0, 0, 0, 0];
+  moving.value = false;
+
+  // 处理移动
+  if (action === 'move') {
+    direction.value[0] = 1;
+    direction.value[2] = -1;
+    direction.value[3] = 1;
+    direction.value[1] = -1;
+    moving.value = true;
+    return;
+  }
+
+  // 处理拖拽方向
+  switch (action) {
+    case 'bottom': {
+      direction.value[2] = -1;
+      break;
+    }
+    case 'bottom-left': {
+      direction.value[2] = -1;
+      direction.value[3] = 1;
+      break;
+    }
+    case 'bottom-right': {
+      direction.value[2] = -1;
+      direction.value[1] = -1;
+      break;
+    }
+    case 'left': {
+      direction.value[3] = 1;
+      break;
+    }
+    case 'right': {
+      direction.value[1] = -1;
+      break;
+    }
+    case 'top': {
+      direction.value[0] = 1;
+      break;
+    }
+    case 'top-left': {
+      direction.value[0] = 1;
+      direction.value[3] = 1;
+      break;
+    }
+    case 'top-right': {
+      direction.value[0] = 1;
+      direction.value[1] = -1;
+      break;
+    }
+  }
+};
+
+/**
+ * 处理鼠标移动事件
+ * @param {MouseEvent} e - 鼠标事件
+ */
+const handleMouseMove = (e: MouseEvent) => {
+  if (!dragging.value || !cropperRef.value) return;
+
+  const { clientX, clientY } = e;
+  const diffX = clientX - startPoint.value[0];
+  const diffY = clientY - startPoint.value[1];
+
+  // 处理移动裁剪框
+  if (moving.value) {
+    handleMoveCropBox(diffX, diffY);
+    return;
+  }
+
+  // 无有效比例
+  if (validAspectRatio.value === null) {
+    handleFreeAspectResize(diffX, diffY);
+  } else {
+    handleFixedAspectResize(diffX, diffY);
+  }
+};
+
+const handleMoveCropBox = (diffX: number, diffY: number) => {
+  const newDimension = [...startDimension.value] as Dimension;
+
+  // 计算临时偏移后的位置
+  const tempTop = startDimension.value[0] + diffY;
+  const tempLeft = startDimension.value[3] + diffX;
+
+  // 计算裁剪框的固定尺寸
+  const cropWidth =
+    containerWidth.value - startDimension.value[3] - startDimension.value[1];
+  const cropHeight =
+    containerHeight.value - startDimension.value[0] - startDimension.value[2];
+
+  // 边界限制：确保裁剪框完全在容器内，且尺寸不变
+  // 顶部边界：top >= 0，且 bottom = 容器高度 - top - 裁剪高度 >= 0
+  newDimension[0] = Math.max(
+    0,
+    Math.min(tempTop, containerHeight.value - cropHeight),
+  );
+  // 底部边界：bottom = 容器高度 - top - 裁剪高度（由top推导，无需额外计算）
+  newDimension[2] = containerHeight.value - newDimension[0] - cropHeight;
+  // 左侧边界：left >= 0，且 right = 容器宽度 - left - 裁剪宽度 >= 0
+  newDimension[3] = Math.max(
+    0,
+    Math.min(tempLeft, containerWidth.value - cropWidth),
+  );
+  // 右侧边界：right = 容器宽度 - left - 裁剪宽度（由left推导，无需额外计算）
+  newDimension[1] = containerWidth.value - newDimension[3] - cropWidth;
+
+  // 强制保证尺寸不变（兜底）
+  const finalWidth = containerWidth.value - newDimension[3] - newDimension[1];
+  const finalHeight = containerHeight.value - newDimension[0] - newDimension[2];
+
+  if (finalWidth !== cropWidth) {
+    newDimension[1] = containerWidth.value - newDimension[3] - cropWidth;
+  }
+
+  if (finalHeight !== cropHeight) {
+    newDimension[2] = containerHeight.value - newDimension[0] - cropHeight;
+  }
+
+  // 更新裁剪区域（仅位置变化，尺寸/比例完全不变）
+  setDimension(newDimension);
+};
+
+const handleFreeAspectResize = (diffX: number, diffY: number) => {
+  const cropperWidth = containerWidth.value;
+  const cropperHeight = containerHeight.value;
+  const currentDimensionNew: Dimension = [0, 0, 0, 0];
+
+  // 计算新的尺寸，确保不小于最小值
+  currentDimensionNew[0] = Math.min(
+    Math.max(startDimension.value[0] + direction.value[0] * diffY, 0),
+    cropperHeight - CROPPER_CONSTANTS.MIN_HEIGHT,
+  );
+
+  currentDimensionNew[1] = Math.min(
+    Math.max(startDimension.value[1] + direction.value[1] * diffX, 0),
+    cropperWidth - CROPPER_CONSTANTS.MIN_WIDTH,
+  );
+
+  currentDimensionNew[2] = Math.min(
+    Math.max(startDimension.value[2] + direction.value[2] * diffY, 0),
+    cropperHeight - CROPPER_CONSTANTS.MIN_HEIGHT,
+  );
+
+  currentDimensionNew[3] = Math.min(
+    Math.max(startDimension.value[3] + direction.value[3] * diffX, 0),
+    cropperWidth - CROPPER_CONSTANTS.MIN_WIDTH,
+  );
+
+  // 确保裁剪区域宽度和高度不小于最小值
+  const newWidth =
+    cropperWidth - currentDimensionNew[3] - currentDimensionNew[1];
+  const newHeight =
+    cropperHeight - currentDimensionNew[0] - currentDimensionNew[2];
+
+  if (newWidth < CROPPER_CONSTANTS.MIN_WIDTH) {
+    if (direction.value[3] === 1) {
+      currentDimensionNew[3] =
+        cropperWidth - currentDimensionNew[1] - CROPPER_CONSTANTS.MIN_WIDTH;
+    } else {
+      currentDimensionNew[1] =
+        cropperWidth - currentDimensionNew[3] - CROPPER_CONSTANTS.MIN_WIDTH;
+    }
+  }
+
+  if (newHeight < CROPPER_CONSTANTS.MIN_HEIGHT) {
+    if (direction.value[0] === 1) {
+      currentDimensionNew[0] =
+        cropperHeight - currentDimensionNew[2] - CROPPER_CONSTANTS.MIN_HEIGHT;
+    } else {
+      currentDimensionNew[2] =
+        cropperHeight - currentDimensionNew[0] - CROPPER_CONSTANTS.MIN_HEIGHT;
+    }
+  }
+
+  setDimension(currentDimensionNew);
+};
+
+const handleFixedAspectResize = (diffX: number, diffY: number) => {
+  if (validAspectRatio.value === null) return;
+  const cropperWidth = containerWidth.value;
+  const cropperHeight = containerHeight.value;
+  // 有有效比例 - 固定比例裁剪
+  const ratio = validAspectRatio.value;
+  const currentWidth =
+    cropperWidth - startDimension.value[3] - startDimension.value[1];
+  const currentHeight =
+    cropperHeight - startDimension.value[0] - startDimension.value[2];
+
+  let newHeight: number, newWidth: number;
+  let widthChange = 0;
+  let heightChange = 0;
+
+  // 计算宽度/高度变化量
+  if (direction.value[3] === 1) widthChange = -diffX;
+  else if (direction.value[1] === -1) widthChange = diffX;
+
+  if (direction.value[0] === 1) heightChange = -diffY;
+  else if (direction.value[2] === -1) heightChange = diffY;
+
+  const isCornerDrag =
+    (direction.value[3] === 1 || direction.value[1] === -1) &&
+    (direction.value[0] === 1 || direction.value[2] === -1);
+
+  // 计算新尺寸
+  if (isCornerDrag) {
+    if (Math.abs(widthChange) > Math.abs(heightChange)) {
+      newWidth = Math.max(
+        CROPPER_CONSTANTS.MIN_WIDTH,
+        currentWidth + widthChange,
+      );
+      newHeight = newWidth / ratio;
+    } else {
+      newHeight = Math.max(
+        CROPPER_CONSTANTS.MIN_HEIGHT,
+        currentHeight + heightChange,
+      );
+      newWidth = newHeight * ratio;
+    }
+  } else {
+    if (direction.value[3] === 1 || direction.value[1] === -1) {
+      newWidth = Math.max(
+        CROPPER_CONSTANTS.MIN_WIDTH,
+        currentWidth + widthChange,
+      );
+      newHeight = newWidth / ratio;
+    } else {
+      newHeight = Math.max(
+        CROPPER_CONSTANTS.MIN_HEIGHT,
+        currentHeight + heightChange,
+      );
+      newWidth = newHeight * ratio;
+    }
+  }
+
+  // 限制最大尺寸
+  const maxWidth = cropperWidth;
+  const maxHeight = cropperHeight;
+
+  if (newWidth > maxWidth) {
+    newWidth = maxWidth;
+    newHeight = newWidth / ratio;
+  }
+
+  if (newHeight > maxHeight) {
+    newHeight = maxHeight;
+    newWidth = newHeight * ratio;
+  }
+
+  // 计算新的位置
+  let newLeft = startDimension.value[3];
+  let newTop = startDimension.value[0];
+  let newRight = startDimension.value[1];
+  let newBottom = startDimension.value[2];
+
+  // 根据拖拽方向调整位置
+  if (direction.value[3] === 1) {
+    newLeft = cropperWidth - newWidth - startDimension.value[1];
+  } else if (direction.value[1] === -1) {
+    newRight = cropperWidth - newWidth - startDimension.value[3];
+  } else if (!isCornerDrag) {
+    // 居中调整
+    const currentHorizontalCenter = startDimension.value[3] + currentWidth / 2;
+    newLeft = Math.max(
+      0,
+      Math.min(cropperWidth - newWidth, currentHorizontalCenter - newWidth / 2),
+    );
+    newRight = cropperWidth - newWidth - newLeft;
+  }
+
+  if (direction.value[0] === 1) {
+    newTop = cropperHeight - newHeight - startDimension.value[2];
+  } else if (direction.value[2] === -1) {
+    newBottom = cropperHeight - newHeight - startDimension.value[0];
+  } else if (!isCornerDrag) {
+    // 居中调整
+    const currentVerticalCenter = startDimension.value[0] + currentHeight / 2;
+    newTop = Math.max(
+      0,
+      Math.min(
+        cropperHeight - newHeight,
+        currentVerticalCenter - newHeight / 2,
+      ),
+    );
+    newBottom = cropperHeight - newHeight - newTop;
+  }
+
+  // 边界检查
+  newLeft = Math.max(0, newLeft);
+  newTop = Math.max(0, newTop);
+  newRight = Math.max(0, newRight);
+  newBottom = Math.max(0, newBottom);
+
+  const newDimension: Dimension = [newTop, newRight, newBottom, newLeft];
+  setDimension(newDimension);
+};
+
+/**
+ * 处理鼠标抬起事件
+ */
+const handleMouseUp = () => {
+  dragging.value = false;
+  moving.value = false;
+  direction.value = [0, 0, 0, 0];
+};
+
+/**
+ * 处理图片加载完成
+ */
+const handleImageLoad = () => {
+  createCropper();
+};
+
+/**
+ * 裁剪图片
+ * @param {'image/jpeg' | 'image/png'} format - 输出图片格式
+ * @param {number} quality - 压缩质量（0-1）
+ * @param {number} targetWidth - 目标宽度（可选，不传则为原始裁剪宽度）
+ * @param {number} targetHeight - 目标高度（可选，不传则为原始裁剪高度）
+ */
+const getCropImage = async (
+  format: 'image/jpeg' | 'image/png' = 'image/jpeg',
+  quality: number = 0.92,
+  targetWidth?: number,
+  targetHeight?: number,
+): Promise<string | undefined> => {
+  if (!props.img || !bgImageRef.value || !containerRef.value) return;
+
+  // 创建临时图片对象获取原始尺寸
+  const tempImg = new Image();
+  // Only set crossOrigin for cross-origin URLs that need CORS
+  if (props.img.startsWith('http://') || props.img.startsWith('https://')) {
+    try {
+      const url = new URL(props.img);
+      if (url.origin !== location.origin) {
+        tempImg.crossOrigin = 'anonymous';
+      }
+    } catch {
+      // Invalid URL, proceed without crossOrigin
+    }
+  }
+
+  // 等待临时图片加载完成
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      tempImg.removeEventListener('load', handleLoad);
+      tempImg.removeEventListener('error', handleError);
+      reject(new Error('图片加载超时'));
+    }, 10_000);
+    const handleLoad = () => {
+      clearTimeout(timeout);
+      tempImg.removeEventListener('load', handleLoad);
+      tempImg.removeEventListener('error', handleError);
+      resolve();
+    };
+
+    const handleError = (err: ErrorEvent) => {
+      clearTimeout(timeout);
+      tempImg.removeEventListener('load', handleLoad);
+      tempImg.removeEventListener('error', handleError);
+      reject(new Error(`图片加载失败: ${err.message}`));
+    };
+
+    tempImg.addEventListener('load', handleLoad);
+    tempImg.addEventListener('error', handleError);
+
+    tempImg.src = props.img;
+  });
+
+  const containerRect = containerRef.value.getBoundingClientRect();
+  const imgRect = bgImageRef.value.getBoundingClientRect();
+
+  // 1. 计算图片在容器内的渲染参数
+  const containerWidth = containerRect.width;
+  const containerHeight = containerRect.height;
+  const renderedImgWidth = imgRect.width;
+  const renderedImgHeight = imgRect.height;
+  const imgOffsetX = (containerWidth - renderedImgWidth) / 2;
+  const imgOffsetY = (containerHeight - renderedImgHeight) / 2;
+
+  // 2. 计算裁剪框在容器内的实际坐标
+  const [cropTop, cropRight, cropBottom, cropLeft] = currentDimension.value;
+  const cropBoxWidth = containerWidth - cropLeft - cropRight;
+  const cropBoxHeight = containerHeight - cropTop - cropBottom;
+
+  // 3. 将裁剪框坐标转换为图片上的坐标（考虑图片偏移）
+  const cropOnImgX = cropLeft - imgOffsetX;
+  const cropOnImgY = cropTop - imgOffsetY;
+
+  // 4. 计算渲染图片到原始图片的缩放比例（关键：保留原始像素）
+  const scaleX = tempImg.width / renderedImgWidth;
+  const scaleY = tempImg.height / renderedImgHeight;
+
+  // 5. 映射到原始图片的裁剪区域（精确到原始像素）
+  const originalCropX = Math.max(0, Math.floor(cropOnImgX * scaleX));
+  const originalCropY = Math.max(0, Math.floor(cropOnImgY * scaleY));
+  const originalCropWidth = Math.min(
+    Math.floor(cropBoxWidth * scaleX),
+    tempImg.width - originalCropX,
+  );
+  const originalCropHeight = Math.min(
+    Math.floor(cropBoxHeight * scaleY),
+    tempImg.height - originalCropY,
+  );
+
+  // 6. 处理高清屏适配（关键：解决Retina屏模糊）
+  const dpr = window.devicePixelRatio || 1;
+
+  // 最终画布尺寸（优先使用原始裁剪尺寸，或目标尺寸）
+  const finalWidth = targetWidth || originalCropWidth;
+  const finalHeight = targetHeight || originalCropHeight;
+
+  // 创建画布（乘以设备像素比，保证高清）
+  const canvas = document.createElement('canvas');
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+
+  // 画布物理尺寸（适配高清屏）
+  canvas.width = finalWidth * dpr;
+  canvas.height = finalHeight * dpr;
+
+  // 画布显示尺寸（视觉尺寸）
+  canvas.style.width = `${finalWidth}px`;
+  canvas.style.height = `${finalHeight}px`;
+
+  // 缩放上下文（适配DPR）
+  ctx.scale(dpr, dpr);
+
+  // 7. 绘制裁剪后的图片（使用原始像素绘制，保证清晰度）
+  ctx.drawImage(
+    tempImg,
+    originalCropX, // 原始图片裁剪起始X（精确像素）
+    originalCropY, // 原始图片裁剪起始Y（精确像素）
+    originalCropWidth, // 原始图片裁剪宽度（精确像素）
+    originalCropHeight, // 原始图片裁剪高度（精确像素）
+    0, // 画布绘制起始X
+    0, // 画布绘制起始Y
+    finalWidth, // 画布绘制宽度（目标尺寸）
+    finalHeight, // 画布绘制高度（目标尺寸）
+  );
+
+  // 8. 导出图片（指定质量，平衡清晰度和体积）
+  return canvas.toDataURL(format, quality);
+};
+
+// 监听比例变化，重新调整裁剪框
+watch(() => props.aspectRatio, adjustCropperToAspectRatio);
+
+// 监听width/height变化，重新计算尺寸
+watch([() => props.width, () => props.height], () => {
+  calculateImageFitSize();
+  adjustCropperToAspectRatio();
+});
+
+// 组件挂载时注册全局事件
+onMounted(() => {
+  document.addEventListener('mousemove', handleMouseMove);
+  document.addEventListener('mouseup', handleMouseUp);
+
+  // 如果图片已经加载完成，手动触发创建裁剪器
+  if (
+    bgImageRef.value &&
+    bgImageRef.value.complete &&
+    bgImageRef.value.naturalWidth > 0
+  ) {
+    createCropper();
+  }
+});
+
+// 组件卸载时清理
+onUnmounted(() => {
+  document.removeEventListener('mousemove', handleMouseMove);
+  document.removeEventListener('mouseup', handleMouseUp);
+});
+
+defineExpose({ getCropImage });
+</script>
+
+<template>
+  <div
+    :style="{
+      width: `${width || CROPPER_CONSTANTS.DEFAULT_WIDTH}px`,
+      height: `${height || CROPPER_CONSTANTS.DEFAULT_HEIGHT}px`,
+    }"
+    class="cropper-action-wrapper"
+  >
+    <div
+      ref="containerRef"
+      class="cropper-container"
+      :style="{
+        width: `${containerWidth}px`,
+        height: `${containerHeight}px`,
+      }"
+    >
+      <!-- 原图展示 - 自适应尺寸 -->
+      <img
+        ref="bgImageRef"
+        class="cropper-image"
+        :src="img"
+        @load="handleImageLoad"
+        :style="{
+          maxWidth: '100%',
+          maxHeight: '100%',
+          objectFit: 'contain',
+        }"
+        alt="裁剪原图"
+      />
+
+      <!-- 遮罩层 -->
+      <div
+        ref="maskRef"
+        class="cropper-mask"
+        :style="{
+          display: isCropperVisible ? 'block' : 'none',
+          width: '100%',
+          height: '100%',
+        }"
+      >
+        <div
+          ref="maskViewRef"
+          class="cropper-mask-view"
+          :style="{
+            backgroundImage: `url(${img})`,
+            backgroundSize: 'contain',
+            backgroundPosition: 'center',
+            backgroundRepeat: 'no-repeat',
+            clipPath: `inset(${currentDimension[0]}px ${currentDimension[1]}px ${currentDimension[2]}px ${currentDimension[3]}px)`,
+            width: '100%',
+            height: '100%',
+          }"
+        ></div>
+      </div>
+
+      <!-- 裁剪框 -->
+      <div
+        ref="cropperRef"
+        class="cropper-box"
+        :style="{
+          display: isCropperVisible ? 'block' : 'none',
+          width: '100%',
+          height: '100%',
+        }"
+      >
+        <div
+          ref="cropperViewRef"
+          class="cropper-view"
+          :style="{
+            inset: `${currentDimension[0]}px ${currentDimension[1]}px ${currentDimension[2]}px ${currentDimension[3]}px`,
+          }"
+        >
+          <!-- 裁剪框辅助线-->
+          <span class="cropper-dashed-h"></span>
+          <span class="cropper-dashed-v"></span>
+
+          <!-- 裁剪框拖拽区域 -->
+          <span
+            class="cropper-move-area"
+            @mousedown="handleMouseDown($event, 'move')"
+          ></span>
+
+          <!-- 边框线 -->
+          <span class="cropper-line-e"></span>
+          <span class="cropper-line-n"></span>
+          <span class="cropper-line-w"></span>
+          <span class="cropper-line-s"></span>
+
+          <!-- 边角拖拽点 -->
+          <span
+            class="cropper-point cropper-point-ne"
+            @mousedown="handleMouseDown($event, 'top-right')"
+          >
+            <span class="cropper-point-inner"></span>
+          </span>
+          <span
+            class="cropper-point cropper-point-nw"
+            @mousedown="handleMouseDown($event, 'top-left')"
+          >
+            <span class="cropper-point-inner"></span>
+          </span>
+          <span
+            class="cropper-point cropper-point-sw"
+            @mousedown="handleMouseDown($event, 'bottom-left')"
+          >
+            <span class="cropper-point-inner"></span>
+          </span>
+          <span
+            class="cropper-point cropper-point-se"
+            @mousedown="handleMouseDown($event, 'bottom-right')"
+          >
+            <span class="cropper-point-inner"></span>
+          </span>
+
+          <!-- 边中点拖拽点 -->
+          <span
+            class="cropper-point cropper-point-e"
+            @mousedown="handleMouseDown($event, 'right')"
+          >
+            <span class="cropper-point-inner"></span>
+          </span>
+          <span
+            class="cropper-point cropper-point-n"
+            @mousedown="handleMouseDown($event, 'top')"
+          >
+            <span class="cropper-point-inner"></span>
+          </span>
+          <span
+            class="cropper-point cropper-point-w"
+            @mousedown="handleMouseDown($event, 'left')"
+          >
+            <span class="cropper-point-inner"></span>
+          </span>
+          <span
+            class="cropper-point cropper-point-s"
+            @mousedown="handleMouseDown($event, 'bottom')"
+          >
+            <span class="cropper-point-inner"></span>
+          </span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.cropper-action-wrapper {
+  @apply box-border flex items-center justify-center;
+  /* 马赛克背景 */
+  background-image:
+    linear-gradient(45deg, #ccc 25%, transparent 25%),
+    linear-gradient(-45deg, #ccc 25%, transparent 25%),
+    linear-gradient(45deg, transparent 75%, #ccc 75%),
+    linear-gradient(-45deg, transparent 75%, #ccc 75%);
+  background-size: 20px 20px;
+  background-position:
+    0 0,
+    0 10px,
+    10px -10px,
+    -10px 0;
+  background-color: transparent;
+}
+
+.cropper-container {
+  @apply relative;
+}
+
+.cropper-image {
+  @apply block;
+}
+
+/* 遮罩层 */
+.cropper-mask {
+  @apply absolute left-0 top-0 bg-black/50;
+}
+
+.cropper-mask-view {
+  @apply absolute left-0 top-0;
+}
+
+/* 裁剪框 */
+.cropper-box {
+  @apply absolute left-0 top-0 z-10;
+}
+
+.cropper-view {
+  @apply absolute bottom-0 left-0 right-0 top-0 select-none outline outline-1 outline-blue-500;
+}
+
+/* 裁剪框辅助线 */
+.cropper-dashed-h {
+  @apply absolute left-0 top-1/3 block h-1/3 w-full border-b border-t border-dashed border-gray-200/50;
+}
+
+.cropper-dashed-v {
+  @apply absolute left-1/3 top-0 block h-full w-1/3 border-l border-r border-dashed border-gray-200/50;
+}
+
+/* 裁剪框拖拽区域 */
+.cropper-move-area {
+  @apply absolute left-0 top-0 block h-full w-full cursor-move bg-white/10;
+}
+
+/* 边框拖拽线 */
+.cropper-line-e,
+.cropper-line-n,
+.cropper-line-w,
+.cropper-line-s {
+  @apply absolute block bg-blue-500/10;
+}
+
+.cropper-line-e {
+  @apply right-[-3px] top-0 h-full w-1;
+}
+
+.cropper-line-n {
+  @apply left-0 top-[-3px] h-1 w-full;
+}
+
+.cropper-line-w {
+  @apply left-[-3px] top-0 h-full w-1;
+}
+
+.cropper-line-s {
+  @apply bottom-[-3px] left-0 h-1 w-full;
+}
+
+/* 拖拽点 */
+.cropper-point {
+  @apply absolute flex h-2 w-2 items-center justify-center bg-blue-500;
+}
+
+.cropper-point-inner {
+  @apply block h-1.5 w-1.5 bg-white;
+}
+
+/* 边角拖拽点位置和光标 */
+.cropper-point-ne {
+  @apply right-[-5px] top-[-5px] cursor-ne-resize;
+}
+
+.cropper-point-nw {
+  @apply left-[-5px] top-[-5px] cursor-nw-resize;
+}
+
+.cropper-point-sw {
+  @apply bottom-[-5px] left-[-5px] cursor-sw-resize;
+}
+
+.cropper-point-se {
+  @apply bottom-[-5px] right-[-5px] cursor-se-resize;
+}
+
+/* 边中点拖拽点位置和光标 */
+.cropper-point-e {
+  @apply right-[-5px] top-1/2 -mt-1 cursor-e-resize;
+}
+
+.cropper-point-n {
+  @apply left-1/2 top-[-5px] -ml-1 cursor-n-resize;
+}
+
+.cropper-point-w {
+  @apply left-[-5px] top-1/2 -mt-1 cursor-w-resize;
+}
+
+.cropper-point-s {
+  @apply bottom-[-5px] left-1/2 -ml-1 cursor-s-resize;
+}
+</style>
diff --git a/packages/effects/common-ui/src/components/cropper/index.ts b/packages/effects/common-ui/src/components/cropper/index.ts
new file mode 100644
index 000000000..58a8f0ab6
--- /dev/null
+++ b/packages/effects/common-ui/src/components/cropper/index.ts
@@ -0,0 +1 @@
+export { default as VCropper } from './cropper.vue';
diff --git a/packages/effects/common-ui/src/components/index.ts b/packages/effects/common-ui/src/components/index.ts
index 9ff0d5ee1..33f32bd04 100644
--- a/packages/effects/common-ui/src/components/index.ts
+++ b/packages/effects/common-ui/src/components/index.ts
@@ -2,6 +2,7 @@ export * from './api-component';
 export * from './captcha';
 export * from './col-page';
 export * from './count-to';
+export * from './cropper';
 export * from './ellipsis-text';
 export * from './icon-picker';
 export * from './json-viewer';
diff --git a/playground/src/locales/langs/en-US/examples.json b/playground/src/locales/langs/en-US/examples.json
index 42a42d54e..958b0c83f 100644
--- a/playground/src/locales/langs/en-US/examples.json
+++ b/playground/src/locales/langs/en-US/examples.json
@@ -75,5 +75,8 @@
   },
   "function": {
     "contentMenu": "Content Menu"
+  },
+  "cropper": {
+    "title": "Cropper"
   }
 }
diff --git a/playground/src/locales/langs/zh-CN/examples.json b/playground/src/locales/langs/zh-CN/examples.json
index 8808b5a9a..3de48e214 100644
--- a/playground/src/locales/langs/zh-CN/examples.json
+++ b/playground/src/locales/langs/zh-CN/examples.json
@@ -75,5 +75,8 @@
   },
   "function": {
     "contentMenu": "上下文菜单"
+  },
+  "cropper": {
+    "title": "图片裁剪"
   }
 }
diff --git a/playground/src/router/routes/modules/examples.ts b/playground/src/router/routes/modules/examples.ts
index 5361fcc8f..017b2c22f 100644
--- a/playground/src/router/routes/modules/examples.ts
+++ b/playground/src/router/routes/modules/examples.ts
@@ -337,6 +337,15 @@ const routes: RouteRecordRaw[] = [
           title: $t('examples.function.contentMenu'),
         },
       },
+      {
+        name: 'CropperDemo',
+        path: '/examples/cropper',
+        component: () => import('#/views/examples/cropper/index.vue'),
+        meta: {
+          icon: 'mdi:crop',
+          title: $t('examples.cropper.title'),
+        },
+      },
     ],
   },
 ];
diff --git a/playground/src/views/examples/cropper/index.vue b/playground/src/views/examples/cropper/index.vue
new file mode 100644
index 000000000..615c95113
--- /dev/null
+++ b/playground/src/views/examples/cropper/index.vue
@@ -0,0 +1,138 @@
+<script lang="ts" setup>
+import type { UploadChangeParam } from 'ant-design-vue';
+
+import { ref } from 'vue';
+
+import { Page, VCropper } from '@vben/common-ui';
+
+import { Button, Card, Select, Upload } from 'ant-design-vue';
+
+const options = [
+  { label: '1:1', value: '1:1' },
+  { label: '16:9', value: '16:9' },
+  { label: '不限制', value: '' },
+];
+
+const cropperRef = ref<InstanceType<typeof VCropper>>();
+
+const cropLoading = ref(false);
+const validAspectRatio = ref<string | undefined>('1:1');
+const imgUrl = ref('');
+const cropperImg = ref();
+
+const selectImgFile = (event: UploadChangeParam) => {
+  const file = event.fileList[0]?.originFileObj;
+  if (!file) return;
+
+  if (!file.type.startsWith('image/')) {
+    console.error('请上传图片文件');
+    return;
+  }
+
+  const reader = new FileReader();
+  reader.addEventListener('load', (e) => {
+    imgUrl.value = e.target?.result as string;
+  });
+  reader.addEventListener('error', () => {
+    console.error('Failed to read file');
+  });
+
+  reader.readAsDataURL(file);
+};
+
+const cropImage = async () => {
+  if (!cropperRef.value) return;
+  cropLoading.value = true;
+  try {
+    cropperImg.value = await cropperRef.value.getCropImage();
+  } catch (error) {
+    console.error('图片裁剪失败:', error);
+  } finally {
+    cropLoading.value = false;
+  }
+};
+
+/**
+ * 下载图片
+ */
+const downloadImage = () => {
+  if (!cropperImg.value) return;
+
+  const link = document.createElement('a');
+  link.download = `cropped-image-${Date.now()}.png`;
+  link.href = cropperImg.value;
+  link.click();
+};
+</script>
+<template>
+  <Page
+    title="VCropper 图片裁剪"
+    description="VCropper是一个图片裁剪组件，提供基础的图片裁剪功能。"
+  >
+    <Card>
+      <div class="image-cropper-container">
+        <div class="cropper-ratio-display">
+          <label class="ratio-label">当前裁剪比例：</label>
+          <Select
+            class="w-24"
+            v-model:value="validAspectRatio"
+            :options="options"
+          />
+          <Upload
+            :max-count="1"
+            :show-upload-list="false"
+            :before-upload="() => false"
+            @change="selectImgFile"
+          >
+            <Button>上传图片</Button>
+          </Upload>
+        </div>
+
+        <div v-if="imgUrl" class="cropper-main-wrapper">
+          <VCropper
+            ref="cropperRef"
+            :img="imgUrl"
+            :aspect-ratio="validAspectRatio"
+            :width="600"
+            :height="600"
+          />
+
+          <!-- 操作按钮组 -->
+          <div class="cropper-btn-group">
+            <Button :loading="cropLoading" @click="cropImage" type="primary">
+              裁剪
+            </Button>
+            <Button v-if="cropperImg" @click="downloadImage" danger>
+              下载图片
+            </Button>
+          </div>
+
+          <!-- 裁剪预览 -->
+          <img
+            v-if="cropperImg"
+            class="h-full w-80"
+            :src="cropperImg"
+            alt="裁剪预览"
+          />
+        </div>
+      </div>
+    </Card>
+  </Page>
+</template>
+<style scoped>
+/* 比例展示区域 */
+.cropper-ratio-display {
+  @apply my-2.5 flex items-center justify-start gap-4;
+}
+
+.ratio-label {
+  @apply text-sm font-medium;
+}
+/* 主裁剪区域 */
+.cropper-main-wrapper {
+  @apply flex items-center gap-4;
+}
+.cropper-btn-group {
+  @apply flex flex-col gap-2;
+}
+</style>

From 343d8a1c1ed92576318f44a5e0cf3cb62d3833e3 Mon Sep 17 00:00:00 2001
From: yuhengshen <yuhengshen@qq.com>
Date: Sat, 10 Jan 2026 14:10:27 +0800
Subject: [PATCH 04/10] =?UTF-8?q?fix:=20=E5=88=87=E6=8D=A2=E6=97=B6?=
 =?UTF-8?q?=E5=8C=BA=E5=90=8E=EF=BC=8C=E9=A1=B5=E9=9D=A2=E4=B8=8D=E5=88=B7?=
 =?UTF-8?q?=E6=96=B0=20(#7085)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: 切换时区后，页面不刷新

* fix: keep-alive 的页面，i18n 和 timezone 不更新
---
 packages/effects/layouts/src/basic/layout.vue | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/packages/effects/layouts/src/basic/layout.vue b/packages/effects/layouts/src/basic/layout.vue
index 6263fbdfc..45b978334 100644
--- a/packages/effects/layouts/src/basic/layout.vue
+++ b/packages/effects/layouts/src/basic/layout.vue
@@ -14,7 +14,7 @@ import {
   updatePreferences,
   usePreferences,
 } from '@vben/preferences';
-import { useAccessStore } from '@vben/stores';
+import { useAccessStore, useTabbarStore, useTimezoneStore } from '@vben/stores';
 import { cloneDeep, mapTree } from '@vben/utils';
 
 import { VbenAdminLayout } from '@vben-core/layout-ui';
@@ -52,6 +52,7 @@ const {
   theme,
 } = usePreferences();
 const accessStore = useAccessStore();
+const timezoneStore = useTimezoneStore();
 const { refresh } = useRefresh();
 
 const sidebarTheme = computed(() => {
@@ -187,9 +188,19 @@ watch(
   },
 );
 
+const tabbarStore = useTabbarStore();
+
+function refreshAll() {
+  tabbarStore.cachedTabs.clear();
+  refresh();
+}
+
 // 语言更新后，刷新页面
 // i18n.global.locale会在preference.app.locale变更之后才会更新，因此watchpreference.app.locale是不合适的，刷新页面时可能语言配置尚未完全加载完成
-watch(i18n.global.locale, refresh, { flush: 'post' });
+watch(i18n.global.locale, refreshAll, { flush: 'post' });
+
+// 时区更新后，刷新页面
+watch(() => timezoneStore.timezone, refreshAll, { flush: 'post' });
 
 const slots: SetupContext['slots'] = useSlots();
 const headerSlots = computed(() => {

From 19b2d7af419d68e59458d30aa0ff5e2646eaf8af Mon Sep 17 00:00:00 2001
From: ppxb <317842449@qq.com>
Date: Sat, 10 Jan 2026 14:11:08 +0800
Subject: [PATCH 05/10] fix: tdesign theme toggle and demos (#7087)

---
 apps/web-tdesign/src/app.vue                      | 15 ++++++++-------
 .../web-tdesign/src/views/demos/tdesign/index.vue |  6 +++---
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/apps/web-tdesign/src/app.vue b/apps/web-tdesign/src/app.vue
index f37688b67..f2fa88408 100644
--- a/apps/web-tdesign/src/app.vue
+++ b/apps/web-tdesign/src/app.vue
@@ -1,7 +1,7 @@
 <script lang="ts" setup>
 import type { GlobalConfigProvider } from 'tdesign-vue-next';
 
-import { onMounted } from 'vue';
+import { watch } from 'vue';
 
 import { usePreferences } from '@vben/preferences';
 
@@ -12,12 +12,13 @@ import zhConfig from 'tdesign-vue-next/es/locale/zh_CN';
 defineOptions({ name: 'App' });
 const { isDark } = usePreferences();
 
-onMounted(() => {
-  document.documentElement.setAttribute(
-    'theme-mode',
-    isDark.value ? 'dark' : '',
-  );
-});
+watch(
+  () => isDark.value,
+  (dark) => {
+    document.documentElement.setAttribute('theme-mode', dark ? 'dark' : '');
+  },
+  { immediate: true },
+);
 
 const customConfig: GlobalConfigProvider = {
   // 可以在此处定义更多自定义配置，具体可配置内容参看 API 文档
diff --git a/apps/web-tdesign/src/views/demos/tdesign/index.vue b/apps/web-tdesign/src/views/demos/tdesign/index.vue
index f44f96e50..27299dea5 100644
--- a/apps/web-tdesign/src/views/demos/tdesign/index.vue
+++ b/apps/web-tdesign/src/views/demos/tdesign/index.vue
@@ -38,7 +38,7 @@ function notify(type: NotificationType) {
     description="支持多语言，主题功能集成切换等"
     title="TDesign Vue组件使用演示"
   >
-    <Card class="mb-5" title="按钮">
+    <Card class="!mb-5" title="按钮">
       <Space>
         <Button>Default</Button>
         <Button theme="primary"> Primary </Button>
@@ -46,7 +46,7 @@ function notify(type: NotificationType) {
         <Button theme="danger"> Error </Button>
       </Space>
     </Card>
-    <Card class="mb-5" title="Message">
+    <Card class="!mb-5" title="Message">
       <Space>
         <Button @click="info"> 信息 </Button>
         <Button theme="danger" @click="error"> 错误 </Button>
@@ -55,7 +55,7 @@ function notify(type: NotificationType) {
       </Space>
     </Card>
 
-    <Card class="mb-5" title="Notification">
+    <Card class="!mb-5" title="Notification">
       <Space>
         <Button @click="notify('info')"> 信息 </Button>
         <Button theme="danger" @click="notify('error')"> 错误 </Button>

From f4a4ced88d4aa11ef6dd1bb4d6b3dbb37e052373 Mon Sep 17 00:00:00 2001
From: ppxb <317842449@qq.com>
Date: Mon, 12 Jan 2026 21:40:26 +0800
Subject: [PATCH 06/10] fix: header auto mode issue (#7096)

---
 .../@core/ui-kit/layout-ui/src/vben-layout.vue  | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/packages/@core/ui-kit/layout-ui/src/vben-layout.vue b/packages/@core/ui-kit/layout-ui/src/vben-layout.vue
index bf7d7753f..a35ed349c 100644
--- a/packages/@core/ui-kit/layout-ui/src/vben-layout.vue
+++ b/packages/@core/ui-kit/layout-ui/src/vben-layout.vue
@@ -403,13 +403,10 @@ watch(
 );
 
 {
-  const mouseMove = () => {
-    mouseY.value > headerWrapperHeight.value
-      ? (headerIsHidden.value = true)
-      : (headerIsHidden.value = false);
-  };
+  const HEADER_TRIGGER_DISTANCE = 12;
+
   watch(
-    [() => props.headerMode, () => mouseY.value],
+    [() => props.headerMode, () => mouseY.value, () => headerIsHidden.value],
     () => {
       if (!isHeaderAutoMode.value || isMixedNav.value || isFullContent.value) {
         if (props.headerMode !== 'auto-scroll') {
@@ -417,8 +414,12 @@ watch(
         }
         return;
       }
-      headerIsHidden.value = true;
-      mouseMove();
+
+      const isInTriggerZone = mouseY.value <= HEADER_TRIGGER_DISTANCE;
+      const isInHeaderZone =
+        !headerIsHidden.value && mouseY.value <= headerWrapperHeight.value;
+
+      headerIsHidden.value = !(isInTriggerZone || isInHeaderZone);
     },
     {
       immediate: true,

From 67da9417a822e885417e58668f49b7d552cddf48 Mon Sep 17 00:00:00 2001
From: JyQAQ <45193678+jyqwq@users.noreply.github.com>
Date: Wed, 14 Jan 2026 15:38:05 +0800
Subject: [PATCH 07/10] =?UTF-8?q?feat(upload=20prop:crop,aspectRatio):=20f?=
 =?UTF-8?q?rom=20Upload=20component=20accept=20prop=E2=80=A6=20(#7095)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(upload prop:crop,aspectRatio): from Upload component accept prop crop,aspectRatio

* feat(upload prop:crop,aspectRatio): from Upload component accept prop crop,aspectRatio

* feat(upload prop:crop,aspectRatio): from Upload component accept prop crop,aspectRatio

* feat(upload prop:crop,aspectRatio): from Upload component accept prop crop,aspectRatio
---
 apps/web-antd/src/adapter/component/index.ts  | 228 ++++++++++++++----
 packages/locales/src/langs/en-US/ui.json      |   6 +
 packages/locales/src/langs/zh-CN/ui.json      |   6 +
 playground/src/adapter/component/index.ts     | 194 ++++++++++++---
 .../src/locales/langs/en-US/examples.json     |   1 +
 .../src/locales/langs/zh-CN/examples.json     |   1 +
 playground/src/views/examples/form/basic.vue  |  40 +++
 7 files changed, 391 insertions(+), 85 deletions(-)

diff --git a/apps/web-antd/src/adapter/component/index.ts b/apps/web-antd/src/adapter/component/index.ts
index 34c821cb5..0f002700d 100644
--- a/apps/web-antd/src/adapter/component/index.ts
+++ b/apps/web-antd/src/adapter/component/index.ts
@@ -26,12 +26,17 @@ import {
   watch,
 } from 'vue';
 
-import { ApiComponent, globalShareState, IconPicker } from '@vben/common-ui';
+import {
+  ApiComponent,
+  globalShareState,
+  IconPicker,
+  VCropper,
+} from '@vben/common-ui';
 import { IconifyIcon } from '@vben/icons';
 import { $t } from '@vben/locales';
 import { isEmpty } from '@vben/utils';
 
-import { message, notification } from 'ant-design-vue';
+import { message, Modal, notification } from 'ant-design-vue';
 
 const AutoComplete = defineAsyncComponent(
   () => import('ant-design-vue/es/auto-complete'),
@@ -121,6 +126,33 @@ const withDefaultPlaceholder = <T extends Component>(
 };
 
 const withPreviewUpload = () => {
+  // 检查是否为图片文件的辅助函数
+  const isImageFile = (file: UploadFile): boolean => {
+    const imageExtensions = new Set([
+      'bmp',
+      'gif',
+      'jpeg',
+      'jpg',
+      'png',
+      'svg',
+      'webp',
+    ]);
+    if (file.url) {
+      try {
+        const pathname = new URL(file.url, 'http://localhost').pathname;
+        const ext = pathname.split('.').pop()?.toLowerCase();
+        return ext ? imageExtensions.has(ext) : false;
+      } catch {
+        const ext = file.url?.split('.').pop()?.toLowerCase();
+        return ext ? imageExtensions.has(ext) : false;
+      }
+    }
+    if (!file.type) {
+      const ext = file.name?.split('.').pop()?.toLowerCase();
+      return ext ? imageExtensions.has(ext) : false;
+    }
+    return file.type.startsWith('image/');
+  };
   // 创建默认的上传按钮插槽
   const createDefaultSlotsWithUpload = (
     listType: string,
@@ -155,27 +187,6 @@ const withPreviewUpload = () => {
     visible: Ref<boolean>,
     fileList: Ref<UploadProps['fileList']>,
   ) => {
-    // 检查是否为图片文件的辅助函数
-    const isImageFile = (file: UploadFile): boolean => {
-      const imageExtensions = new Set([
-        'bmp',
-        'gif',
-        'jpeg',
-        'jpg',
-        'png',
-        'webp',
-      ]);
-      if (file.url) {
-        const ext = file.url?.split('.').pop()?.toLowerCase();
-        return ext ? imageExtensions.has(ext) : false;
-      }
-      if (!file.type) {
-        const ext = file.name?.split('.').pop()?.toLowerCase();
-        return ext ? imageExtensions.has(ext) : false;
-      }
-      return file.type.startsWith('image/');
-    };
-
     // 如果当前文件不是图片，直接打开
     if (!isImageFile(file)) {
       if (file.url) {
@@ -261,6 +272,107 @@ const withPreviewUpload = () => {
 
     render(h(PreviewWrapper), container);
   };
+
+  // 图片裁剪操作
+  const cropImage = (file: File, aspectRatio: string | undefined) => {
+    return new Promise((resolve, reject) => {
+      const container: HTMLElement | null = document.createElement('div');
+      document.body.append(container);
+
+      // 用于追踪组件是否已卸载
+      let isUnmounted = false;
+      let objectUrl: null | string = null;
+
+      const open = ref<boolean>(true);
+      const cropperRef = ref<InstanceType<typeof VCropper> | null>(null);
+
+      const closeModal = () => {
+        open.value = false;
+        // 延迟清理，确保动画完成
+        setTimeout(() => {
+          if (!isUnmounted && container) {
+            if (objectUrl) {
+              URL.revokeObjectURL(objectUrl);
+            }
+            isUnmounted = true;
+            render(null, container);
+            container.remove();
+          }
+        }, 300);
+      };
+
+      const CropperWrapper = {
+        setup() {
+          return () => {
+            if (isUnmounted) return null;
+            if (!objectUrl) {
+              objectUrl = URL.createObjectURL(file);
+            }
+            return h(
+              Modal,
+              {
+                open: open.value,
+                title: $t('ui.crop.title'),
+                centered: true,
+                width: 548,
+                keyboard: false,
+                maskClosable: false,
+                closable: false,
+                cancelText: $t('common.cancel'),
+                okText: $t('ui.crop.confirm'),
+                destroyOnClose: true,
+                onOk: async () => {
+                  const cropper = cropperRef.value;
+                  if (!cropper) {
+                    reject(new Error('Cropper not found'));
+                    closeModal();
+                    return;
+                  }
+                  try {
+                    const dataUrl = await cropper.getCropImage();
+                    resolve(dataUrl);
+                  } catch {
+                    reject(new Error($t('ui.crop.errorTip')));
+                  } finally {
+                    closeModal();
+                  }
+                },
+                onCancel() {
+                  resolve('');
+                  closeModal();
+                },
+              },
+              () =>
+                h(VCropper, {
+                  ref: (ref: any) => (cropperRef.value = ref),
+                  img: objectUrl as string,
+                  aspectRatio,
+                }),
+            );
+          };
+        },
+      };
+
+      render(h(CropperWrapper), container);
+    });
+  };
+
+  const base64ToBlob = (base64: Base64URLString) => {
+    try {
+      const [typeStr, encodeStr] = base64.split(',');
+      if (!typeStr || !encodeStr) return;
+      const mime = typeStr.match(/:(.*?);/)?.[1];
+      const raw = window.atob(encodeStr);
+      const rawLength = raw.length;
+      const uInt8Array = new Uint8Array(rawLength);
+      for (let i = 0; i < rawLength; ++i) {
+        uInt8Array[i] = raw.codePointAt(i) as number;
+      }
+      return new Blob([uInt8Array], { type: mime });
+    } catch {
+      return undefined;
+    }
+  };
   return defineComponent({
     name: Upload.name,
     emits: ['update:modelValue'],
@@ -278,12 +390,37 @@ const withPreviewUpload = () => {
         attrs?.fileList || attrs?.['file-list'] || [],
       );
 
-      const handleBeforeUpload = (file: UploadFile) => {
+      const handleBeforeUpload = async (
+        file: UploadFile,
+        originFileList: Array<File>,
+      ) => {
         if (attrs.maxSize && (file.size || 0) / 1024 / 1024 > attrs.maxSize) {
           message.error($t('ui.formRules.sizeLimit', [attrs.maxSize]));
           file.status = 'removed';
           return false;
         }
+        // 多选或者非图片不唤起裁剪框
+        if (
+          attrs.crop &&
+          !attrs.multiple &&
+          originFileList[0] &&
+          isImageFile(file)
+        ) {
+          file.status = 'removed';
+          // antd Upload组件问题 file参数获取的是UploadFile类型对象无法取到File类型 所以通过originFileList[0]获取
+          const base64 = await cropImage(originFileList[0], attrs.aspectRatio);
+          return new Promise((resolve, reject) => {
+            if (!base64) {
+              return reject(new Error($t('ui.crop.cancel')));
+            }
+            const blob = base64ToBlob(base64 as string);
+            if (!blob) {
+              return reject(new Error($t('ui.crop.errorTip')));
+            }
+            resolve(blob);
+          });
+        }
+
         return attrs.beforeUpload?.(file) ?? true;
       };
 
@@ -377,6 +514,7 @@ async function initComponentAdapter() {
     // 如果你的组件体积比较大，可以使用异步加载
     // Button: () =>
     // import('xxx').then((res) => res.Button),
+
     ApiCascader: withDefaultPlaceholder(ApiComponent, 'select', {
       component: Cascader,
       fieldNames: { label: 'label', value: 'value', children: 'children' },
@@ -384,34 +522,20 @@ async function initComponentAdapter() {
       modelPropName: 'value',
       visibleEvent: 'onVisibleChange',
     }),
-    ApiSelect: withDefaultPlaceholder(
-      {
-        ...ApiComponent,
-        name: 'ApiSelect',
-      },
-      'select',
-      {
-        component: Select,
-        loadingSlot: 'suffixIcon',
-        visibleEvent: 'onDropdownVisibleChange',
-        modelPropName: 'value',
-      },
-    ),
-    ApiTreeSelect: withDefaultPlaceholder(
-      {
-        ...ApiComponent,
-        name: 'ApiTreeSelect',
-      },
-      'select',
-      {
-        component: TreeSelect,
-        fieldNames: { label: 'label', value: 'value', children: 'children' },
-        loadingSlot: 'suffixIcon',
-        modelPropName: 'value',
-        optionsPropName: 'treeData',
-        visibleEvent: 'onVisibleChange',
-      },
-    ),
+    ApiSelect: withDefaultPlaceholder(ApiComponent, 'select', {
+      component: Select,
+      loadingSlot: 'suffixIcon',
+      modelPropName: 'value',
+      visibleEvent: 'onVisibleChange',
+    }),
+    ApiTreeSelect: withDefaultPlaceholder(ApiComponent, 'select', {
+      component: TreeSelect,
+      fieldNames: { label: 'label', value: 'value', children: 'children' },
+      loadingSlot: 'suffixIcon',
+      modelPropName: 'value',
+      optionsPropName: 'treeData',
+      visibleEvent: 'onVisibleChange',
+    }),
     AutoComplete,
     Cascader,
     Checkbox,
diff --git a/packages/locales/src/langs/en-US/ui.json b/packages/locales/src/langs/en-US/ui.json
index f5166cdfa..fbba093a6 100644
--- a/packages/locales/src/langs/en-US/ui.json
+++ b/packages/locales/src/langs/en-US/ui.json
@@ -54,6 +54,12 @@
     "copy": "Copy",
     "copied": "Copied"
   },
+  "crop": {
+    "title": "Image Cropping",
+    "confirm": "Crop",
+    "cancel": "Cancel cropping",
+    "errorTip": "Cropping error"
+  },
   "fallback": {
     "pageNotFound": "Oops! Page Not Found",
     "pageNotFoundDesc": "Sorry, we couldn't find the page you were looking for.",
diff --git a/packages/locales/src/langs/zh-CN/ui.json b/packages/locales/src/langs/zh-CN/ui.json
index 460931898..173fa516f 100644
--- a/packages/locales/src/langs/zh-CN/ui.json
+++ b/packages/locales/src/langs/zh-CN/ui.json
@@ -54,6 +54,12 @@
     "copy": "复制",
     "copied": "已复制"
   },
+  "crop": {
+    "title": "图片裁剪",
+    "confirm": "裁剪",
+    "cancel": "取消裁剪",
+    "errorTip": "裁剪错误"
+  },
   "fallback": {
     "pageNotFound": "哎呀！未找到页面",
     "pageNotFoundDesc": "抱歉，我们无法找到您要找的页面。",
diff --git a/playground/src/adapter/component/index.ts b/playground/src/adapter/component/index.ts
index 48ce2fcc8..0f002700d 100644
--- a/playground/src/adapter/component/index.ts
+++ b/playground/src/adapter/component/index.ts
@@ -26,12 +26,17 @@ import {
   watch,
 } from 'vue';
 
-import { ApiComponent, globalShareState, IconPicker } from '@vben/common-ui';
+import {
+  ApiComponent,
+  globalShareState,
+  IconPicker,
+  VCropper,
+} from '@vben/common-ui';
 import { IconifyIcon } from '@vben/icons';
 import { $t } from '@vben/locales';
 import { isEmpty } from '@vben/utils';
 
-import { message, notification } from 'ant-design-vue';
+import { message, Modal, notification } from 'ant-design-vue';
 
 const AutoComplete = defineAsyncComponent(
   () => import('ant-design-vue/es/auto-complete'),
@@ -101,7 +106,6 @@ const withDefaultPlaceholder = <T extends Component>(
         $t(`ui.placeholder.${type}`);
       // 透传组件暴露的方法
       const innerRef = ref();
-      // const publicApi: Recordable<any> = {};
       expose(
         new Proxy(
           {},
@@ -111,14 +115,6 @@ const withDefaultPlaceholder = <T extends Component>(
           },
         ),
       );
-      // const instance = getCurrentInstance();
-      // instance?.proxy?.$nextTick(() => {
-      //   for (const key in innerRef.value) {
-      //     if (typeof innerRef.value[key] === 'function') {
-      //       publicApi[key] = innerRef.value[key];
-      //     }
-      //   }
-      // });
       return () =>
         h(
           component,
@@ -130,6 +126,33 @@ const withDefaultPlaceholder = <T extends Component>(
 };
 
 const withPreviewUpload = () => {
+  // 检查是否为图片文件的辅助函数
+  const isImageFile = (file: UploadFile): boolean => {
+    const imageExtensions = new Set([
+      'bmp',
+      'gif',
+      'jpeg',
+      'jpg',
+      'png',
+      'svg',
+      'webp',
+    ]);
+    if (file.url) {
+      try {
+        const pathname = new URL(file.url, 'http://localhost').pathname;
+        const ext = pathname.split('.').pop()?.toLowerCase();
+        return ext ? imageExtensions.has(ext) : false;
+      } catch {
+        const ext = file.url?.split('.').pop()?.toLowerCase();
+        return ext ? imageExtensions.has(ext) : false;
+      }
+    }
+    if (!file.type) {
+      const ext = file.name?.split('.').pop()?.toLowerCase();
+      return ext ? imageExtensions.has(ext) : false;
+    }
+    return file.type.startsWith('image/');
+  };
   // 创建默认的上传按钮插槽
   const createDefaultSlotsWithUpload = (
     listType: string,
@@ -164,27 +187,6 @@ const withPreviewUpload = () => {
     visible: Ref<boolean>,
     fileList: Ref<UploadProps['fileList']>,
   ) => {
-    // 检查是否为图片文件的辅助函数
-    const isImageFile = (file: UploadFile): boolean => {
-      const imageExtensions = new Set([
-        'bmp',
-        'gif',
-        'jpeg',
-        'jpg',
-        'png',
-        'webp',
-      ]);
-      if (file.url) {
-        const ext = file.url?.split('.').pop()?.toLowerCase();
-        return ext ? imageExtensions.has(ext) : false;
-      }
-      if (!file.type) {
-        const ext = file.name?.split('.').pop()?.toLowerCase();
-        return ext ? imageExtensions.has(ext) : false;
-      }
-      return file.type.startsWith('image/');
-    };
-
     // 如果当前文件不是图片，直接打开
     if (!isImageFile(file)) {
       if (file.url) {
@@ -270,6 +272,107 @@ const withPreviewUpload = () => {
 
     render(h(PreviewWrapper), container);
   };
+
+  // 图片裁剪操作
+  const cropImage = (file: File, aspectRatio: string | undefined) => {
+    return new Promise((resolve, reject) => {
+      const container: HTMLElement | null = document.createElement('div');
+      document.body.append(container);
+
+      // 用于追踪组件是否已卸载
+      let isUnmounted = false;
+      let objectUrl: null | string = null;
+
+      const open = ref<boolean>(true);
+      const cropperRef = ref<InstanceType<typeof VCropper> | null>(null);
+
+      const closeModal = () => {
+        open.value = false;
+        // 延迟清理，确保动画完成
+        setTimeout(() => {
+          if (!isUnmounted && container) {
+            if (objectUrl) {
+              URL.revokeObjectURL(objectUrl);
+            }
+            isUnmounted = true;
+            render(null, container);
+            container.remove();
+          }
+        }, 300);
+      };
+
+      const CropperWrapper = {
+        setup() {
+          return () => {
+            if (isUnmounted) return null;
+            if (!objectUrl) {
+              objectUrl = URL.createObjectURL(file);
+            }
+            return h(
+              Modal,
+              {
+                open: open.value,
+                title: $t('ui.crop.title'),
+                centered: true,
+                width: 548,
+                keyboard: false,
+                maskClosable: false,
+                closable: false,
+                cancelText: $t('common.cancel'),
+                okText: $t('ui.crop.confirm'),
+                destroyOnClose: true,
+                onOk: async () => {
+                  const cropper = cropperRef.value;
+                  if (!cropper) {
+                    reject(new Error('Cropper not found'));
+                    closeModal();
+                    return;
+                  }
+                  try {
+                    const dataUrl = await cropper.getCropImage();
+                    resolve(dataUrl);
+                  } catch {
+                    reject(new Error($t('ui.crop.errorTip')));
+                  } finally {
+                    closeModal();
+                  }
+                },
+                onCancel() {
+                  resolve('');
+                  closeModal();
+                },
+              },
+              () =>
+                h(VCropper, {
+                  ref: (ref: any) => (cropperRef.value = ref),
+                  img: objectUrl as string,
+                  aspectRatio,
+                }),
+            );
+          };
+        },
+      };
+
+      render(h(CropperWrapper), container);
+    });
+  };
+
+  const base64ToBlob = (base64: Base64URLString) => {
+    try {
+      const [typeStr, encodeStr] = base64.split(',');
+      if (!typeStr || !encodeStr) return;
+      const mime = typeStr.match(/:(.*?);/)?.[1];
+      const raw = window.atob(encodeStr);
+      const rawLength = raw.length;
+      const uInt8Array = new Uint8Array(rawLength);
+      for (let i = 0; i < rawLength; ++i) {
+        uInt8Array[i] = raw.codePointAt(i) as number;
+      }
+      return new Blob([uInt8Array], { type: mime });
+    } catch {
+      return undefined;
+    }
+  };
   return defineComponent({
     name: Upload.name,
     emits: ['update:modelValue'],
@@ -287,12 +390,37 @@ const withPreviewUpload = () => {
         attrs?.fileList || attrs?.['file-list'] || [],
       );
 
-      const handleBeforeUpload = (file: UploadFile) => {
+      const handleBeforeUpload = async (
+        file: UploadFile,
+        originFileList: Array<File>,
+      ) => {
         if (attrs.maxSize && (file.size || 0) / 1024 / 1024 > attrs.maxSize) {
           message.error($t('ui.formRules.sizeLimit', [attrs.maxSize]));
           file.status = 'removed';
           return false;
         }
+        // 多选或者非图片不唤起裁剪框
+        if (
+          attrs.crop &&
+          !attrs.multiple &&
+          originFileList[0] &&
+          isImageFile(file)
+        ) {
+          file.status = 'removed';
+          // antd Upload组件问题 file参数获取的是UploadFile类型对象无法取到File类型 所以通过originFileList[0]获取
+          const base64 = await cropImage(originFileList[0], attrs.aspectRatio);
+          return new Promise((resolve, reject) => {
+            if (!base64) {
+              return reject(new Error($t('ui.crop.cancel')));
+            }
+            const blob = base64ToBlob(base64 as string);
+            if (!blob) {
+              return reject(new Error($t('ui.crop.errorTip')));
+            }
+            resolve(blob);
+          });
+        }
+
         return attrs.beforeUpload?.(file) ?? true;
       };
 
diff --git a/playground/src/locales/langs/en-US/examples.json b/playground/src/locales/langs/en-US/examples.json
index 958b0c83f..05035487f 100644
--- a/playground/src/locales/langs/en-US/examples.json
+++ b/playground/src/locales/langs/en-US/examples.json
@@ -23,6 +23,7 @@
     "upload-error": "Partial file upload failed",
     "upload-urls": "Urls after file upload",
     "file": "file",
+    "crop-image": "Crop image",
     "upload-image": "Click to upload image"
   },
   "vxeTable": {
diff --git a/playground/src/locales/langs/zh-CN/examples.json b/playground/src/locales/langs/zh-CN/examples.json
index 3de48e214..3b0d934cf 100644
--- a/playground/src/locales/langs/zh-CN/examples.json
+++ b/playground/src/locales/langs/zh-CN/examples.json
@@ -26,6 +26,7 @@
     "upload-error": "部分文件上传失败",
     "upload-urls": "文件上传后的网址",
     "file": "文件",
+    "crop-image": "裁剪图片",
     "upload-image": "点击上传图片"
   },
   "vxeTable": {
diff --git a/playground/src/views/examples/form/basic.vue b/playground/src/views/examples/form/basic.vue
index 7cb085227..40f5930d5 100644
--- a/playground/src/views/examples/form/basic.vue
+++ b/playground/src/views/examples/form/basic.vue
@@ -358,6 +358,28 @@ const [BaseForm, baseFormApi] = useVbenForm({
       },
       rules: 'selectRequired',
     },
+    {
+      component: 'Upload',
+      componentProps: {
+        accept: '.png,.jpg,.jpeg',
+        customRequest: upload_file,
+        maxCount: 1,
+        maxSize: 2,
+        listType: 'picture-card',
+        // 是否启用图片裁剪(多选或者非图片不唤起裁剪框)
+        crop: true,
+        // 裁剪比例
+        aspectRatio: '1:1',
+      },
+      fieldName: 'cropImage',
+      label: $t('examples.form.crop-image'),
+      renderComponentContent: () => {
+        return {
+          default: () => $t('examples.form.upload-image'),
+        };
+      },
+      rules: 'selectRequired',
+    },
   ],
   // 大屏一行显示3个，中屏一行显示2个，小屏一行显示1个
   wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
@@ -365,13 +387,20 @@ const [BaseForm, baseFormApi] = useVbenForm({
 
 function onSubmit(values: Record<string, any>) {
   const files = toRaw(values.files) as UploadFile[];
+  const cropImage = (toRaw(values.cropImage) ?? []) as UploadFile[];
   const doneFiles = files.filter((file) => file.status === 'done');
   const failedFiles = files.filter((file) => file.status !== 'done');
+  const doneCrop = cropImage.filter((file) => file.status === 'done');
+  const failedCrop = cropImage.filter((file) => file.status !== 'done');
 
   const msg = [
     ...doneFiles.map((file) => file.response?.url || file.url),
     ...failedFiles.map((file) => file.name),
   ].join(', ');
+  const msgCrop = [
+    ...doneCrop.map((file) => file.response?.url || file.url),
+    ...failedCrop.map((file) => file.name),
+  ].join(', ');
 
   if (failedFiles.length === 0) {
     message.success({
@@ -383,8 +412,19 @@ function onSubmit(values: Record<string, any>) {
     });
     return;
   }
+  if (doneCrop.length > 0 && failedCrop.length === 0) {
+    message.success({
+      content: `${$t('examples.form.upload-urls')}: ${msgCrop}`,
+    });
+  } else if (failedCrop.length > 0) {
+    message.error({
+      content: `${$t('examples.form.upload-error')}: ${msgCrop}`,
+    });
+    return;
+  }
   // 如果需要可提交前替换为需要的urls
   values.files = doneFiles.map((file) => file.response?.url || file.url);
+  values.cropImage = doneCrop.map((file) => file.response?.url || file.url);
   message.success({
     content: `form values: ${JSON.stringify(values)}`,
   });

From 174c4ae7499d7e6217b03557e194a36722fe3cc1 Mon Sep 17 00:00:00 2001
From: JyQAQ <45193678+jyqwq@users.noreply.github.com>
Date: Wed, 14 Jan 2026 15:38:21 +0800
Subject: [PATCH 08/10] =?UTF-8?q?fix(antd=20Upload=20onChange=20Event):=20?=
 =?UTF-8?q?rewrite=20onChange=20event=20to=20handle=20upl=E2=80=A6=20(#709?=
 =?UTF-8?q?8)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(antd Upload onChange Event): rewrite onChange event to handle upload success or error messages

* fix(antd Upload onChange Event): rewrite onChange event to handle upload success or error messages

* fix(antd Upload onChange Event): rewrite onChange event to handle upload success or error messages
---
 apps/web-antd/src/adapter/component/index.ts | 11 ++++++++++-
 playground/src/adapter/component/index.ts    | 11 ++++++++++-
 playground/src/views/examples/form/basic.vue |  9 +++++++++
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/apps/web-antd/src/adapter/component/index.ts b/apps/web-antd/src/adapter/component/index.ts
index 0f002700d..f319ad1da 100644
--- a/apps/web-antd/src/adapter/component/index.ts
+++ b/apps/web-antd/src/adapter/component/index.ts
@@ -424,7 +424,16 @@ const withPreviewUpload = () => {
         return attrs.beforeUpload?.(file) ?? true;
       };
 
-      const handleChange = async (event: UploadChangeParam) => {
+      const handleChange = (event: UploadChangeParam) => {
+        try {
+          // 行内写法 handleChange: (event) => {}
+          attrs.handleChange?.(event);
+          // template写法 @handle-change="(event) => {}"
+          attrs.onHandleChange?.(event);
+        } catch (error) {
+          // Avoid breaking internal v-model sync on user handler errors
+          console.error(error);
+        }
         fileList.value = event.fileList.filter(
           (file) => file.status !== 'removed',
         );
diff --git a/playground/src/adapter/component/index.ts b/playground/src/adapter/component/index.ts
index 0f002700d..f319ad1da 100644
--- a/playground/src/adapter/component/index.ts
+++ b/playground/src/adapter/component/index.ts
@@ -424,7 +424,16 @@ const withPreviewUpload = () => {
         return attrs.beforeUpload?.(file) ?? true;
       };
 
-      const handleChange = async (event: UploadChangeParam) => {
+      const handleChange = (event: UploadChangeParam) => {
+        try {
+          // 行内写法 handleChange: (event) => {}
+          attrs.handleChange?.(event);
+          // template写法 @handle-change="(event) => {}"
+          attrs.onHandleChange?.(event);
+        } catch (error) {
+          // Avoid breaking internal v-model sync on user handler errors
+          console.error(error);
+        }
         fileList.value = event.fileList.filter(
           (file) => file.status !== 'removed',
         );
diff --git a/playground/src/views/examples/form/basic.vue b/playground/src/views/examples/form/basic.vue
index 40f5930d5..52d04319f 100644
--- a/playground/src/views/examples/form/basic.vue
+++ b/playground/src/views/examples/form/basic.vue
@@ -348,6 +348,15 @@ const [BaseForm, baseFormApi] = useVbenForm({
         showUploadList: true,
         // 上传列表的内建样式，支持四种基本样式 text, picture, picture-card 和 picture-circle
         listType: 'picture-card',
+        // onChange事件已被重写，如需自定义请在此基础上扩展
+        handleChange: ({ file }: { file: UploadFile }) => {
+          const { name, status } = file;
+          if (status === 'done') {
+            message.success(`${name} ${$t('examples.form.upload-success')}`);
+          } else if (status === 'error') {
+            message.error(`${name} ${$t('examples.form.upload-fail')}`);
+          }
+        },
       },
       fieldName: 'files',
       label: $t('examples.form.file'),

From 8a7e2bd8e4756516a192252bf68972dedd7c38d0 Mon Sep 17 00:00:00 2001
From: MRSWC <1628875709@qq.com>
Date: Wed, 14 Jan 2026 15:38:55 +0800
Subject: [PATCH 09/10] =?UTF-8?q?fix:=E4=BF=AE=E5=A4=8D=E9=BB=98=E8=AE=A4?=
 =?UTF-8?q?=E9=BB=98=E8=AE=A4=E9=A6=96=E9=A1=B5=E5=A6=82=E6=9E=9C=E6=90=BA?=
 =?UTF-8?q?=E5=B8=A6=E5=8F=82=E6=95=B0=E6=97=B6=E5=88=B7=E6=96=B0=E9=A1=B5?=
 =?UTF-8?q?=E9=9D=A2=E5=8F=82=E6=95=B0=E4=B8=A2=E5=A4=B1=E9=97=AE=E9=A2=98?=
 =?UTF-8?q?=20(#7102)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: chenwei <chenw@jiuzhekan.com>
---
 playground/src/router/guard.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/playground/src/router/guard.ts b/playground/src/router/guard.ts
index 514bd2eb6..167a84d10 100644
--- a/playground/src/router/guard.ts
+++ b/playground/src/router/guard.ts
@@ -108,9 +108,9 @@ function setupAccessGuard(router: Router) {
     let redirectPath: string;
     if (from.query.redirect) {
       redirectPath = from.query.redirect as string;
-    } else if (to.path === preferences.app.defaultHomePath) {
+    } else if (to.fullPath === preferences.app.defaultHomePath) {
       redirectPath = preferences.app.defaultHomePath;
-    } else if (userInfo.homePath && to.path === userInfo.homePath) {
+    } else if (userInfo.homePath && to.fullPath === userInfo.homePath) {
       redirectPath = userInfo.homePath;
     } else {
       redirectPath = to.fullPath;

From 686c3f9208ccc3dd14014a2903fb35cd53e0ab6e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=A9=99=E5=AD=90?=
 <126167116+caodachen@users.noreply.github.com>
Date: Wed, 14 Jan 2026 19:36:45 +0800
Subject: [PATCH 10/10] docs(@vben-core/preferences): update comments (#7107)

---
 packages/@core/preferences/src/use-preferences.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/@core/preferences/src/use-preferences.ts b/packages/@core/preferences/src/use-preferences.ts
index d931f7582..0507d9617 100644
--- a/packages/@core/preferences/src/use-preferences.ts
+++ b/packages/@core/preferences/src/use-preferences.ts
@@ -136,7 +136,7 @@ function usePreferences() {
   });
 
   /**
-   * @zh_CN 登录注册页面布局是否为左侧
+   * @zh_CN 登录注册页面布局是否为右侧
    */
   const authPanelRight = computed(() => {
     return appPreferences.value.authPageLayout === 'panel-right';