From 2a84b590b5e54631b145ccc7269a60fa04a2a43b Mon Sep 17 00:00:00 2001
From: PanFu <panfuy@hotmail.com>
Date: Wed, 20 May 2026 17:24:53 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E5=81=8F=E5=A5=BD=E8=AE=BE=E7=BD=AE?=
 =?UTF-8?q?=E6=8C=89=E9=92=AE=EF=BC=8C=E6=94=AF=E6=8C=81=E5=9C=A8=E5=8F=B3?=
 =?UTF-8?q?=E4=B8=8A=E8=A7=92=E7=94=A8=E6=88=B7=E7=9A=84=E4=B8=8B=E6=8B=89?=
 =?UTF-8?q?=E6=A1=86=E4=B8=AD=E5=B1=95=E7=A4=BA=EF=BC=9B=E5=81=8F=E5=A5=BD?=
 =?UTF-8?q?=E8=AE=BE=E7=BD=AE=E4=B8=AD=E6=94=AF=E6=8C=81=E8=AE=BE=E7=BD=AE?=
 =?UTF-8?q?=E6=97=B6=E5=8C=BA=EF=BC=88=E5=A4=9A=E4=B8=80=E4=B8=AA=E5=85=A5?=
 =?UTF-8?q?=E5=8F=A3=EF=BC=89=EF=BC=9B=20(#7931)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat: 偏好设置按钮支持显示在用户下拉窗中的特性

* feat: 时区设置功能支持在偏好设置列表进行配置

* feat: 偏好设置按钮支持显示在用户下拉窗中的特性 - 完善示例代码

* feat: 时区设置功能支持在偏好设置列表进行配置

* feat: 时区设置功能支持在偏好设置列表进行配置-单元测试报错问题

* feat: 时区设置功能支持在偏好设置列表进行配置-修改代码QC问题

---------

Co-authored-by: PanFu <panfu@zhihuaai.com>
---
 apps/web-antd/src/layouts/basic.vue           |  1 +
 apps/web-antdv-next/src/layouts/basic.vue     |  1 +
 apps/web-ele/src/layouts/basic.vue            |  1 +
 apps/web-naive/src/layouts/basic.vue          |  1 +
 apps/web-tdesign/src/layouts/basic.vue        |  1 +
 packages/@core/base/typings/src/app.d.ts      |  9 +++-
 .../__snapshots__/config.test.ts.snap         |  1 +
 packages/@core/preferences/src/config.ts      |  1 +
 packages/@core/preferences/src/types.ts       |  4 ++
 .../@core/preferences/src/use-preferences.ts  |  6 ++-
 .../preferences/blocks/general/general.vue    | 24 +++++++++++
 .../preferences/blocks/layout/widget.vue      |  4 ++
 .../preferences/preferences-drawer.vue        |  2 +
 .../src/widgets/preferences/preferences.vue   | 43 ++++++++++++++-----
 .../widgets/user-dropdown/user-dropdown.vue   | 33 ++++++++++++--
 .../locales/src/langs/en-US/preferences.json  |  4 +-
 .../locales/src/langs/zh-CN/preferences.json  |  4 +-
 playground/src/layouts/basic.vue              |  1 +
 18 files changed, 121 insertions(+), 20 deletions(-)

diff --git a/apps/web-antd/src/layouts/basic.vue b/apps/web-antd/src/layouts/basic.vue
index 1bb07ec8f..c938f09cd 100644
--- a/apps/web-antd/src/layouts/basic.vue
+++ b/apps/web-antd/src/layouts/basic.vue
@@ -226,6 +226,7 @@ watch(
         description="ann.vben@gmail.com"
         tag-text="Pro"
         @logout="handleLogout"
+        @clear-preferences-and-logout="handleLogout"
       />
     </template>
     <template #notification>
diff --git a/apps/web-antdv-next/src/layouts/basic.vue b/apps/web-antdv-next/src/layouts/basic.vue
index 1bb07ec8f..c938f09cd 100644
--- a/apps/web-antdv-next/src/layouts/basic.vue
+++ b/apps/web-antdv-next/src/layouts/basic.vue
@@ -226,6 +226,7 @@ watch(
         description="ann.vben@gmail.com"
         tag-text="Pro"
         @logout="handleLogout"
+        @clear-preferences-and-logout="handleLogout"
       />
     </template>
     <template #notification>
diff --git a/apps/web-ele/src/layouts/basic.vue b/apps/web-ele/src/layouts/basic.vue
index 1bb07ec8f..c938f09cd 100644
--- a/apps/web-ele/src/layouts/basic.vue
+++ b/apps/web-ele/src/layouts/basic.vue
@@ -226,6 +226,7 @@ watch(
         description="ann.vben@gmail.com"
         tag-text="Pro"
         @logout="handleLogout"
+        @clear-preferences-and-logout="handleLogout"
       />
     </template>
     <template #notification>
diff --git a/apps/web-naive/src/layouts/basic.vue b/apps/web-naive/src/layouts/basic.vue
index 1bb07ec8f..c938f09cd 100644
--- a/apps/web-naive/src/layouts/basic.vue
+++ b/apps/web-naive/src/layouts/basic.vue
@@ -226,6 +226,7 @@ watch(
         description="ann.vben@gmail.com"
         tag-text="Pro"
         @logout="handleLogout"
+        @clear-preferences-and-logout="handleLogout"
       />
     </template>
     <template #notification>
diff --git a/apps/web-tdesign/src/layouts/basic.vue b/apps/web-tdesign/src/layouts/basic.vue
index 1bb07ec8f..c938f09cd 100644
--- a/apps/web-tdesign/src/layouts/basic.vue
+++ b/apps/web-tdesign/src/layouts/basic.vue
@@ -226,6 +226,7 @@ watch(
         description="ann.vben@gmail.com"
         tag-text="Pro"
         @logout="handleLogout"
+        @clear-preferences-and-logout="handleLogout"
       />
     </template>
     <template #notification>
diff --git a/packages/@core/base/typings/src/app.d.ts b/packages/@core/base/typings/src/app.d.ts
index f2b443359..dc6081b1a 100644
--- a/packages/@core/base/typings/src/app.d.ts
+++ b/packages/@core/base/typings/src/app.d.ts
@@ -10,12 +10,17 @@ type LayoutType =
 type ThemeModeType = 'auto' | 'dark' | 'light';
 
 /**
- * 偏好设置按钮位置
+ * 按钮位置
+ * user-dropdown 用户的下拉弹出框中
  * fixed 固定在右侧
  * header 顶栏
  * auto 自动
  */
-type PreferencesButtonPositionType = 'auto' | 'fixed' | 'header';
+type PreferencesButtonPositionType =
+  | 'auto'
+  | 'fixed'
+  | 'header'
+  | 'user-dropdown';
 
 type BuiltinThemeType =
   | 'custom'
diff --git a/packages/@core/preferences/__tests__/__snapshots__/config.test.ts.snap b/packages/@core/preferences/__tests__/__snapshots__/config.test.ts.snap
index 5e3dc6c81..041dfab27 100644
--- a/packages/@core/preferences/__tests__/__snapshots__/config.test.ts.snap
+++ b/packages/@core/preferences/__tests__/__snapshots__/config.test.ts.snap
@@ -30,6 +30,7 @@ exports[`defaultPreferences immutability test > should not modify the config obj
     "loginExpiredMode": "page",
     "name": "Vben Admin",
     "preferencesButtonPosition": "auto",
+    "timezone": "Asia/Shanghai",
     "watermark": false,
     "watermarkContent": "",
     "zIndex": 200,
diff --git a/packages/@core/preferences/src/config.ts b/packages/@core/preferences/src/config.ts
index c39366a75..88ba861fb 100644
--- a/packages/@core/preferences/src/config.ts
+++ b/packages/@core/preferences/src/config.ts
@@ -30,6 +30,7 @@ const defaultPreferences: Preferences = {
     loginExpiredMode: 'page',
     name: 'Vben Admin',
     preferencesButtonPosition: 'auto',
+    timezone: 'Asia/Shanghai',
     watermark: false,
     watermarkContent: '',
     zIndex: 200,
diff --git a/packages/@core/preferences/src/types.ts b/packages/@core/preferences/src/types.ts
index 50aefa6e0..bf86935bf 100644
--- a/packages/@core/preferences/src/types.ts
+++ b/packages/@core/preferences/src/types.ts
@@ -155,6 +155,10 @@ interface AppPreferences {
   name: string;
   /** 偏好设置按钮位置 */
   preferencesButtonPosition: PreferencesButtonPositionType;
+  /**
+   * @zh_CN 应用时区
+   */
+  timezone: string;
   /**
    * @zh_CN 是否开启水印
    */
diff --git a/packages/@core/preferences/src/use-preferences.ts b/packages/@core/preferences/src/use-preferences.ts
index e126cd9a8..a27f8d733 100644
--- a/packages/@core/preferences/src/use-preferences.ts
+++ b/packages/@core/preferences/src/use-preferences.ts
@@ -195,12 +195,12 @@ function usePreferences() {
    */
   const preferencesButtonPosition = computed(() => {
     const { enablePreferences, preferencesButtonPosition } = preferences.app;
-
     // 如果没有启用偏好设置按钮
     if (!enablePreferences) {
       return {
         fixed: false,
         header: false,
+        userDropdown: false,
       };
     }
 
@@ -211,12 +211,15 @@ function usePreferences() {
     const contentIsMaximize = headerHidden && sidebarHidden;
 
     const isHeaderPosition = preferencesButtonPosition === 'header';
+    const isUserDropdownPosition =
+      preferencesButtonPosition === 'user-dropdown';
 
     // 如果设置了固定位置
     if (preferencesButtonPosition !== 'auto') {
       return {
         fixed: preferencesButtonPosition === 'fixed',
         header: isHeaderPosition,
+        userDropdown: isUserDropdownPosition,
       };
     }
 
@@ -230,6 +233,7 @@ function usePreferences() {
     return {
       fixed,
       header: !fixed,
+      userDropdown: !fixed && isUserDropdownPosition,
     };
   });
 
diff --git a/packages/effects/layouts/src/widgets/preferences/blocks/general/general.vue b/packages/effects/layouts/src/widgets/preferences/blocks/general/general.vue
index 857902924..d5fd1c737 100644
--- a/packages/effects/layouts/src/widgets/preferences/blocks/general/general.vue
+++ b/packages/effects/layouts/src/widgets/preferences/blocks/general/general.vue
@@ -1,6 +1,9 @@
 <script setup lang="ts">
+import { onMounted, ref, unref } from 'vue';
+
 import { SUPPORT_LANGUAGES } from '@vben/constants';
 import { $t } from '@vben/locales';
+import { useTimezoneStore } from '@vben/stores';
 
 import InputItem from '../input-item.vue';
 import SelectItem from '../select-item.vue';
@@ -11,6 +14,7 @@ defineOptions({
 });
 
 const appLocale = defineModel<string>('appLocale');
+const appTimezone = defineModel<string>('appTimezone');
 const appDynamicTitle = defineModel<boolean>('appDynamicTitle');
 const appWatermark = defineModel<boolean>('appWatermark');
 const appWatermarkContent = defineModel<string>('appWatermarkContent');
@@ -18,12 +22,32 @@ const appEnableCheckUpdates = defineModel<boolean>('appEnableCheckUpdates');
 const appEnableCopyPreferences = defineModel<boolean>(
   'appEnableCopyPreferences',
 );
+const timezoneStore = useTimezoneStore();
+
+const timezoneOptionsRef = ref<
+  {
+    label: string;
+    value: string;
+  }[]
+>([]);
+
+onMounted(async () => {
+  timezoneOptionsRef.value = await timezoneStore.getTimezoneOptions();
+  // 获取当前时区，例如：Asia/Shanghai
+  const timezoneValue = unref(timezoneStore.timezone);
+  if (timezoneValue) {
+    appTimezone.value = timezoneValue;
+  }
+});
 </script>
 
 <template>
   <SelectItem v-model="appLocale" :items="SUPPORT_LANGUAGES">
     {{ $t('preferences.language') }}
   </SelectItem>
+  <SelectItem v-model="appTimezone" :items="timezoneOptionsRef">
+    {{ $t('preferences.timezone') }}
+  </SelectItem>
   <SwitchItem v-model="appDynamicTitle">
     {{ $t('preferences.dynamicTitle') }}
   </SwitchItem>
diff --git a/packages/effects/layouts/src/widgets/preferences/blocks/layout/widget.vue b/packages/effects/layouts/src/widgets/preferences/blocks/layout/widget.vue
index 73b7af7a8..39cd14e5b 100644
--- a/packages/effects/layouts/src/widgets/preferences/blocks/layout/widget.vue
+++ b/packages/effects/layouts/src/widgets/preferences/blocks/layout/widget.vue
@@ -38,6 +38,10 @@ const positionItems = computed((): SelectOption[] => [
     label: $t('preferences.position.fixed'),
     value: 'fixed',
   },
+  {
+    label: $t('preferences.position.userDropdown'),
+    value: 'user-dropdown',
+  },
 ]);
 </script>
 
diff --git a/packages/effects/layouts/src/widgets/preferences/preferences-drawer.vue b/packages/effects/layouts/src/widgets/preferences/preferences-drawer.vue
index c3204166f..963e9da4b 100644
--- a/packages/effects/layouts/src/widgets/preferences/preferences-drawer.vue
+++ b/packages/effects/layouts/src/widgets/preferences/preferences-drawer.vue
@@ -65,6 +65,7 @@ const emit = defineEmits<{ clearPreferencesAndLogout: [] }>();
 const message = globalShareState.getMessage();
 
 const appLocale = defineModel<SupportedLanguagesType>('appLocale');
+const appTimezone = defineModel<string>('appTimezone');
 const appDynamicTitle = defineModel<boolean>('appDynamicTitle');
 const appLayout = defineModel<LayoutType>('appLayout');
 const appColorGrayMode = defineModel<boolean>('appColorGrayMode');
@@ -359,6 +360,7 @@ function handleCustomPreferencesUpdate(updates: CustomPreferencesRecord) {
                 v-model:app-enable-check-updates="appEnableCheckUpdates"
                 v-model:app-enable-copy-preferences="appEnableCopyPreferences"
                 v-model:app-locale="appLocale"
+                v-model:app-timezone="appTimezone"
                 v-model:app-watermark="appWatermark"
                 v-model:app-watermark-content="appWatermarkContent"
               />
diff --git a/packages/effects/layouts/src/widgets/preferences/preferences.vue b/packages/effects/layouts/src/widgets/preferences/preferences.vue
index d99e0d90d..ef2e41cfe 100644
--- a/packages/effects/layouts/src/widgets/preferences/preferences.vue
+++ b/packages/effects/layouts/src/widgets/preferences/preferences.vue
@@ -11,10 +11,26 @@ import { VbenButton } from '@vben-core/shadcn-ui';
 
 import PreferencesDrawer from './preferences-drawer.vue';
 
+interface Props {
+  /** 是否显示按钮 */
+  showButton?: boolean;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  showButton: true,
+});
+
+const emit = defineEmits<{ clearPreferencesAndLogout: [] }>();
+
 const [Drawer, drawerApi] = useVbenDrawer({
   connectedComponent: PreferencesDrawer,
 });
 
+// 暴露打开抽屉的方法
+defineExpose({
+  open: () => drawerApi.open(),
+});
+
 /**
  * preferences 转成 vue props
  * preferences.widget.fullscreen=>widgetFullscreen
@@ -56,17 +72,22 @@ const listen = computed(() => {
 </script>
 <template>
   <div>
-    <Drawer v-bind="{ ...$attrs, ...attrs }" v-on="listen" />
+    <Drawer
+      v-bind="{ ...$attrs, ...attrs }"
+      v-on="listen"
+      @clear-preferences-and-logout="emit('clearPreferencesAndLogout')"
+    />
 
-    <div @click="() => drawerApi.open()">
-      <slot>
-        <VbenButton
-          :title="$t('preferences.title')"
-          class="flex-col-center size-10 cursor-pointer rounded-l-lg rounded-r-none border-none bg-primary"
-        >
-          <Settings class="size-5" />
-        </VbenButton>
-      </slot>
-    </div>
+    <!-- 触发打开抽屉的按钮(可覆盖) -->
+    <slot>
+      <VbenButton
+        v-if="props.showButton"
+        :title="$t('preferences.title')"
+        class="flex-col-center size-10 cursor-pointer rounded-l-lg rounded-r-none border-none bg-primary"
+        @click="() => drawerApi.open()"
+      >
+        <Settings class="size-5" />
+      </VbenButton>
+    </slot>
   </div>
 </template>
diff --git a/packages/effects/layouts/src/widgets/user-dropdown/user-dropdown.vue b/packages/effects/layouts/src/widgets/user-dropdown/user-dropdown.vue
index b11f3857b..8eadde33a 100644
--- a/packages/effects/layouts/src/widgets/user-dropdown/user-dropdown.vue
+++ b/packages/effects/layouts/src/widgets/user-dropdown/user-dropdown.vue
@@ -6,7 +6,7 @@ import type { AnyFunction } from '@vben/types';
 import { computed, useTemplateRef, watch } from 'vue';
 
 import { useHoverToggle } from '@vben/hooks';
-import { LockKeyhole, LogOut } from '@vben/icons';
+import { LockKeyhole, LogOut, Settings } from '@vben/icons';
 import { $t } from '@vben/locales';
 import { preferences, usePreferences } from '@vben/preferences';
 import { useAccessStore } from '@vben/stores';
@@ -29,6 +29,7 @@ import {
 import { useMagicKeys, whenever } from '@vueuse/core';
 
 import { LockScreenModal } from '../lock-screen';
+import { Preferences } from '../preferences';
 
 interface Props {
   /**
@@ -82,10 +83,13 @@ const props = withDefaults(defineProps<Props>(), {
   hoverDelay: 500,
 });
 
-const emit = defineEmits<{ logout: [] }>();
+const emit = defineEmits<{ clearPreferencesAndLogout: []; logout: [] }>();
 
-const { globalLockScreenShortcutKey, globalLogoutShortcutKey } =
-  usePreferences();
+const {
+  globalLockScreenShortcutKey,
+  globalLogoutShortcutKey,
+  preferencesButtonPosition,
+} = usePreferences();
 const accessStore = useAccessStore();
 const [LockModal, lockModalApi] = useVbenModal({
   connectedComponent: LockScreenModal,
@@ -98,6 +102,7 @@ const [LogoutModal, logoutModalApi] = useVbenModal({
 
 const refTrigger = useTemplateRef('refTrigger');
 const refContent = useTemplateRef('refContent');
+const refPreferences = useTemplateRef('refPreferences');
 const [openPopover, hoverWatcher] = useHoverToggle(
   [refTrigger, refContent],
   () => props.hoverDelay,
@@ -151,6 +156,11 @@ function handleSubmitLogout() {
   logoutModalApi.close();
 }
 
+// 设置 - 打开偏好设置抽屉
+function handleOpenSettings() {
+  refPreferences.value?.open();
+}
+
 if (enableShortcutKey.value) {
   const keys = useMagicKeys();
   const logoutKey = keys['Alt+KeyQ'];
@@ -195,6 +205,13 @@ if (enableShortcutKey.value) {
     {{ $t('ui.widgets.logoutTip') }}
   </LogoutModal>
 
+  <Preferences
+    v-if="preferencesButtonPosition.userDropdown"
+    ref="refPreferences"
+    :show-button="false"
+    @clear-preferences-and-logout="emit('clearPreferencesAndLogout')"
+  />
+
   <DropdownMenu v-model:open="openPopover">
     <DropdownMenuTrigger ref="refTrigger" :disabled="props.trigger === 'hover'">
       <div class="mr-2 ml-1 cursor-pointer rounded-full p-1.5 hover:bg-accent">
@@ -241,6 +258,14 @@ if (enableShortcutKey.value) {
           {{ menu.text }}
         </DropdownMenuItem>
         <DropdownMenuSeparator />
+        <DropdownMenuItem
+          v-if="preferencesButtonPosition.userDropdown"
+          class="mx-1 flex cursor-pointer items-center rounded-sm py-1 leading-8"
+          @click="handleOpenSettings"
+        >
+          <Settings class="mr-2 size-4" />
+          {{ $t('preferences.title') }}
+        </DropdownMenuItem>
         <DropdownMenuItem
           v-if="preferences.widget.lockScreen"
           class="mx-1 flex cursor-pointer items-center rounded-sm py-1 leading-8"
diff --git a/packages/locales/src/langs/en-US/preferences.json b/packages/locales/src/langs/en-US/preferences.json
index b9a4278ba..209eacfe6 100644
--- a/packages/locales/src/langs/en-US/preferences.json
+++ b/packages/locales/src/langs/en-US/preferences.json
@@ -38,6 +38,7 @@
   "mode": "Mode",
   "general": "General",
   "language": "Language",
+  "timezone": "Timezone",
   "dynamicTitle": "Dynamic Title",
   "watermark": "Watermark",
   "watermarkContent": "Please input Watermark content",
@@ -46,7 +47,8 @@
     "title": "Preferences Postion",
     "header": "Header",
     "auto": "Auto",
-    "fixed": "Fixed"
+    "fixed": "Fixed",
+    "userDropdown": "User Dropdown"
   },
   "sidebar": {
     "buttons": "Show Buttons",
diff --git a/packages/locales/src/langs/zh-CN/preferences.json b/packages/locales/src/langs/zh-CN/preferences.json
index 0d5add7f6..2d4a3d44f 100644
--- a/packages/locales/src/langs/zh-CN/preferences.json
+++ b/packages/locales/src/langs/zh-CN/preferences.json
@@ -38,6 +38,7 @@
   "mode": "模式",
   "general": "通用",
   "language": "语言",
+  "timezone": "时区",
   "dynamicTitle": "动态标题",
   "watermark": "水印",
   "watermarkContent": "请输入水印文案",
@@ -46,7 +47,8 @@
     "title": "偏好设置位置",
     "header": "顶栏",
     "auto": "自动",
-    "fixed": "固定"
+    "fixed": "固定",
+    "userDropdown": "用户下拉窗"
   },
   "sidebar": {
     "buttons": "显示按钮",
diff --git a/playground/src/layouts/basic.vue b/playground/src/layouts/basic.vue
index 62b641768..50381b571 100644
--- a/playground/src/layouts/basic.vue
+++ b/playground/src/layouts/basic.vue
@@ -251,6 +251,7 @@ onBeforeMount(() => {
         tag-text="Pro"
         trigger="both"
         @logout="handleLogout"
+        @clear-preferences-and-logout="handleLogout"
       />
     </template>
     <template #notification>