WEB/src/views/system/setting/encoding2/config/template-config.ts
2026-07-25 18:14:50 +08:00

728 lines
24 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.

/**
* 【页面模板】配置文件 v2 — 基于 waveOrder2 架构设计
*
* ===== 核心设计 =====
*
* 1. FIELD_DICT — 全局字段预设表,每个字段拥有唯一翻译(label)和完整元数据
* 2. VALUE_MAPS — 值翻译映射表(select options 和 tag 翻译共用)
* 3. TAG_RESOLVERS — 标签颜色解析器(集中管理 tag 颜色逻辑)
* 4. 各标签页通过 key 引用所需字段(scanBoxFieldKeys / tableColumnKeys)
* 5. resolveTabConfig() — 加载时将 key 列表展开为完整配置
*
* ===== 快速上手 =====
* 1. 复制整个 views/mode/ 文件夹,重命名为你的页面名
* 2. 在 FIELD_DICT 中添加你需要的字段定义
* 3. 在 tabPages 中配置标签页(引用 FIELD_DICT 的 key)
* 4. 在 TabPageApiConfig 中接入真实接口
* 5. 在 router/map.ts 中添加路由
*/
import type { Component } from 'vue'
import DetailPanel from './components/DetailPanel.vue'
import LogPanel from './components/LogPanel.vue'
// ============================================================
// 〇、全局页面配置
// ============================================================
export const PAGE_CONFIG = {
/** 是否显示顶部多标签栏 */
showTabArea: true,
/** 单页模式:不显示标签栏,仅一个标签页内容 */
singlePage: false,
/** 是否启用详情面板(底部分栏 + 显示/隐藏详情按钮),false 时表格占满全高 */
enableDetailPanel: true
}
// ============================================================
// 〇-A、组件注册表 — 所有可复用组件在此注册
// ============================================================
export const COMPONENT_REGISTRY: Record<string, Component> = {
DetailPanel,
LogPanel
}
// ============================================================
// 〇-B、SCANBOX_GROUPS — ScanBox 分组名称
// ============================================================
export const SCANBOX_GROUPS = {
basic: '基础信息',
process: '流程状态',
time: '时间范围',
custom: '自定义字段'
} as const
// ============================================================
// 一、FIELD_DICT — 全局字段预设表(唯一真相来源)
// ============================================================
// 每个字段拥有:
// label — 唯一翻译文本
// scanBox — ScanBox 渲染配置(type/options/group)
// table — 表格列配置(minWidth/fixed/align/sortable)
// slot — 单元格渲染配置(tag/tagResolver/translateField)
// detailLabel — 明细面板中的标签文本(可选,默认用 label)
// filterParamMap — ScanBox 筛选值 → API 传参值映射
export interface FieldDefinition {
key: string
label: string
scanBox: {
type: 'text' | 'select' | 'daterange' | 'number'
group?: string
options?: { label: string; value: any }[]
} | null
table: {
minWidth?: number
width?: number
fixed?: 'left' | 'right' | boolean
align?: 'left' | 'center' | 'right'
sortable?: boolean
showOverflowTooltip?: boolean
copyAction?: 'copy' | 'copyQr'
copyValue?: (row: any) => any
} | null
slot: {
type: 'tag' | 'text' | 'default' | 'operation'
tagType?: string | Record<string, string>
tagResolver?: string
translateField?: string
format?: 'datetime'
} | null
detailLabel?: string
filterParamMap?: Record<string, string>
}
// ============================================================
// VALUE_MAPS — 值翻译映射(select options 和 tag 翻译共用)
// ============================================================
export const VALUE_MAPS: Record<string, Record<string, string>> = {
status: { 'pending': '待处理', 'processing': '处理中', 'done': '已完成', '待处理': '待处理', '处理中': '处理中', '已完成': '已完成' },
type: { 'A': '类型A', 'B': '类型B', 'C': '类型C', '类型A': '类型A', '类型B': '类型B', '类型C': '类型C' },
bool: { '1': '是', '0': '否', '是': '是', '否': '否' }
}
/** 从 VALUE_MAPS 衍生 options(优先取中文值作为 option value) */
export function getOptions(field: string): { label: string; value: string }[] {
const map = VALUE_MAPS[field]
if (!map) return []
const seen = new Set<string>()
const opts: { label: string; value: string }[] = []
const chineseKeys: [string, string][] = []
const otherKeys: [string, string][] = []
for (const [v, l] of Object.entries(map)) {
if (/^[\u4e00-\u9fa5]/.test(v)) {
chineseKeys.push([v, l])
} else {
otherKeys.push([v, l])
}
}
for (const [v, l] of [...chineseKeys, ...otherKeys]) {
if (!seen.has(l)) {
seen.add(l)
opts.push({ label: l, value: v })
}
}
return opts
}
/** 翻译 value → label */
export function translate(field: string, value: any): string {
const map = VALUE_MAPS[field]
if (!map) return String(value ?? '—')
return map[String(value)] ?? String(value ?? '—')
}
/** 格式化时间戳为 YYYY-MM-DD HH:mm:ss */
export function formatTime(value: any): string {
if (!value) return '—'
try {
const d = new Date(value)
if (isNaN(d.getTime())) return String(value)
const pad = (n: number) => String(n).padStart(2, '0')
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`
} catch {
return String(value)
}
}
// ============================================================
// TAG_RESOLVERS — 标签颜色解析器
// ============================================================
// 颜色规则:未xx=info(灰) 已xx=success(绿) xx中/部分xx=warning(黄) 错误=danger(红)
export const TAG_RESOLVERS: Record<string, (val: any) => string> = {
resolveStatusTag(v) {
if (!v) return 'info'
if (v === '已完成' || v === 'done') return 'success'
if (v === '处理中' || v === 'processing') return 'warning'
return 'info'
},
resolveBoolTag(v) {
if (v === undefined || v === null) return 'info'
if (v === '是' || v === true || v === 1 || v === '1') return 'success'
return 'info'
}
}
// ============================================================
// 二、FIELD_DICT 实例 — 在此定义页面所需的所有字段
// ============================================================
export const FIELD_DICT: Record<string, FieldDefinition> = {
code: {
key: 'code',
label: '编号',
scanBox: { type: 'text', group: SCANBOX_GROUPS.basic },
table: { minWidth: 160, fixed: 'left', copyAction: 'copy', showOverflowTooltip: true },
slot: null,
detailLabel: '编号'
},
name: {
key: 'name',
label: '名称',
scanBox: { type: 'text', group: SCANBOX_GROUPS.basic },
table: { minWidth: 150, showOverflowTooltip: true },
slot: null,
detailLabel: '名称'
},
type: {
key: 'type',
label: '类型',
scanBox: { type: 'select', group: SCANBOX_GROUPS.basic, options: getOptions('type') },
table: { minWidth: 100, align: 'center' },
slot: { type: 'tag', tagType: 'info', translateField: 'type' },
detailLabel: '类型',
filterParamMap: { '类型A': 'A', '类型B': 'B', '类型C': 'C' }
},
status: {
key: 'status',
label: '状态',
scanBox: { type: 'select', group: SCANBOX_GROUPS.process, options: getOptions('status') },
table: { minWidth: 100, align: 'center' },
slot: { type: 'tag', tagResolver: 'resolveStatusTag', translateField: 'status' },
detailLabel: '状态',
filterParamMap: { '待处理': 'pending', '处理中': 'processing', '已完成': 'done' }
},
count: {
key: 'count',
label: '数量',
scanBox: null,
table: { minWidth: 80, align: 'center', sortable: true },
slot: null
},
amount: {
key: 'amount',
label: '金额(元)',
scanBox: null,
table: { minWidth: 110, align: 'center', sortable: true },
slot: null
},
creator: {
key: 'creator',
label: '创建人',
scanBox: { type: 'text', group: SCANBOX_GROUPS.basic },
table: { minWidth: 100 },
slot: null,
detailLabel: '创建人'
},
create_time: {
key: 'create_time',
label: '创建时间',
scanBox: { type: 'daterange', group: SCANBOX_GROUPS.time },
table: { minWidth: 170, sortable: true },
slot: { type: 'text', format: 'datetime' },
detailLabel: '创建时间'
},
update_time: {
key: 'update_time',
label: '更新时间',
scanBox: { type: 'daterange', group: SCANBOX_GROUPS.time },
table: { minWidth: 170, sortable: true },
slot: { type: 'text', format: 'datetime' },
detailLabel: '更新时间'
},
/** 操作列(虚拟字段,仅用于表格列渲染) */
operation: {
key: 'operation',
label: '操作',
scanBox: null,
table: { minWidth: 180, fixed: 'right', align: 'center' },
slot: { type: 'operation' }
}
}
// ============================================================
// 三、ColumnSlotConfig — 列单元格渲染配置
// ============================================================
export interface ColumnSlotConfig {
type: 'tag' | 'text' | 'default' | 'operation'
tagType?: string | Record<string, string>
tagResolver?: string
translateField?: string
format?: 'datetime'
}
// ============================================================
// 三-A、OperationButtonConfig — 操作列按钮配置
// ============================================================
export interface OperationButtonConfig {
key: string
label: string
type?: 'primary' | 'success' | 'warning' | 'danger' | 'info' | ''
actionType: 'form' | 'action'
formKey?: string
formTitle?: string
formWidth?: string
paramMap?: Record<string, string>
extraParams?: Record<string, any>
disabledOnField?: string
confirmMessage?: string
confirmTitle?: string
confirmType?: 'warning' | 'danger' | 'info'
confirmButtonText?: string
}
// ============================================================
// 四、DetailFieldConfig / DetailSectionConfig — 明细面板配置
// ============================================================
export interface DetailFieldConfig {
key: string
label?: string
span?: number
renderType?: 'text' | 'tag' | 'pre'
tagType?: string | Record<string, string>
tagResolver?: string
translateField?: string
}
export interface DetailSectionConfig {
title: string
columnCount: number
fields: DetailFieldConfig[]
}
export interface DetailTabConfig {
name: string
label: string
componentKey: string
component?: Component
}
// ============================================================
// 五、TabPageApiConfig — 标签页接口插槽配置
// ============================================================
export type ApiMethod = (...args: any[]) => Promise<any>
export type ApiSource = 'api' | 'list'
export type ComponentApiConfig = { source: 'list' } | ApiMethod
export interface TabPageApiConfig {
/** 列表查询接口 */
list: ApiMethod
/** 明细面板接口(可选,不配则用 row 数据) */
detail?: ComponentApiConfig
/** 操作日志接口(可选) */
log?: ComponentApiConfig
/** 导出接口(可选) */
export?: ApiMethod
/** 导出进度查询接口(可选) */
exportProgress?: ApiMethod
/** ScanBox 下拉选项数据源接口(可选) */
scanBoxOptions?: Record<string, ApiMethod>
/** 工具栏按钮 → API 方法映射(可选) */
toolbar?: Record<string, ApiMethod>
/** 列表响应解析器 */
parseListResponse?: (res: any) => { list: any[]; total: number }
/** 构建列表请求参数 */
buildListParams?: (params: {
pagination: { page: number; pageSize: number }
conditions: Record<string, any>
sort?: { prop: string; order: string }
}) => Record<string, any>
}
// ============================================================
// 六、TabPageRawConfig — 标签页声明配置(仅用 key 引用)
// ============================================================
export interface TabPageRawConfig {
name: string
label: string
scanBoxCacheKey: string
/** ScanBox 需要的字段 key 列表(从 FIELD_DICT 中查找) */
scanBoxFieldKeys: string[]
/** 表格需要的列 key 列表(从 FIELD_DICT 中查找) */
tableColumnKeys: string[]
upperTableDefaults: {
title: string
enableColumnConfig?: boolean
showIndex?: boolean
showSelection?: boolean
emptyText?: string
}
/** 明细面板标签页配置 */
detailTabs?: { name: string; label: string; componentKey: string }[]
/** 明细面板分区配置(字段 key 列表,resolveTabConfig 展开) */
detailSections: {
title: string
columnCount: number
fieldKeys: string[]
}[]
/** 接口配置(有 api 时启用真实接口) */
api?: TabPageApiConfig
/** 操作列按钮配置(需 tableColumnKeys 包含 'operation') */
operationButtons?: OperationButtonConfig[]
}
// ============================================================
// 七、TabPageConfig — 展开后的完整配置(给 index.vue 使用)
// ============================================================
export interface TabPageConfig {
name: string
label: string
scanBoxCacheKey: string
scanBoxFields: Record<string, any>[]
upperTable: {
title: string
enableColumnConfig: boolean
showIndex: boolean
showSelection: boolean
emptyText: string
columns: Record<string, any>[]
}
columnSlots: Record<string, ColumnSlotConfig>
detailConfig: DetailSectionConfig[]
detailTabs: DetailTabConfig[]
api?: TabPageApiConfig
operationButtons?: OperationButtonConfig[]
}
// ============================================================
// 八、resolveTabConfig — 加载时将 RawConfig 展开为完整配置
// ============================================================
export function resolveTabConfig(raw: TabPageRawConfig): TabPageConfig {
// 展开 ScanBox 字段
const scanBoxFields: Record<string, any>[] = []
for (const key of raw.scanBoxFieldKeys) {
const def = FIELD_DICT[key]
if (!def || !def.scanBox) continue
scanBoxFields.push({
label: def.label,
value: def.key,
type: def.scanBox.type,
options: def.scanBox.options ? [...def.scanBox.options] : undefined,
group: def.scanBox.group,
required: (def.scanBox as any).required
})
}
// 展开表格列
const columns: Record<string, any>[] = []
for (const key of raw.tableColumnKeys) {
const def = FIELD_DICT[key]
if (!def || !def.table) continue
columns.push({
prop: def.key,
label: def.label,
...def.table
})
}
// 展开列插槽
const columnSlots: Record<string, ColumnSlotConfig> = {}
for (const key of raw.tableColumnKeys) {
const def = FIELD_DICT[key]
if (!def || !def.slot) continue
columnSlots[def.key] = { ...def.slot }
}
// 展开明细面板配置
const detailConfig: DetailSectionConfig[] = raw.detailSections.map((sec) => ({
title: sec.title,
columnCount: sec.columnCount,
fields: sec.fieldKeys
.map((key): DetailFieldConfig | null => {
const def = FIELD_DICT[key]
if (!def) return null
return {
key: def.key,
label: def.detailLabel ?? def.label,
translateField: def.slot?.translateField,
tagResolver: def.slot?.tagResolver,
tagType: def.slot?.tagType,
renderType: def.slot?.type === 'tag' ? 'tag' : 'text'
}
})
.filter((f): f is DetailFieldConfig => f !== null)
}))
// 展开明细标签页(解析 componentKey → Component)
const detailTabs: DetailTabConfig[] = raw.detailTabs
? raw.detailTabs.map((tab) => ({
name: tab.name,
label: tab.label,
componentKey: tab.componentKey,
component: COMPONENT_REGISTRY[tab.componentKey]
}))
: [{ name: 'detail', label: '明细', componentKey: 'DetailPanel', component: COMPONENT_REGISTRY['DetailPanel'] }]
return {
name: raw.name,
label: raw.label,
scanBoxCacheKey: raw.scanBoxCacheKey,
scanBoxFields,
upperTable: {
title: raw.upperTableDefaults.title,
enableColumnConfig: raw.upperTableDefaults.enableColumnConfig ?? true,
showIndex: raw.upperTableDefaults.showIndex ?? true,
showSelection: raw.upperTableDefaults.showSelection ?? true,
emptyText: raw.upperTableDefaults.emptyText ?? '暂无数据',
columns
},
columnSlots,
detailConfig,
detailTabs,
api: raw.api,
operationButtons: raw.operationButtons
}
}
// ============================================================
// 九、buildWhereConditions — 将 ScanBox 条件转为 API where 参数
// ============================================================
export function buildWhereConditions(rawConditions: Record<string, any>): Record<string, any> {
const where: Record<string, any> = {}
for (const [key, cond] of Object.entries(rawConditions || {})) {
let value: any = undefined
if (cond && typeof cond === 'object' && 'operator' in cond) {
value = (cond as any).value
} else if (cond !== undefined && cond !== null && cond !== '') {
value = Array.isArray(cond) ? cond[0] ?? '' : cond
}
if (value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0)) {
continue
}
const def = FIELD_DICT[key]
if (def?.filterParamMap) {
const mapped = def.filterParamMap[String(value)]
if (mapped !== undefined) {
where[key] = mapped
continue
}
}
where[key] = value
}
return where
}
// ============================================================
// 十、工具栏按钮系统
// ============================================================
// 按钮分为三类:
// common — 公共按钮(刷新、导出)
// function — 功能按钮(打开表单/确认窗口)
// basic — 基础操作(字段设置、隐藏详情)
export interface ToolbarButtonConfig {
key: string
label: string
category: 'common' | 'function' | 'basic'
size?: '' | 'default' | 'small' | 'large'
type?: '' | 'primary' | 'success' | 'warning' | 'info' | 'danger'
plain?: boolean
loadingKey?: string
disabledKey?: string
action: string
dynamicLabelKey?: string
onlyForTabs?: string[]
buttonType?: 'default' | 'dropdown'
dropdownOptions?: Array<{ label: string; action: string; divided?: boolean }>
formKey?: string
}
export const TOOLBAR_BUTTONS: Record<string, ToolbarButtonConfig> = {
// ===== 公共按钮 =====
refresh: {
key: 'refresh',
label: '刷新',
category: 'common',
type: 'primary',
size: 'small',
loadingKey: 'loading',
action: 'loadData'
},
export: {
key: 'export',
label: '导出',
category: 'common',
size: 'small',
loadingKey: 'exportLoading',
action: 'handleExport',
buttonType: 'dropdown',
dropdownOptions: [
{ label: '不含明细', action: 'handleExport' },
{ label: '含明细', action: 'handleExportItem', divided: true }
]
},
// ===== 基础操作 =====
columnConfig: {
key: 'columnConfig',
label: '字段设置',
category: 'basic',
size: 'small',
action: 'openColumnConfigPanel'
},
toggleDetail: {
key: 'toggleDetail',
label: '显示详情',
category: 'basic',
dynamicLabelKey: 'detailToggleLabel',
size: 'small',
action: 'toggleDetailVisible'
}
// ★ 在此添加功能按钮(如批量操作)★
}
/** 按标签页名称获取工具栏按钮列表(自动根据 PAGE_CONFIG 过滤) */
export function getTabToolbarButtons(tabName: string): ToolbarButtonConfig[] {
return Object.values(TOOLBAR_BUTTONS).filter((btn) => {
if (btn.onlyForTabs && !btn.onlyForTabs.includes(tabName)) return false
// 详情面板禁用时,隐藏「显示/隐藏详情」按钮
if (!PAGE_CONFIG.enableDetailPanel && btn.key === 'toggleDetail') return false
return true
})
}
// ============================================================
// 十一、批量操作配置(可选,接入 BatchOperationForm 时使用)
// ============================================================
export interface BatchOperationConfig {
action: string
title: string
confirmText: string
confirmType?: 'warning' | 'error' | 'info' | 'success'
confirmButtonText: string
successText: string
failText: string
apiMethod: (...args: any[]) => Promise<any>
payloadKey?: string
idField?: string | string[]
payloadBuilder?: (rows: Record<string, any>[]) => Record<string, any>
useProgress?: boolean
progressApiMethod?: (...args: any[]) => Promise<any>
}
/** ★ 在此配置批量操作 */
export const BATCH_OPERATION_CONFIGS: Record<string, BatchOperationConfig> = {
// batchExample: {
// action: 'batchExample',
// title: '批量操作示例',
// confirmText: '确定对选中的 {count} 项执行操作吗?',
// confirmType: 'warning',
// confirmButtonText: '确认操作',
// successText: '批量操作成功',
// failText: '批量操作失败',
// apiMethod: yourBatchApi,
// payloadKey: 'ids',
// idField: 'id'
// }
}
// ============================================================
// 十二、标签页注册表 — 在此定义你的页面标签页
// ============================================================
export const tabPages: TabPageRawConfig[] = [
// ===== 示例标签页一 =====
{
name: 'tab1',
label: '标签页一',
scanBoxCacheKey: 'template-tab1',
scanBoxFieldKeys: ['code', 'type', 'status', 'creator', 'create_time'],
tableColumnKeys: ['code', 'name', 'type', 'status', 'count', 'amount', 'creator', 'create_time', 'operation'],
upperTableDefaults: {
title: '示例列表一',
showSelection: true
},
detailTabs: [
{ name: 'detail', label: '明细', componentKey: 'DetailPanel' },
{ name: 'log', label: '操作日志', componentKey: 'LogPanel' }
],
detailSections: [
{
title: '基础信息',
columnCount: 3,
fieldKeys: ['code', 'name', 'type', 'status', 'count', 'amount', 'creator']
},
{
title: '时间信息',
columnCount: 2,
fieldKeys: ['create_time', 'update_time']
}
],
/** ★ 接入真实接口时取消注释 */
// api: {
// list: yourListApi,
// detail: { source: 'list' },
// parseListResponse(res) {
// return { list: res.data?.list ?? [], total: res.data?.pagination?.total ?? 0 }
// },
// buildListParams({ pagination, conditions, sort }) {
// return {
// page: pagination.page,
// pageSize: pagination.pageSize,
// where: buildWhereConditions(conditions),
// ...(sort?.prop ? { sortField: sort.prop, sortOrder: sort.order === 'ascending' ? 'ASC' : 'DESC' } : {})
// }
// }
// },
operationButtons: [
{
key: 'viewDetail',
label: '查看详情',
actionType: 'action',
type: 'primary'
},
{
key: 'edit',
label: '编辑',
actionType: 'action',
type: 'warning'
}
]
},
// ===== 示例标签页二 =====
{
name: 'tab2',
label: '标签页二',
scanBoxCacheKey: 'template-tab2',
scanBoxFieldKeys: ['code', 'status', 'create_time'],
tableColumnKeys: ['code', 'name', 'status', 'count', 'creator', 'create_time', 'operation'],
upperTableDefaults: {
title: '示例列表二',
showSelection: true
},
detailSections: [
{
title: '基础信息',
columnCount: 3,
fieldKeys: ['code', 'name', 'status', 'count', 'creator']
},
{
title: '时间信息',
columnCount: 2,
fieldKeys: ['create_time', 'update_time']
}
],
operationButtons: [
{
key: 'viewDetail',
label: '查看详情',
actionType: 'action',
type: 'primary'
}
]
}
]
// ============================================================
// 十三、向后兼容导出
// ============================================================
export const templateTabs = tabPages.map((t) => ({ name: t.name, label: t.label, scanBoxCacheKey: t.scanBoxCacheKey }))