From ccabbf0e97e2c2b1e8cf8eb2ce35c8c0fb3acb41 Mon Sep 17 00:00:00 2001 From: Caisin Date: Mon, 13 Apr 2026 15:11:57 +0800 Subject: [PATCH] feat: enable project-scoped preferences extension tabs (#7803) * feat: enable project-scoped preferences extension tabs Add a typed extension schema so subprojects can define extra settings, render them in the shared preferences drawer only when configured, and consume them in playground as a real feature demo. Extension labels now follow locale keys instead of hardcoded app-specific strings. Constraint: Reuse the shared preferences drawer and field blocks Rejected: Add app-specific fields to core preferences | too tightly coupled Rejected: Inline localized label objects | breaks existing locale-key flow Confidence: high Scope-risk: moderate Reversibility: clean Directive: Keep extension labels as locale keys rendered via $t in UI Tested: Vitest preferences tests Tested: Turbo typecheck for preferences, layouts, web-antd, and playground Tested: ESLint for touched preferences and playground files Not-tested: Manual browser interaction in playground preferences drawer * fix: satisfy lint formatting for preferences extension demo Adjust the playground preferences extension demo template so formatter and Vue template lint rules agree on the rendered markup. This keeps CI green without changing runtime behavior. Constraint: Must preserve the existing demo behavior while fixing CI only Rejected: Disable the Vue newline rule | would weaken shared lint guarantees Confidence: high Scope-risk: narrow Reversibility: clean Directive: Prefer computed/template structures that avoid formatter-vs-lint conflicts Tested: pnpm run lint Not-tested: Manual browser interaction in playground preferences extension demo * fix: harden custom preferences validation and i18n labels Tighten custom preferences handling so numeric extension fields respect min, max, and step constraints. Number inputs now ignore NaN values, and web-antd extension metadata uses locale keys instead of raw strings. Also align tip-based hover guards in shared preference inputs/selects. Constraint: Keep fixes scoped to verified findings only Rejected: Broader refactor of preferences field components | not needed for these fixes Confidence: high Scope-risk: narrow Reversibility: clean Directive: Reuse the same validation path for updates and cache hydration Tested: Vitest preferences tests Tested: ESLint for touched preferences and widget files Tested: Typecheck for web-antd, layouts, and core preferences Not-tested: Manual browser interaction for all preference field variants * fix: remove localized default from playground extension config Drop the hardcoded Chinese default value from the playground extension report title field and fall back to an empty string instead. This keeps extension config locale-neutral while preserving localized labels and placeholders through translation keys. Constraint: Keep the fix limited to the verified localized default issue Rejected: Compute the default from runtime locale in config | unnecessary for this finding Confidence: high Scope-risk: narrow Reversibility: clean Directive: Avoid embedding localized literals in extension default values Tested: ESLint for playground/src/preferences.ts Tested: Oxfmt check for playground/src/preferences.ts Not-tested: Manual playground preferences interaction * docs: document project-scoped preferences extension workflow Add Chinese and English guide sections explaining how to define, initialize, read, and update project-scoped preferences extensions. Also document numeric field validation and point readers to the playground demo for a complete example. Constraint: Keep this docs-only and aligned with the shipped API Rejected: Update only Chinese docs | would leave English docs inconsistent Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep zh/en examples and playground demo paths synchronized Tested: git diff --check; pnpm build:docs Not-tested: Manual browser review of the rendered docs site * fix: harden custom preferences defaults and baselines Use a locale-neutral default for the web-antd report title. Also stop preference getters from exposing mutable baseline or extension schema objects, and add a regression test for external mutation attempts. Constraint: Keep behavior compatible with the shipped preferences API Rejected: Return raw refs with readonly typing only | callers could still mutate internals Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep defensive copies for baseline and schema getters unless storage semantics change Tested: eslint, oxlint, targeted vitest, filtered typecheck, git diff --check Not-tested: Full monorepo typecheck and test suite * test: relax custom preference cache key matching Avoid coupling the custom-number cache test to one exact localStorage key string. Match the intended cache lookup more loosely so the test still verifies filtering behavior without depending on the full namespaced cache key. Constraint: Focus the test on cache filtering behavior Rejected: Assert one exact key | brittle with namespace changes Confidence: high Scope-risk: narrow Reversibility: clean Directive: Prefer behavior tests over literal storage keys Tested: targeted vitest, eslint, git diff --check Not-tested: Full monorepo test suite --------- Co-authored-by: caisin --- .gitignore | 2 +- apps/web-antd/src/main.ts | 3 +- apps/web-antd/src/preferences.ts | 61 +++- docs/src/en/guide/essentials/settings.md | 150 +++++++++ docs/src/guide/essentials/settings.md | 150 +++++++++ .../preferences/__tests__/preferences.test.ts | 301 +++++++++++++++++- packages/@core/preferences/src/index.ts | 4 + packages/@core/preferences/src/preferences.ts | 252 ++++++++++++++- packages/@core/preferences/src/types.ts | 94 +++++- .../@core/preferences/src/use-preferences.ts | 13 + .../preferences/blocks/custom/custom.vue | 121 +++++++ .../src/widgets/preferences/blocks/index.ts | 1 + .../widgets/preferences/blocks/input-item.vue | 14 +- .../preferences/blocks/select-item.vue | 14 +- .../preferences/preferences-drawer.vue | 76 ++++- .../locales/src/langs/en-US/preferences.json | 28 ++ .../locales/src/langs/zh-CN/preferences.json | 28 ++ packages/preferences/src/index.ts | 14 +- playground/src/locales/langs/en-US/demos.json | 58 ++++ playground/src/locales/langs/zh-CN/demos.json | 58 ++++ playground/src/main.ts | 3 +- playground/src/preferences.ts | 73 ++++- playground/src/router/routes/modules/demos.ts | 10 + .../features/preferences-extension/index.vue | 231 ++++++++++++++ 24 files changed, 1720 insertions(+), 39 deletions(-) create mode 100644 packages/effects/layouts/src/widgets/preferences/blocks/custom/custom.vue create mode 100644 playground/src/views/demos/features/preferences-extension/index.vue diff --git a/.gitignore b/.gitignore index df1f37a8a..86d1f1f8a 100644 --- a/.gitignore +++ b/.gitignore @@ -22,7 +22,7 @@ yarn.lock package-lock.json .VSCodeCounter **/backend-mock/data - +.omx # local env files .env.local .env.*.local diff --git a/apps/web-antd/src/main.ts b/apps/web-antd/src/main.ts index 5d728a02a..110acbd7c 100644 --- a/apps/web-antd/src/main.ts +++ b/apps/web-antd/src/main.ts @@ -1,7 +1,7 @@ import { initPreferences } from '@vben/preferences'; import { unmountGlobalLoading } from '@vben/utils'; -import { overridesPreferences } from './preferences'; +import { overridesPreferences, preferencesExtension } from './preferences'; /** * 应用初始化完成之后再进行页面加载渲染 @@ -15,6 +15,7 @@ async function initApplication() { // app偏好设置初始化 await initPreferences({ + extension: preferencesExtension, namespace, overrides: overridesPreferences, }); diff --git a/apps/web-antd/src/preferences.ts b/apps/web-antd/src/preferences.ts index b2e9ace43..3f56c477f 100644 --- a/apps/web-antd/src/preferences.ts +++ b/apps/web-antd/src/preferences.ts @@ -1,4 +1,14 @@ -import { defineOverridesPreferences } from '@vben/preferences'; +import { + defineOverridesPreferences, + definePreferencesExtension, +} from '@vben/preferences'; + +interface WebAntdPreferencesExtension { + defaultTableSize: number; + enableFormFullscreen: boolean; + reportTitle: string; + tenantMode: 'multi' | 'single'; +} /** * @description 项目配置文件 @@ -11,3 +21,52 @@ export const overridesPreferences = defineOverridesPreferences({ name: import.meta.env.VITE_APP_TITLE, }, }); + +export const preferencesExtension = + definePreferencesExtension({ + tabLabel: 'preferences.antd.tabLabel', + title: 'preferences.antd.title', + fields: [ + { + component: 'switch', + defaultValue: true, + key: 'enableFormFullscreen', + label: 'preferences.antd.fields.enableFormFullscreen.label', + tip: 'preferences.antd.fields.enableFormFullscreen.tip', + }, + { + component: 'select', + defaultValue: 'single', + key: 'tenantMode', + label: 'preferences.antd.fields.tenantMode.label', + options: [ + { + label: 'preferences.antd.fields.tenantMode.options.single.label', + value: 'single', + }, + { + label: 'preferences.antd.fields.tenantMode.options.multi.label', + value: 'multi', + }, + ], + }, + { + component: 'number', + componentProps: { + max: 200, + min: 10, + step: 10, + }, + defaultValue: 20, + key: 'defaultTableSize', + label: 'preferences.antd.fields.defaultTableSize.label', + }, + { + component: 'input', + defaultValue: '', + key: 'reportTitle', + label: 'preferences.antd.fields.reportTitle.label', + placeholder: 'preferences.antd.fields.reportTitle.placeholder', + }, + ], + }); diff --git a/docs/src/en/guide/essentials/settings.md b/docs/src/en/guide/essentials/settings.md index 59bb3900a..69aedbde2 100644 --- a/docs/src/en/guide/essentials/settings.md +++ b/docs/src/en/guide/essentials/settings.md @@ -193,6 +193,156 @@ export const overridesPreferences = defineOverridesPreferences({ }); ``` +### Extend project-level preferences + +In addition to overriding the built-in framework preferences, you can also add a set of business preferences for each application. After configuration, the preferences drawer will display an extra tab for the current app, and the data will be stored together with the app `namespace`. This is useful for project-specific fields such as tenant mode, business titles, or default page size. + +#### 1. Define the extension in `src/preferences.ts` + +```ts +import { + defineOverridesPreferences, + definePreferencesExtension, +} from '@vben/preferences'; + +interface ProjectPreferencesExtension { + defaultTableSize: number; + enableFormFullscreen: boolean; + reportTitle: string; + tenantMode: 'multi' | 'single'; +} + +export const overridesPreferences = defineOverridesPreferences({ + app: { + name: import.meta.env.VITE_APP_TITLE, + }, +}); + +export const preferencesExtension = + definePreferencesExtension({ + tabLabel: 'preferences.antd.tabLabel', + title: 'preferences.antd.title', + fields: [ + { + component: 'switch', + defaultValue: true, + key: 'enableFormFullscreen', + label: 'preferences.antd.fields.enableFormFullscreen.label', + tip: 'preferences.antd.fields.enableFormFullscreen.tip', + }, + { + component: 'select', + defaultValue: 'single', + key: 'tenantMode', + label: 'preferences.antd.fields.tenantMode.label', + options: [ + { + label: 'preferences.antd.fields.tenantMode.options.single.label', + value: 'single', + }, + { + label: 'preferences.antd.fields.tenantMode.options.multi.label', + value: 'multi', + }, + ], + }, + { + component: 'number', + componentProps: { + max: 200, + min: 10, + step: 10, + }, + defaultValue: 20, + key: 'defaultTableSize', + label: 'preferences.antd.fields.defaultTableSize.label', + }, + { + component: 'input', + defaultValue: '', + key: 'reportTitle', + label: 'preferences.antd.fields.reportTitle.label', + placeholder: 'preferences.antd.fields.reportTitle.placeholder', + }, + ], + }); +``` + +- `tabLabel` is the tab label, and `title` is the panel title. If `title` is omitted, `tabLabel` is used as the fallback. +- `fields` currently supports four component types: `input`, `number`, `select`, and `switch`. +- `label`, `placeholder`, `tip`, and `options[].label` can be i18n keys directly. The preferences drawer resolves them with `$t` automatically. + +#### 2. Pass `extension` when initializing preferences + +```ts +import { initPreferences } from '@vben/preferences'; + +import { overridesPreferences, preferencesExtension } from './preferences'; + +await initPreferences({ + namespace, + overrides: overridesPreferences, + extension: preferencesExtension, +}); +``` + +The same `namespace` isolates both framework preferences and extension preferences. So even if multiple subprojects run in the same browser, their business preferences remain independent. + +#### 3. Read or update extension preferences in business pages + +```ts +import { + getCustomPreferences, + updateCustomPreferences, + usePreferences, +} from '@vben/preferences'; + +interface ProjectPreferencesExtension { + defaultTableSize: number; + enableFormFullscreen: boolean; + reportTitle: string; + tenantMode: 'multi' | 'single'; +} + +const projectPreferences = getCustomPreferences(); + +const { customPreferences, preferencesExtension } = usePreferences(); + +updateCustomPreferences({ + defaultTableSize: 50, + tenantMode: 'multi', +}); +``` + +- `getCustomPreferences` returns the reactive extension-preferences object for the current app. +- `customPreferences` and `preferencesExtension` from `usePreferences` are convenient when composing reusable logic. +- Calling `resetPreferences()` also resets extension preferences back to their default values. + +#### 4. Number fields validate `min` / `max` / `step` automatically + +If you provide `componentProps.min`, `componentProps.max`, and `componentProps.step` for a `number` field, runtime persistence follows the same constraints. For example: + +```ts +{ + component: 'number', + componentProps: { + min: 10, + max: 200, + step: 10, + }, + defaultValue: 20, + key: 'defaultTableSize', + label: 'preferences.antd.fields.defaultTableSize.label', +} +``` + +Only values within `10 ~ 200` and increasing by `10` will be saved. Values like `15`, `205`, or invalid legacy cache values are ignored automatically. + +For complete examples, see: + +- `playground/src/preferences.ts` +- `playground/src/views/demos/features/preferences-extension/index.vue` + ### Framework default configuration ::: details View the default configuration of the framework diff --git a/docs/src/guide/essentials/settings.md b/docs/src/guide/essentials/settings.md index 9637114fe..067a1cb95 100644 --- a/docs/src/guide/essentials/settings.md +++ b/docs/src/guide/essentials/settings.md @@ -192,6 +192,156 @@ export const overridesPreferences = defineOverridesPreferences({ }); ``` +### 扩展项目级偏好 + +除了覆盖框架内置偏好外，还可以为每个应用追加一组“业务偏好”。配置后，偏好设置抽屉会新增一个独立标签页，并且这组数据会跟随当前应用的 `namespace` 一起存储，适合放租户模式、业务标题、默认分页条数等项目字段。 + +#### 1. 在应用的 `src/preferences.ts` 中定义扩展 + +```ts +import { + defineOverridesPreferences, + definePreferencesExtension, +} from '@vben/preferences'; + +interface ProjectPreferencesExtension { + defaultTableSize: number; + enableFormFullscreen: boolean; + reportTitle: string; + tenantMode: 'multi' | 'single'; +} + +export const overridesPreferences = defineOverridesPreferences({ + app: { + name: import.meta.env.VITE_APP_TITLE, + }, +}); + +export const preferencesExtension = + definePreferencesExtension({ + tabLabel: 'preferences.antd.tabLabel', + title: 'preferences.antd.title', + fields: [ + { + component: 'switch', + defaultValue: true, + key: 'enableFormFullscreen', + label: 'preferences.antd.fields.enableFormFullscreen.label', + tip: 'preferences.antd.fields.enableFormFullscreen.tip', + }, + { + component: 'select', + defaultValue: 'single', + key: 'tenantMode', + label: 'preferences.antd.fields.tenantMode.label', + options: [ + { + label: 'preferences.antd.fields.tenantMode.options.single.label', + value: 'single', + }, + { + label: 'preferences.antd.fields.tenantMode.options.multi.label', + value: 'multi', + }, + ], + }, + { + component: 'number', + componentProps: { + max: 200, + min: 10, + step: 10, + }, + defaultValue: 20, + key: 'defaultTableSize', + label: 'preferences.antd.fields.defaultTableSize.label', + }, + { + component: 'input', + defaultValue: '', + key: 'reportTitle', + label: 'preferences.antd.fields.reportTitle.label', + placeholder: 'preferences.antd.fields.reportTitle.placeholder', + }, + ], + }); +``` + +- `tabLabel` 是标签名称，`title` 是该标签页标题；如果不传 `title`，会回退使用 `tabLabel`。 +- `fields` 目前支持 `input`、`number`、`select`、`switch` 四种组件。 +- `label`、`placeholder`、`tip`、`options[].label` 可以直接写 i18n key，偏好设置面板会自动调用 `$t` 渲染。 + +#### 2. 初始化偏好设置时传入 `extension` + +```ts +import { initPreferences } from '@vben/preferences'; + +import { overridesPreferences, preferencesExtension } from './preferences'; + +await initPreferences({ + namespace, + overrides: overridesPreferences, + extension: preferencesExtension, +}); +``` + +这里的 `namespace` 会同时隔离框架偏好和扩展偏好。因此同一浏览器中即使运行多个子项目，它们的业务偏好也不会互相污染。 + +#### 3. 在业务页面中读取或更新扩展偏好 + +```ts +import { + getCustomPreferences, + updateCustomPreferences, + usePreferences, +} from '@vben/preferences'; + +interface ProjectPreferencesExtension { + defaultTableSize: number; + enableFormFullscreen: boolean; + reportTitle: string; + tenantMode: 'multi' | 'single'; +} + +const projectPreferences = getCustomPreferences(); + +const { customPreferences, preferencesExtension } = usePreferences(); + +updateCustomPreferences({ + defaultTableSize: 50, + tenantMode: 'multi', +}); +``` + +- `getCustomPreferences` 返回当前应用扩展偏好的响应式对象，适合直接在页面中读取。 +- `usePreferences` 中的 `customPreferences` 和 `preferencesExtension` 适合在组合式逻辑里统一使用。 +- 调用 `resetPreferences()` 时，扩展偏好也会一起重置到默认值。 + +#### 4. 数字字段会自动校验 `min` / `max` / `step` + +为 `number` 字段设置 `componentProps.min`、`componentProps.max`、`componentProps.step` 后，运行时保存也会遵守同样的规则。例如下面的配置： + +```ts +{ + component: 'number', + componentProps: { + min: 10, + max: 200, + step: 10, + }, + defaultValue: 20, + key: 'defaultTableSize', + label: 'preferences.antd.fields.defaultTableSize.label', +} +``` + +此时只有 `10 ~ 200` 且按 `10` 递增的值会被保存；像 `15`、`205`，或者旧缓存里不满足约束的值，都会被自动忽略。 + +完整示例可以参考： + +- `playground/src/preferences.ts` +- `playground/src/views/demos/features/preferences-extension/index.vue` + ### 框架默认配置 ::: details 查看框架默认配置 diff --git a/packages/@core/preferences/__tests__/preferences.test.ts b/packages/@core/preferences/__tests__/preferences.test.ts index 37657d89f..84e9844e4 100644 --- a/packages/@core/preferences/__tests__/preferences.test.ts +++ b/packages/@core/preferences/__tests__/preferences.test.ts @@ -1,11 +1,13 @@ -import { beforeEach, describe, expect, it, vi } from 'vitest'; +import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'; import { defaultPreferences } from '../src/config'; -import { PreferenceManager } from '../src/preferences'; import { isDarkTheme } from '../src/update-css-variables'; describe('preferences', () => { - let preferenceManager: PreferenceManager; + let PreferenceManager: typeof import('../src/preferences').PreferenceManager; + let preferenceManager: InstanceType< + typeof import('../src/preferences').PreferenceManager + >; // 模拟 window.matchMedia 方法 vi.stubGlobal( @@ -21,7 +23,36 @@ describe('preferences', () => { removeListener: vi.fn(), // Deprecated })), ); + + vi.stubGlobal('localStorage', { + clear: vi.fn(), + getItem: vi.fn(() => null), + key: vi.fn(() => null), + length: 0, + removeItem: vi.fn(), + setItem: vi.fn(), + }); + + vi.stubGlobal('sessionStorage', { + clear: vi.fn(), + getItem: vi.fn(() => null), + key: vi.fn(() => null), + length: 0, + removeItem: vi.fn(), + setItem: vi.fn(), + }); + + beforeAll(async () => { + ({ PreferenceManager } = await import('../src/preferences')); + }); + beforeEach(() => { + vi.mocked(localStorage.getItem).mockImplementation(() => null); + vi.mocked(localStorage.removeItem).mockReset(); + vi.mocked(localStorage.setItem).mockReset(); + vi.mocked(sessionStorage.getItem).mockImplementation(() => null); + vi.mocked(sessionStorage.removeItem).mockReset(); + vi.mocked(sessionStorage.setItem).mockReset(); preferenceManager = new PreferenceManager(); }); @@ -214,7 +245,10 @@ describe('preferences', () => { }, }; - await preferenceManager.initPreferences(overrides); + await preferenceManager.initPreferences({ + namespace: 'apply-updates', + overrides, + }); preferenceManager.updatePreferences({ theme: { mode: 'light' }, @@ -222,6 +256,265 @@ describe('preferences', () => { expect(preferenceManager.getPreferences().theme.mode).toBe('light'); }); + + it('initializes custom preferences extension with default values', async () => { + const extension = { + fields: [ + { + component: 'switch', + defaultValue: true, + key: 'enableWorkbench', + label: '启用工作台', + }, + { + component: 'select', + defaultValue: 'single', + key: 'tenantMode', + label: '租户模式', + options: [ + { label: '单租户', value: 'single' }, + { label: '多租户', value: 'multi' }, + ], + }, + ], + tabLabel: '扩展', + title: '业务偏好', + } as const; + + await preferenceManager.initPreferences({ + extension, + namespace: 'custom-defaults', + }); + + expect(preferenceManager.getPreferencesExtension()).toEqual(extension); + expect(preferenceManager.getCustomPreferences()).toEqual({ + enableWorkbench: true, + tenantMode: 'single', + }); + }); + + it('does not expose mutable custom preference baselines or extension schema', async () => { + const extension = { + fields: [ + { + component: 'number', + componentProps: { + max: 10, + min: 2, + step: 2, + }, + defaultValue: 4, + key: 'pageSize', + label: '分页大小', + }, + ], + tabLabel: '扩展', + title: '业务偏好', + } as const; + + await preferenceManager.initPreferences({ + extension, + namespace: 'custom-readonly', + }); + + const initialCustomPreferences = + preferenceManager.getInitialCustomPreferences<{ + pageSize: number; + }>() as { pageSize: number }; + const preferencesExtension = preferenceManager.getPreferencesExtension<{ + pageSize: number; + }>() as { + fields: Array<{ componentProps?: { max?: number }; label: string }>; + }; + const [firstField] = preferencesExtension.fields; + + initialCustomPreferences.pageSize = 8; + expect(firstField).toBeDefined(); + expect(firstField?.componentProps).toBeDefined(); + + if (!firstField || !firstField.componentProps) { + return; + } + + firstField.label = '已修改'; + firstField.componentProps.max = 20; + + expect(preferenceManager.getInitialCustomPreferences()).toEqual({ + pageSize: 4, + }); + expect(preferenceManager.getPreferencesExtension()).toEqual(extension); + }); + + it('updates and resets custom preferences correctly', async () => { + await preferenceManager.initPreferences({ + extension: { + fields: [ + { + component: 'number', + defaultValue: 20, + key: 'pageSize', + label: '分页大小', + }, + { + component: 'input', + defaultValue: '日报', + key: 'reportTitle', + label: '报表标题', + }, + ], + tabLabel: '扩展', + }, + namespace: 'custom-reset', + }); + + preferenceManager.updateCustomPreferences({ + pageSize: 50, + reportTitle: '月报', + }); + + expect(preferenceManager.getCustomPreferences()).toEqual({ + pageSize: 50, + reportTitle: '月报', + }); + + preferenceManager.resetPreferences(); + + expect(preferenceManager.getCustomPreferences()).toEqual({ + pageSize: 20, + reportTitle: '日报', + }); + }); + + it('ignores invalid custom preferences updates', async () => { + await preferenceManager.initPreferences({ + extension: { + fields: [ + { + component: 'switch', + defaultValue: true, + key: 'enableWorkbench', + label: '启用工作台', + }, + { + component: 'select', + defaultValue: 'single', + key: 'tenantMode', + label: '租户模式', + options: [ + { label: '单租户', value: 'single' }, + { label: '多租户', value: 'multi' }, + ], + }, + ], + tabLabel: '扩展', + }, + namespace: 'custom-invalid', + }); + + const originalCustomPreferences = preferenceManager.getCustomPreferences(); + + preferenceManager.updateCustomPreferences({ + enableWorkbench: 'true' as unknown as boolean, + tenantMode: 'unknown', + unknownField: 'value', + } as any); + + expect(preferenceManager.getCustomPreferences()).toEqual( + originalCustomPreferences, + ); + }); + + it('enforces custom number field min max and step constraints', async () => { + await preferenceManager.initPreferences({ + extension: { + fields: [ + { + component: 'number', + componentProps: { + max: 10, + min: 2, + step: 2, + }, + defaultValue: 4, + key: 'pageSize', + label: '分页大小', + }, + ], + tabLabel: '扩展', + }, + namespace: 'custom-number-constraints', + }); + + preferenceManager.updateCustomPreferences({ + pageSize: 8, + }); + + expect(preferenceManager.getCustomPreferences()).toEqual({ + pageSize: 8, + }); + + preferenceManager.updateCustomPreferences({ + pageSize: 1, + }); + + expect(preferenceManager.getCustomPreferences()).toEqual({ + pageSize: 8, + }); + + preferenceManager.updateCustomPreferences({ + pageSize: 12, + }); + + expect(preferenceManager.getCustomPreferences()).toEqual({ + pageSize: 8, + }); + + preferenceManager.updateCustomPreferences({ + pageSize: 5, + }); + + expect(preferenceManager.getCustomPreferences()).toEqual({ + pageSize: 8, + }); + }); + + it('filters cached custom number values that violate field constraints', async () => { + vi.mocked(localStorage.getItem).mockImplementation((key) => { + if (key.endsWith('cache-preferences-custom')) { + return JSON.stringify({ + value: { + pageSize: 5, + }, + }); + } + + return null; + }); + + await preferenceManager.initPreferences({ + extension: { + fields: [ + { + component: 'number', + componentProps: { + max: 10, + min: 2, + step: 2, + }, + defaultValue: 4, + key: 'pageSize', + label: '分页大小', + }, + ], + tabLabel: '扩展', + }, + namespace: 'custom-number-cache', + }); + + expect(preferenceManager.getCustomPreferences()).toEqual({ + pageSize: 4, + }); + }); }); describe('isDarkTheme', () => { diff --git a/packages/@core/preferences/src/index.ts b/packages/@core/preferences/src/index.ts index 15ec89639..d81823d17 100644 --- a/packages/@core/preferences/src/index.ts +++ b/packages/@core/preferences/src/index.ts @@ -4,7 +4,11 @@ import { preferencesManager } from './preferences'; export const { getPreferences, + getCustomPreferences, + getInitialCustomPreferences, + getPreferencesExtension, updatePreferences, + updateCustomPreferences, resetPreferences, clearCache, initPreferences, diff --git a/packages/@core/preferences/src/preferences.ts b/packages/@core/preferences/src/preferences.ts index 1dfd530c7..7f82bb094 100644 --- a/packages/@core/preferences/src/preferences.ts +++ b/packages/@core/preferences/src/preferences.ts @@ -1,6 +1,12 @@ import type { DeepPartial } from '@vben-core/typings'; -import type { InitialOptions, Preferences } from './types'; +import type { + CustomPreferencesField, + CustomPreferencesRecord, + InitialOptions, + Preferences, + PreferencesExtension, +} from './types'; import { markRaw, reactive, readonly, watch } from 'vue'; @@ -17,6 +23,7 @@ import { defaultPreferences } from './config'; import { updateCSSVariables } from './update-css-variables'; const STORAGE_KEYS = { + CUSTOM: 'preferences-custom', MAIN: 'preferences', LOCALE: 'preferences-locale', THEME: 'preferences-theme', @@ -24,7 +31,10 @@ const STORAGE_KEYS = { class PreferenceManager { private cache: StorageManager; - private debouncedSave: (preference: Preferences) => void; + private customPreferencesExtension: null | PreferencesExtension = null; + private customState = reactive({}); + private debouncedSave: () => void; + private initialCustomPreferences: CustomPreferencesRecord = {}; private initialPreferences: Preferences = defaultPreferences; private isInitialized = false; private state: Preferences; @@ -34,10 +44,7 @@ class PreferenceManager { this.state = reactive( this.loadFromCache() || { ...defaultPreferences }, ); - this.debouncedSave = useDebounceFn( - (preference) => this.saveToCache(preference), - 150, - ); + this.debouncedSave = useDebounceFn(() => this.saveToCache(), 150); } /** @@ -47,6 +54,26 @@ class PreferenceManager { Object.values(STORAGE_KEYS).forEach((key) => this.cache.removeItem(key)); }; + /** + * 获取扩展偏好设置 + */ + getCustomPreferences = < + TCustomPreferences extends object = CustomPreferencesRecord, + >() => { + return readonly(this.customState) as Readonly; + }; + + /** + * 获取初始化扩展偏好设置 + */ + getInitialCustomPreferences = < + TCustomPreferences extends object = CustomPreferencesRecord, + >() => { + return this.cloneValue( + this.initialCustomPreferences, + ) as Readonly; + }; + /** * 获取初始化偏好设置 */ @@ -61,13 +88,32 @@ class PreferenceManager { return readonly(this.state); }; + /** + * 获取扩展偏好设置配置 + */ + getPreferencesExtension = < + TCustomPreferences extends object = CustomPreferencesRecord, + >() => { + return this.customPreferencesExtension + ? (this.cloneValue(this.customPreferencesExtension) as Readonly< + PreferencesExtension + >) + : null; + }; + /** * 初始化偏好设置 * @param options - 初始化配置项 * @param options.namespace - 命名空间，用于隔离不同应用的配置 * @param options.overrides - 要覆盖的偏好设置 */ - initPreferences = async ({ namespace, overrides }: InitialOptions) => { + initPreferences = async < + TCustomPreferences extends object = CustomPreferencesRecord, + >({ + namespace, + overrides, + extension, + }: InitialOptions) => { // 防止重复初始化 if (this.isInitialized) { return; @@ -78,6 +124,10 @@ class PreferenceManager { // 合并初始偏好设置 this.initialPreferences = merge({}, overrides, defaultPreferences); + this.customPreferencesExtension = extension ?? null; + this.initialCustomPreferences = this.resolveCustomPreferencesDefaults( + this.customPreferencesExtension, + ); // 加载缓存的偏好设置并与初始配置合并 const cachedPreferences = this.loadFromCache() || {}; @@ -89,6 +139,14 @@ class PreferenceManager { // 更新偏好设置 this.updatePreferences(mergedPreference); + this.replaceCustomPreferences( + merge( + {}, + this.sanitizeCustomPreferences(this.loadCustomFromCache() || {}), + this.initialCustomPreferences, + ), + ); + this.saveToCache(); // 设置监听器 this.setupWatcher(); @@ -105,14 +163,42 @@ class PreferenceManager { resetPreferences = () => { // 将状态重置为初始偏好设置 Object.assign(this.state, this.initialPreferences); + this.replaceCustomPreferences(this.initialCustomPreferences); // 保存偏好设置至缓存 - this.saveToCache(this.state); + this.saveToCache(); // 直接触发 UI 更新 this.handleUpdates(this.state); }; + /** + * 更新扩展偏好设置 + * @param updates - 要更新的扩展偏好设置 + */ + updateCustomPreferences = < + TCustomPreferences extends object = CustomPreferencesRecord, + >( + updates: DeepPartial, + ) => { + if (!this.customPreferencesExtension) { + return; + } + + const sanitizedUpdates = this.sanitizeCustomPreferences( + updates as DeepPartial, + ); + + if (Object.keys(sanitizedUpdates).length === 0) { + return; + } + + this.replaceCustomPreferences( + merge({}, sanitizedUpdates, markRaw(this.customState)), + ); + this.debouncedSave(); + }; + /** * 更新偏好设置 * @param updates - 要更新的偏好设置 @@ -126,9 +212,25 @@ class PreferenceManager { this.handleUpdates(updates); // 保存到缓存 - this.debouncedSave(this.state); + this.debouncedSave(); }; + private cloneValue(value: T): T { + if (Array.isArray(value)) { + return value.map((item) => this.cloneValue(item)) as T; + } + + if (value && typeof value === 'object') { + return Object.fromEntries( + Object.entries(value as Record).map( + ([key, nestedValue]) => [key, this.cloneValue(nestedValue)], + ), + ) as T; + } + + return value; + } + /** * 处理更新 * @param updates - 更新的偏好设置 @@ -158,6 +260,70 @@ class PreferenceManager { document.documentElement.dataset.platform = isMacOs() ? 'macOs' : 'window'; } + private isAlmostInteger(value: number, epsilon = Number.EPSILON * 10) { + return Math.abs(value - Math.round(value)) < epsilon; + } + + private isValidCustomPreferenceValue( + field: CustomPreferencesField, + value: unknown, + ) { + switch (field.component) { + case 'number': { + if (typeof value !== 'number' || !Number.isFinite(value)) { + return false; + } + + const max = this.resolveNumericConstraint(field.componentProps?.max); + const min = this.resolveNumericConstraint(field.componentProps?.min); + const step = this.resolveNumericConstraint(field.componentProps?.step); + + if (min !== undefined && value < min) { + return false; + } + + if (max !== undefined && value > max) { + return false; + } + + if (step !== undefined) { + if (step <= 0) { + return false; + } + + const stepBase = min ?? 0; + const stepCount = (value - stepBase) / step; + + if (!this.isAlmostInteger(stepCount)) { + return false; + } + } + + return true; + } + case 'select': { + return ( + typeof value === 'string' && + field.options.some((option) => option.value === value) + ); + } + case 'switch': { + return typeof value === 'boolean'; + } + default: { + return typeof value === 'string'; + } + } + } + + /** + * 从缓存加载扩展偏好设置 + * @returns 缓存的扩展偏好设置，如果不存在则返回 null + */ + private loadCustomFromCache(): CustomPreferencesRecord | null { + return this.cache.getItem(STORAGE_KEYS.CUSTOM); + } + /** * 从缓存加载偏好设置 * @returns 缓存的偏好设置，如果不存在则返回 null @@ -166,14 +332,72 @@ class PreferenceManager { return this.cache.getItem(STORAGE_KEYS.MAIN); } + private replaceCustomPreferences(preferences: CustomPreferencesRecord) { + Object.keys(this.customState).forEach((key) => { + Reflect.deleteProperty(this.customState, key); + }); + Object.assign(this.customState, preferences); + } + + private resolveCustomPreferencesDefaults( + extension: null | PreferencesExtension, + ) { + if (!extension) { + return {}; + } + + const result: CustomPreferencesRecord = {}; + + for (const field of extension.fields) { + result[field.key] = field.defaultValue; + } + + return result; + } + + private resolveNumericConstraint(value: unknown) { + return typeof value === 'number' && Number.isFinite(value) + ? value + : undefined; + } + + private sanitizeCustomPreferences( + updates: DeepPartial, + ) { + if (!this.customPreferencesExtension) { + return {}; + } + + const result: CustomPreferencesRecord = {}; + + for (const field of this.customPreferencesExtension.fields) { + const value = updates[field.key]; + + if ( + value !== undefined && + this.isValidCustomPreferenceValue(field, value) + ) { + result[field.key] = value; + } + } + + return result; + } + /** * 保存偏好设置到缓存 - * @param preference - 要保存的偏好设置 */ - private saveToCache(preference: Preferences) { - this.cache.setItem(STORAGE_KEYS.MAIN, preference); - this.cache.setItem(STORAGE_KEYS.LOCALE, preference.app.locale); - this.cache.setItem(STORAGE_KEYS.THEME, preference.theme.mode); + private saveToCache() { + this.cache.setItem(STORAGE_KEYS.MAIN, this.state); + this.cache.setItem(STORAGE_KEYS.LOCALE, this.state.app.locale); + this.cache.setItem(STORAGE_KEYS.THEME, this.state.theme.mode); + + if (this.customPreferencesExtension) { + this.cache.setItem(STORAGE_KEYS.CUSTOM, { ...this.customState }); + return; + } + + this.cache.removeItem(STORAGE_KEYS.CUSTOM); } /** diff --git a/packages/@core/preferences/src/types.ts b/packages/@core/preferences/src/types.ts index ab331b5d6..50aefa6e0 100644 --- a/packages/@core/preferences/src/types.ts +++ b/packages/@core/preferences/src/types.ts @@ -17,6 +17,84 @@ import type { } from '@vben-core/typings'; type SupportedLanguagesType = 'en-US' | 'zh-CN'; +type CustomPreferencesValue = boolean | number | string; + +interface CustomPreferencesOption { + label: string; + value: TValue; +} + +interface BaseCustomPreferencesField< + TKey extends string = string, + TValue extends CustomPreferencesValue = CustomPreferencesValue, +> { + componentProps?: Record; + defaultValue: TValue; + disabled?: boolean; + key: TKey; + label: string; + placeholder?: string; + tip?: string; +} + +interface CustomPreferencesInputField< + TKey extends string = string, +> extends BaseCustomPreferencesField { + component: 'input'; +} + +interface CustomPreferencesNumberField< + TKey extends string = string, +> extends BaseCustomPreferencesField { + component: 'number'; +} + +interface CustomPreferencesSelectField< + TKey extends string = string, +> extends BaseCustomPreferencesField { + component: 'select'; + options: CustomPreferencesOption[]; +} + +interface CustomPreferencesSwitchField< + TKey extends string = string, +> extends BaseCustomPreferencesField { + component: 'switch'; +} + +type CustomPreferencesRecord = Record; + +type AnyCustomPreferencesField = + | CustomPreferencesInputField + | CustomPreferencesNumberField + | CustomPreferencesSelectField + | CustomPreferencesSwitchField; + +type CustomPreferencesField< + TCustomPreferences extends object = CustomPreferencesRecord, +> = + string extends Extract + ? AnyCustomPreferencesField + : { + [K in Extract< + keyof TCustomPreferences, + string + >]: TCustomPreferences[K] extends boolean + ? CustomPreferencesSwitchField + : TCustomPreferences[K] extends number + ? CustomPreferencesNumberField + : TCustomPreferences[K] extends string + ? CustomPreferencesInputField | CustomPreferencesSelectField + : never; + }[Extract]; + +interface PreferencesExtension< + TCustomPreferences extends object = CustomPreferencesRecord, +> { + fields: Array>; + tabLabel: string; + title?: string; +} interface AppPreferences { /** 权限模式 */ @@ -324,19 +402,33 @@ interface Preferences { type PreferencesKeys = keyof Preferences; -interface InitialOptions { +interface InitialOptions< + TCustomPreferences extends object = CustomPreferencesRecord, +> { + extension?: PreferencesExtension; namespace: string; overrides?: DeepPartial; } export type { + AnyCustomPreferencesField, AppPreferences, + BaseCustomPreferencesField, BreadcrumbPreferences, + CustomPreferencesField, + CustomPreferencesInputField, + CustomPreferencesNumberField, + CustomPreferencesOption, + CustomPreferencesRecord, + CustomPreferencesSelectField, + CustomPreferencesSwitchField, + CustomPreferencesValue, FooterPreferences, HeaderPreferences, InitialOptions, LogoPreferences, NavigationPreferences, Preferences, + PreferencesExtension, PreferencesKeys, ShortcutKeyPreferences, SidebarPreferences, diff --git a/packages/@core/preferences/src/use-preferences.ts b/packages/@core/preferences/src/use-preferences.ts index 0507d9617..e126cd9a8 100644 --- a/packages/@core/preferences/src/use-preferences.ts +++ b/packages/@core/preferences/src/use-preferences.ts @@ -7,7 +7,13 @@ import { isDarkTheme } from './update-css-variables'; function usePreferences() { const preferences = preferencesManager.getPreferences(); + const customPreferences = preferencesManager.getCustomPreferences(); const initialPreferences = preferencesManager.getInitialPreferences(); + const initialCustomPreferences = + preferencesManager.getInitialCustomPreferences(); + const preferencesExtension = computed(() => + preferencesManager.getPreferencesExtension(), + ); /** * @zh_CN 计算偏好设置的变化 */ @@ -15,6 +21,10 @@ function usePreferences() { return diff(initialPreferences, preferences); }); + const diffCustomPreference = computed(() => { + return diff(initialCustomPreferences, customPreferences); + }); + const appPreferences = computed(() => preferences.app); const shortcutKeysPreferences = computed(() => preferences.shortcutKeys); @@ -228,7 +238,9 @@ function usePreferences() { authPanelLeft, authPanelRight, contentIsMaximize, + customPreferences, diffPreference, + diffCustomPreference, globalLockScreenShortcutKey, globalLogoutShortcutKey, globalSearchShortcutKey, @@ -245,6 +257,7 @@ function usePreferences() { keepAlive, layout, locale, + preferencesExtension, preferencesButtonPosition, sidebarCollapsed, theme, diff --git a/packages/effects/layouts/src/widgets/preferences/blocks/custom/custom.vue b/packages/effects/layouts/src/widgets/preferences/blocks/custom/custom.vue new file mode 100644 index 000000000..2cfb8f0ba --- /dev/null +++ b/packages/effects/layouts/src/widgets/preferences/blocks/custom/custom.vue @@ -0,0 +1,121 @@ + + + diff --git a/packages/effects/layouts/src/widgets/preferences/blocks/index.ts b/packages/effects/layouts/src/widgets/preferences/blocks/index.ts index cdd6bb1db..b1b8eac93 100644 --- a/packages/effects/layouts/src/widgets/preferences/blocks/index.ts +++ b/packages/effects/layouts/src/widgets/preferences/blocks/index.ts @@ -1,4 +1,5 @@ export { default as Block } from './block.vue'; +export { default as Custom } from './custom/custom.vue'; export { default as Animation } from './general/animation.vue'; export { default as General } from './general/general.vue'; export { default as Breadcrumb } from './layout/breadcrumb.vue'; diff --git a/packages/effects/layouts/src/widgets/preferences/blocks/input-item.vue b/packages/effects/layouts/src/widgets/preferences/blocks/input-item.vue index bf9b03d1c..d07667721 100644 --- a/packages/effects/layouts/src/widgets/preferences/blocks/input-item.vue +++ b/packages/effects/layouts/src/widgets/preferences/blocks/input-item.vue @@ -16,10 +16,12 @@ withDefaults( disabled?: boolean; items?: SelectOption[]; placeholder?: string; + tip?: string; }>(), { disabled: false, placeholder: '', + tip: '', items: () => [], }, ); @@ -32,7 +34,7 @@ const slots = useSlots();