WEB/src/composables/useTabOrder.ts
yin f41b37aa54 feat(tab-order): 统一标签排序与默认页签配置,构建按需引入 Element Plus/ECharts
- 新增 useTabOrder、tab-order 工具与 tab-order-registry 注册表,按模块集中登记
  页面标签并懒加载默认标签;新增 TabOrderSettingsDialog、TabOrderDragList,
  支持拖拽排序、设置默认页签与重置,SortSettingDialog / TabArea 迁移到同一套实现
- 用户偏好存储新增「用户级」globalMap(不随仓库隔离),tabOrder 写入用户级 scope,
  旧 scope 一次性迁移并对齐回退读取;各页面 config 接入统一注册表,
  移除页面内自写的排序与默认页签逻辑
- 新增 tbyc-config 统一配置文件与分区注册表,UpperTable 的配置导出/导入
  升级为 tbyc-config.json(字段列、标签排序、界面显示、快捷键),
  兼容旧版「全局字段配置」与 tabOrders 文件
- Element Plus 改为 unplugin-vue-components 按需自动引入,移除
  app.use(ElementPlus)、dts 生成与强制 vendor-element-plus 分包
- ECharts 改为按需注册(折线/饼图 + 所需组件),dashboard 图表统一走
  @/utils/echarts;移除 three.js 及 overlookControls / threeScene / threeUtils,
  同步清理依赖、manualChunks 与 optimizeDeps
- vue-devtools 支持 VITE_VUE_DEVTOOLS=off 关闭;抽离 wavePrintPayload 供订单、
  复核页面复用,scanFields 承接批量搜索操作符与「包含商品」筛选项
- 补充标签排序与默认页签统一方案、tbyc-config 说明文档,
  更新标签页性能测量结论与用户偏好保存方案
2026-11-07 18:00:11 +08:00

182 lines
6.3 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
* useTabOrder — 标签排序 / 默认页签的唯一实现
*
* 页面接入示例:
* const { orderedTabs, defaultTabName, resolveInitialTab, saveOrder, setDefault, reset } =
* useTabOrder('order.management', () => tabList.value, { legacyScopes: ['order.tabs.order'] })
*
* 读取优先级:
* 1. 新文档(userPreference 用户级 scope `tabOrder`)
* 2. 旧 scope(legacyScopes,命中后一次性迁移进新文档)
* 3. 传入的默认顺序(tabs 原顺序)
*
* 初始激活页签优先级:
* URL ?tab=(合法时) > 用户默认 > 页面兜底默认 > 排序后第一项
*/
import { computed, inject, onMounted, provide, watch, type ComputedRef, type InjectionKey } from 'vue'
import { useUserPreferenceStore } from '@/stores/modules/userPreference'
import {
applyTabOrder,
isValidTabName,
normalizeTabOrder,
readTabOrderDoc,
updateTabOrderDoc,
type TabOption
} from '@/utils/tab-order'
/** 页面 key 注入键:字段设置里的「标签排序」用它高亮当前页 */
export const TAB_ORDER_PAGE_KEY: InjectionKey<ComputedRef<string>> = Symbol('tabOrderPageKey')
export interface UseTabOrderOptions {
/** 旧配置 scope(按顺序尝试;命中的顺序会在挂载时迁移到新文档) */
legacyScopes?: string[] | (() => string[])
/** 页面级默认标签兜底(用户未设置默认时使用;返回空则用排序后第一项) */
fallbackTabName?: string | (() => string | undefined)
/** 是否把 pageKey provide 给后代(默认开启,供字段设置高亮当前页) */
provideKey?: boolean
}
type ValueOrGetter<T> = T | (() => T)
function resolveValue<T>(input: ValueOrGetter<T> | { value: T }): T {
const raw: any = input
if (typeof raw === 'function') return raw() as T
if (raw && typeof raw === 'object' && 'value' in raw) return raw.value as T
return raw as T
}
export function useTabOrder(
pageKey: ValueOrGetter<string> | ComputedRef<string>,
tabs: () => TabOption[],
options: UseTabOrderOptions = {}
) {
const pref = useUserPreferenceStore()
const key = computed(() => String(resolveValue(pageKey) || ''))
/** 响应式文档:store 变更后所有页面立即重排(字段设置里保存即生效) */
const doc = computed(() => readTabOrderDoc())
/** 旧配置顺序(兼容读取) */
const legacyOrder = computed<string[]>(() => {
const scopes = resolveValue<string[]>(options.legacyScopes ?? [])
if (!Array.isArray(scopes) || !scopes.length) return []
for (const scope of scopes) {
const value = pref.get(scope) ?? pref.getGlobal(scope)
if (Array.isArray(value) && value.length) {
return value.filter((name): name is string => typeof name === 'string' && !!name)
}
}
return []
})
/** 当前生效的 name 顺序(自定义 → 旧配置 → 空表示默认顺序) */
const savedOrder = computed<string[]>(() => {
const explicit = doc.value.orders[key.value]
if (Array.isArray(explicit) && explicit.length) return explicit
return legacyOrder.value
})
/** 排序后的标签(保留原始对象,页面自定义字段如 count 不丢) */
const orderedTabs = computed<TabOption[]>(() => {
const list = tabs()
if (!savedOrder.value.length) return list
return applyTabOrder(savedOrder.value, list)
})
/** 用户设置的默认标签(非法时返回空串) */
const userDefaultTab = computed(() => {
const name = doc.value.defaults[key.value]
return isValidTabName(name, tabs()) ? String(name) : ''
})
/** 页面兜底默认(未设置或已失效时使用) */
const fallbackTab = computed(() => {
const name = resolveValue<string | undefined>(options.fallbackTabName ?? '')
return isValidTabName(name, tabs()) ? String(name) : ''
})
/** 最终默认标签:用户默认 → 页面兜底 → 排序后第一项 */
const defaultTabName = computed(
() => userDefaultTab.value || fallbackTab.value || orderedTabs.value[0]?.name || ''
)
/** 是否被用户自定义过(顺序或默认) */
const isCustomized = computed(
() => !!doc.value.orders[key.value]?.length || !!doc.value.defaults[key.value]
)
/** 解析初始激活标签:合法 URL tab 优先,其次默认标签 */
function resolveInitialTab(urlTab?: string | null): string {
const raw = urlTab === undefined || urlTab === null ? '' : String(urlTab).trim()
if (raw && isValidTabName(raw, tabs())) return raw
return defaultTabName.value
}
/** 保存顺序(自动剔除非法项、补齐缺失项) */
function saveOrder(order: unknown): string[] {
const normalized = normalizeTabOrder(order, tabs())
updateTabOrderDoc((draft) => {
draft.orders[key.value] = normalized
})
return normalized
}
/** 设置默认标签;传空表示清除 */
function setDefault(name: string | null): void {
updateTabOrderDoc((draft) => {
if (!name || !isValidTabName(name, tabs())) {
delete draft.defaults[key.value]
return
}
draft.defaults[key.value] = name
})
}
/** 恢复默认(同时清除顺序与默认标签) */
function reset(): void {
updateTabOrderDoc((draft) => {
delete draft.orders[key.value]
delete draft.defaults[key.value]
})
}
/**
* 旧配置一次性迁移:新文档无该页配置、但旧 scope 有值时,写入新文档。
* 旧 key 不删除(便于回滚);迁移后「恢复默认」才会真正回到默认顺序。
*/
function seedLegacyIfNeeded() {
if (!key.value) return
if (doc.value.orders[key.value]?.length) return
if (!legacyOrder.value.length) return
updateTabOrderDoc((draft) => {
draft.orders[key.value] = normalizeTabOrder(legacyOrder.value, tabs())
})
}
if (options.provideKey !== false) provide(TAB_ORDER_PAGE_KEY, key)
onMounted(seedLegacyIfNeeded)
watch(key, () => seedLegacyIfNeeded())
return {
pageKey: key,
orderedTabs,
savedOrder,
defaultTabName,
userDefaultTab,
isCustomized,
resolveInitialTab,
saveOrder,
setDefault,
reset,
seedLegacyIfNeeded
}
}
/** 供 UpperTable 等后代组件读取当前页面 key(无注入时返回空串) */
export function injectTabOrderPageKey(): string {
const key = inject(TAB_ORDER_PAGE_KEY, null)
return key?.value || ''
}