create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/components/AppTable/engine/table/layout/nestedHeaders.ts

@@ -0,0 +1,271 @@
+/** 基于 Handsontable 公共 API 的嵌套表头布局合同。 */
+import type {
+  NestedHeader,
+  NestedHeaderSettings,
+} from 'handsontable/plugins/nestedHeaders'
+
+export type TableHeaderVisibility = NonNullable<
+  NestedHeaderSettings['visibleWhen']
+>
+
+export interface TableHeaderLeaf {
+  /** 引用的稳定业务列 key。 */
+  key: string
+  /** 仅在当前分组表头中覆盖列标题。 */
+  label?: string
+  /** 追加到该叶子表头的样式类。 */
+  headerClassName?: string
+  /** Handsontable v18 条件可见性设置。 */
+  visibleWhen?: TableHeaderVisibility
+}
+
+export interface TableHeaderGroup {
+  /** 分组表头显示文案。 */
+  label: string
+  /** 子列 key、叶子覆盖项或继续嵌套的子分组。 */
+  children: Array<string | TableHeaderLeaf | TableHeaderGroup>
+  /** 追加到分组表头的样式类。 */
+  headerClassName?: string
+  /** Handsontable v18 条件可见性设置。 */
+  visibleWhen?: TableHeaderVisibility
+  /** 为当前分组启用 v18 官方 CollapsibleColumns 控件。 */
+  collapsible?: boolean
+}
+
+interface TableNestedHeaderColumn {
+  /** 稳定业务列 key。 */
+  key: string
+  /** 当前业务列标题。 */
+  label: string
+  /** false 表示该列不参与本次嵌套表头编译。 */
+  visible?: boolean
+}
+
+export interface TableNestedHeadersResult {
+  nestedHeaders: NestedHeader[][]
+  collapsibleColumns:
+    | false
+    | Array<{ row: number; col: number; collapsible: true }>
+}
+
+interface BuildTableNestedHeadersOptions {
+  columns: readonly TableNestedHeaderColumn[]
+  groups: readonly TableHeaderGroup[]
+  selectionLabel?: string
+}
+
+class TableNestedHeadersConfigError extends Error {
+  readonly code = 'TABLE_NESTED_HEADERS_CONFIG_INVALID'
+
+  constructor(message: string) {
+    super(`[TableComponent] ${message}`)
+    this.name = 'TableNestedHeadersConfigError'
+  }
+}
+
+interface ResolvedLeaf {
+  type: 'leaf'
+  key: string
+  label: string
+  headerClassName?: string
+  visibleWhen?: TableHeaderVisibility
+}
+
+interface ResolvedGroup {
+  type: 'group'
+  label: string
+  children: ResolvedNode[]
+  headerClassName?: string
+  visibleWhen?: TableHeaderVisibility
+  collapsible: boolean
+}
+
+type ResolvedNode = ResolvedLeaf | ResolvedGroup
+
+const leafKeys = (node: ResolvedNode): string[] =>
+  node.type === 'leaf'
+    ? [node.key]
+    : node.children.flatMap((child) => leafKeys(child))
+
+const nodeDepth = (node: ResolvedNode): number =>
+  node.type === 'leaf'
+    ? 1
+    : 1 + Math.max(...node.children.map((child) => nodeDepth(child)))
+
+const containsConditionalVisibility = (node: ResolvedNode): boolean =>
+  Boolean(node.visibleWhen) ||
+  (node.type === 'group' &&
+    node.children.some((child) => containsConditionalVisibility(child)))
+
+const configuredLeaf = (value: string | TableHeaderLeaf): TableHeaderLeaf =>
+  typeof value === 'string' ? { key: value } : value
+
+export const buildTableNestedHeaders = (
+  options: BuildTableNestedHeadersOptions
+): TableNestedHeadersResult | undefined => {
+  if (!options.groups.length) return undefined
+
+  const columns = new Map(options.columns.map((column) => [column.key, column]))
+  const visibleColumns = options.columns.filter(
+    (column) => column.visible !== false
+  )
+  const visibleIndex = new Map(
+    visibleColumns.map((column, index) => [column.key, index])
+  )
+  const claimedKeys = new Set<string>()
+
+  const resolveNode = (
+    value: string | TableHeaderLeaf | TableHeaderGroup
+  ): ResolvedNode | undefined => {
+    if (typeof value === 'string' || 'key' in value) {
+      const leaf = configuredLeaf(value)
+      const column = columns.get(leaf.key)
+      if (!column) {
+        throw new TableNestedHeadersConfigError(
+          `Nested header references unknown column key "${leaf.key}".`
+        )
+      }
+      if (claimedKeys.has(leaf.key)) {
+        throw new TableNestedHeadersConfigError(
+          `Nested header column key "${leaf.key}" is declared more than once.`
+        )
+      }
+      claimedKeys.add(leaf.key)
+      if (column.visible === false) return undefined
+      return {
+        type: 'leaf',
+        key: leaf.key,
+        label: leaf.label ?? column.label,
+        headerClassName: leaf.headerClassName,
+        visibleWhen: leaf.visibleWhen,
+      }
+    }
+
+    const children = value.children.flatMap((child) => {
+      const resolved = resolveNode(child)
+      return resolved ? [resolved] : []
+    })
+    if (!children.length) return undefined
+    return {
+      type: 'group',
+      label: value.label,
+      children,
+      headerClassName: value.headerClassName,
+      visibleWhen: value.visibleWhen,
+      collapsible:
+        value.collapsible === true ||
+        children.some((child) => containsConditionalVisibility(child)),
+    }
+  }
+
+  const groups = options.groups.flatMap((group) => {
+    const resolved = resolveNode(group)
+    return resolved?.type === 'group' ? [resolved] : []
+  })
+
+  const starts = new Map<number, ResolvedGroup>()
+  const covered = new Set<string>()
+  groups.forEach((group) => {
+    const keys = leafKeys(group)
+    const indices = keys.map((key) => visibleIndex.get(key))
+    if (indices.some((index) => index === undefined)) return
+    const start = indices[0]!
+    const contiguous = indices.every(
+      (index, offset) => index === start + offset
+    )
+    if (!contiguous) {
+      throw new TableNestedHeadersConfigError(
+        `Group "${group.label}" columns must stay contiguous and in visible column order.`
+      )
+    }
+    starts.set(start, group)
+    keys.forEach((key) => covered.add(key))
+  })
+
+  const forest: ResolvedNode[] = []
+  if (options.selectionLabel) {
+    forest.push({
+      type: 'leaf',
+      key: '__tableSelection',
+      label: options.selectionLabel,
+    })
+  }
+  for (let index = 0; index < visibleColumns.length; index += 1) {
+    const group = starts.get(index)
+    if (group) {
+      forest.push(group)
+      index += leafKeys(group).length - 1
+      continue
+    }
+    const column = visibleColumns[index]
+    if (!covered.has(column.key)) {
+      forest.push({
+        type: 'leaf',
+        key: column.key,
+        label: column.label,
+      })
+    }
+  }
+
+  const depth = Math.max(...forest.map((node) => nodeDepth(node)))
+  const nestedHeaders: NestedHeader[][] = Array.from(
+    { length: depth },
+    (): NestedHeader[] => []
+  )
+  const collapsibleColumns: Array<{
+    row: number
+    col: number
+    collapsible: true
+  }> = []
+
+  const render = (node: ResolvedNode, level: number, column: number) => {
+    if (node.type === 'leaf') {
+      const rowspan = depth - level
+      nestedHeaders[level].push({
+        label: node.label,
+        ...(rowspan > 1 ? { rowspan } : {}),
+        ...(node.headerClassName
+          ? { headerClassName: node.headerClassName }
+          : {}),
+        ...(node.visibleWhen ? { visibleWhen: node.visibleWhen } : {}),
+      })
+      for (let row = level + 1; row < depth; row += 1) {
+        nestedHeaders[row].push('')
+      }
+      return
+    }
+
+    const colspan = leafKeys(node).length
+    nestedHeaders[level].push({
+      label: node.label,
+      colspan,
+      ...(node.headerClassName
+        ? { headerClassName: node.headerClassName }
+        : {}),
+      ...(node.visibleWhen ? { visibleWhen: node.visibleWhen } : {}),
+    })
+    if (node.collapsible && colspan > 1) {
+      collapsibleColumns.push({
+        row: level - depth,
+        col: column,
+        collapsible: true,
+      })
+    }
+    let childColumn = column
+    node.children.forEach((child) => {
+      render(child, level + 1, childColumn)
+      childColumn += leafKeys(child).length
+    })
+  }
+
+  let column = 0
+  forest.forEach((node) => {
+    render(node, 0, column)
+    column += leafKeys(node).length
+  })
+
+  return {
+    nestedHeaders,
+    collapsibleColumns: collapsibleColumns.length ? collapsibleColumns : false,
+  }
+}

package/template/src/components/AppTable/engine/table/layout/types.ts

@@ -0,0 +1,10 @@
+import type { TableKeyOf, TableRow } from '../../shared/types'
+
+export interface TableAutoMergeConfig<T extends TableRow = TableRow> {
+  /** 按父级到子级分组顺序排列的稳定列键。 */
+  columns: Array<TableKeyOf<T>>
+  /** 默认为 true，防止子级值跨父级分组合并。 */
+  hierarchical?: boolean
+  /** 是否合并连续空值，默认 false。 */
+  mergeEmpty?: boolean
+}

package/template/src/components/AppTable/engine/toolbar/index.ts

@@ -0,0 +1 @@
+export * from './types'

package/template/src/components/AppTable/engine/toolbar/types.ts

@@ -0,0 +1,56 @@
+import type { SelectionState } from '../selection/selection'
+import type { TableRow } from '../shared/types'
+
+export interface TableToolbarDropdownItem<T extends TableRow = TableRow> {
+  /** 下拉项稳定 key；省略时由调用位置生成。 */
+  key?: string
+  /** 下拉项显示文案。 */
+  label: string
+  /** 下拉项 Iconify 图标名称。 */
+  icon?: string
+  /** 静态或按当前选择状态计算的禁用状态。 */
+  disabled?: boolean | ((rows: T[], selection: SelectionState<T>) => boolean)
+  /** 点击下拉项时执行的业务回调。 */
+  onClick: (rows: T[], selection: SelectionState<T>) => void | Promise<void>
+}
+
+interface TableToolbarButtonBase<T extends TableRow = TableRow> {
+  /** 工具栏按钮稳定唯一 key。 */
+  key: string
+  /** 按钮显示文案。 */
+  label: string
+  /** Iconify 图标名称，例如 ri:add-line；engine 只保存字符串，不依赖 React 组件。 */
+  icon?: string
+  /** 工具栏按钮语义色。 */
+  type?: 'primary' | 'success' | 'warning' | 'danger' | 'info'
+  /** 静态或根据当前选择状态计算的禁用状态。 */
+  disabled?: boolean | ((rows: T[], selection: SelectionState<T>) => boolean)
+  /** 静态或根据当前选择状态计算的隐藏状态。 */
+  hidden?: boolean | ((rows: T[], selection: SelectionState<T>) => boolean)
+  /** 是否显示按钮加载状态。 */
+  loading?: boolean
+}
+
+/** 普通按钮必须有 onClick；下拉按钮必须至少有一个可执行菜单项。 */
+export type TableToolbarButton<T extends TableRow = TableRow> =
+  TableToolbarButtonBase<T> &
+    (
+      | {
+          /** 点击普通按钮时执行的业务动作。 */
+          onClick: (
+            rows: T[],
+            selection: SelectionState<T>
+          ) => void | Promise<void>
+          /** 普通按钮不能同时声明下拉菜单。 */
+          dropdown?: never
+        }
+      | {
+          /** 至少包含一个可执行项的下拉菜单。 */
+          dropdown: readonly [
+            TableToolbarDropdownItem<T>,
+            ...TableToolbarDropdownItem<T>[],
+          ]
+          /** 下拉按钮由菜单项处理点击，不接受按钮级 onClick。 */
+          onClick?: never
+        }
+    )

package/template/src/components/AppTable/index.ts

@@ -0,0 +1,11 @@
+export { AppTable } from './AppTable'
+export { fnCreateSensitiveDataTableColumn } from './sensitiveData'
+export type { TableConfiguration } from './config'
+export type {
+  IAppTableMessages,
+  ICreateSensitiveDataTableColumnOptions,
+  TableSensitiveDataColumnBase,
+} from './config'
+export type { TableCellContext } from './engine/cell/types'
+export type { TableRow } from './engine/shared/types'
+export type { TableHeight } from './engine/table/layout/height'

package/template/src/components/AppTable/messages.ts

@@ -0,0 +1,256 @@
+import { createContext, useContext } from 'react'
+import type { TAppLocale } from '@/locale'
+import type { IAppTableMessages } from './config'
+import { TABLE_ENGINE_MESSAGES_ZH_CN } from './engine/shared/messages'
+
+/** AppTable 内建中英文文案。 */
+export const objAppTableMessages: Readonly<
+  Record<TAppLocale, IAppTableMessages>
+> = Object.freeze({
+  'en-US': Object.freeze({
+    strFormulaRequired: 'Formula cannot be empty',
+    strFormulaTooLong: 'Formula cannot exceed 256 characters',
+    strFormulaParentheses: 'Formula parentheses do not match',
+    fnFormulaInvalidCharacter: (nPosition) =>
+      `Formula is invalid at character ${nPosition}`,
+    strFormulaExponentRange: 'Formula exponent is out of range',
+    strFormulaPowerRange:
+      'Formula power must be an integer between -100 and 100',
+    strFormulaDivisionByZero: 'Formula cannot divide by zero',
+    strFormulaResultRange: 'Formula result is out of range',
+    strFormulaUnsafeNumber:
+      'Formula result cannot be safely converted to number',
+    strInvalidDateFormat: 'Enter a valid date in YYYY-MM-DD format',
+    strInvalidDate: 'Enter an existing date',
+    strInvalidTimeFormat: 'Enter a valid time in HH:mm:ss format',
+    strInvalidTime: 'Enter an existing time',
+    strInvalidDateTimeFormat:
+      'Enter a valid date and time in YYYY-MM-DD HH:mm:ss format',
+    strSelectClearForbidden: 'This select column cannot be cleared',
+    strSelectValueUnknown: 'The selected value is not in the available options',
+    strSelectOptionDisabled: 'The selected option is disabled',
+    strMultiSelectArrayRequired: 'Multi-select values must be an array',
+    fnMultiSelectLimit: (nMaximum) => `Select at most ${nMaximum} options`,
+    strInvalidNumber: 'Enter a valid number',
+    strInputForbidden: 'Direct input is not allowed for this column',
+    strPasteForbidden: 'Pasting is not allowed for this column',
+    strAutofillForbidden: 'Autofill is not allowed for this column',
+    strChangeForbidden: 'This change is not allowed',
+    fnValidationInteger: (strLabel) => `${strLabel} must be an integer`,
+    fnValidationIntegerDigits: (strLabel, nDigits) =>
+      `${strLabel} can have at most ${nDigits} integer digits`,
+    fnValidationPositive: (strLabel) => `${strLabel} must be greater than 0`,
+    fnValidationMin: (strLabel, nMinimum) =>
+      `${strLabel} cannot be less than ${nMinimum}`,
+    fnValidationMax: (strLabel, nMaximum) =>
+      `${strLabel} cannot exceed ${nMaximum}`,
+    fnValidationDecimals: (strLabel, nPlaces) =>
+      `${strLabel} can have at most ${nPlaces} decimal places`,
+    fnValidationRequired: (strLabel) => `${strLabel} is required`,
+    fnValidationMaxLength: (strLabel, nMaximum) =>
+      `${strLabel} cannot exceed ${nMaximum} characters`,
+    fnValidationNumber: (strLabel) => `${strLabel} must be a valid number`,
+    fnValidationFailed: (strLabel) => `${strLabel} validation failed`,
+    strSelectPlaceholder: 'Please select',
+    strMoreActions: 'More',
+    fnSwitchAriaLabel: (strLabel, bChecked) =>
+      `${strLabel}: ${bChecked ? 'On' : 'Off'}`,
+    fnClearLinkAriaLabel: (strLabel) => `Clear ${strLabel}`,
+    strConfirmInput: 'Submit',
+    fnSelectRowAriaLabel: (nRow) => `Select row ${nRow}`,
+    strSelectCurrentPage: 'Select current page',
+    strRequired: 'Required',
+    strFixedActionColumns: 'Fixed action columns',
+    strOpenCellEditor: 'Open cell editor',
+    strMissingCreateResult:
+      'The server did not return a result for this created row',
+    strMissingUpdateResult:
+      'The server did not return a result for this updated row',
+    strMissingRemoveResult:
+      'The server did not return a result for this removed row',
+    strServerDataUpdated: 'The server data has been updated',
+    strSaveFailed: 'Save failed',
+    strCancel: 'Cancel',
+    strConfirm: 'Confirm',
+    fnSaveChanges: (nCount) => `Save changes (${nCount})`,
+    strDiscardChanges: 'Discard changes',
+    strSelectAllMatching: 'Select all matching',
+    strClearSelection: 'Clear selection',
+    strExport: 'Export',
+    fnDensityAriaLabel: (strDensity) =>
+      `Change table density, current: ${strDensity}`,
+    strDensity: 'Density',
+    strDensityCompact: 'Compact',
+    strDensityDefault: 'Standard',
+    strDensityComfortable: 'Comfortable',
+    strRefreshAriaLabel: 'Refresh table',
+    fnSelectedCount: (nCount) => `${nCount} selected`,
+    fnAllMatchingSelected: (nExcluded) =>
+      nExcluded
+        ? `All matching selected (${nExcluded} excluded)`
+        : 'All matching selected',
+    strCloseErrorAriaLabel: 'Dismiss error',
+    strLoadingData: 'Loading data',
+    strEmpty: 'No data',
+    strDetail: 'Details',
+    strSelectionColumn: 'Select',
+    strSingleCellEditOnly: 'Only one cell can be edited at a time',
+    strSummary: 'Total',
+    strSearch: 'Search',
+    strReset: 'Reset',
+    strCollapse: 'Collapse',
+    strExpand: 'Expand',
+    fnRemoteSearchAriaLabel: (strLabel) => `Search ${strLabel} remotely`,
+    strSearchPlaceholder: 'Enter keywords to search',
+    strAll: 'All',
+    fnStartDateAriaLabel: (strLabel) => `${strLabel} start date`,
+    fnEndDateAriaLabel: (strLabel) => `${strLabel} end date`,
+    strDateSeparator: 'to',
+    strOperatorIncludes: 'Contains',
+    strOperatorEquals: 'Equals',
+    strOperatorNotEquals: 'Not equal',
+    fnQueryOperatorAriaLabel: (strLabel) => `${strLabel} operator`,
+    strColumnSettings: 'Column settings',
+    strColumnSettingsPanel: 'Column settings panel',
+    strSearchColumns: 'Search columns',
+    fnVisibleCount: (nVisible, nTotal) => `${nVisible}/${nTotal} shown`,
+    strShowAll: 'Show all',
+    strHideAll: 'Hide all',
+    fnShowColumnAriaLabel: (strLabel) => `Show column ${strLabel}`,
+    fnMoveColumnUpAriaLabel: (strLabel) => `Move column ${strLabel} up`,
+    fnMoveColumnDownAriaLabel: (strLabel) => `Move column ${strLabel} down`,
+    strNoMatchingColumns: 'No matching columns',
+    strFreezeTopRows: 'Freeze top rows',
+    strKeepOneColumn: 'Keep at least one column',
+    strRestoreDefaults: 'Restore defaults',
+    strFilterSettings: 'Filter settings',
+    fnDragConditionAriaLabel: (strLabel) => `Drag to reorder ${strLabel}`,
+    fnMoveConditionUpAriaLabel: (strLabel) => `Move ${strLabel} up`,
+    fnMoveConditionDownAriaLabel: (strLabel) => `Move ${strLabel} down`,
+    strKeepOneCondition: 'Keep at least one condition',
+    strClearCellSelectionAriaLabel: 'Clear selection',
+    strSearchOptions: 'Search options',
+    strLoadingOptions: 'Loading options…',
+    strNoOptions: 'No options',
+    fnSelectedCellSum: (strValue) => `Selected cell total: ${strValue}`,
+    fnTotalRows: (nTotal) => `${nTotal} rows`,
+    strPageSizeAriaLabel: 'Rows per page',
+    fnRowsPerPage: (nSize) => `${nSize} / page`,
+    fnPageAriaLabel: (nPage) => `Page ${nPage}`,
+    strGoTo: 'Go to',
+    strTargetPageAriaLabel: 'Target page',
+    strPage: 'page',
+    strJump: 'Go',
+    strBottomPanel: 'Bottom panel',
+    strResizeBottomPanelAriaLabel: 'Resize bottom panel height',
+    strRightPanel: 'Side panel',
+    strResizeRightPanelAriaLabel: 'Resize side panel width',
+    fnClosePanelAriaLabel: (strTitle) => `Close ${strTitle}`,
+    strExportRange: 'Selected range',
+    strExportPage: 'Current page',
+    strExportSelection: 'Selected rows',
+    strExportAll: 'All data',
+  } satisfies IAppTableMessages),
+  'zh-CN': Object.freeze({
+    strDensity: '密度',
+    strDensityCompact: '紧凑',
+    strDensityDefault: '标准',
+    strDensityComfortable: '舒适',
+    ...TABLE_ENGINE_MESSAGES_ZH_CN,
+    strCancel: '取消',
+    strConfirm: '确定',
+    fnSaveChanges: (nCount) => `保存修改 (${nCount})`,
+    strDiscardChanges: '放弃修改',
+    strSelectAllMatching: '选择全部匹配项',
+    strClearSelection: '清除选择',
+    strExport: '导出',
+    fnDensityAriaLabel: (strDensity) => `切换表格密度，当前 ${strDensity}`,
+    strRefreshAriaLabel: '刷新表格',
+    fnSelectedCount: (nCount) => `已选择 ${nCount} 项`,
+    fnAllMatchingSelected: (nExcluded) =>
+      nExcluded
+        ? `已选择全部匹配项（排除 ${nExcluded} 项）`
+        : '已选择全部匹配项',
+    strCloseErrorAriaLabel: '关闭错误提示',
+    strLoadingData: '正在加载数据',
+    strEmpty: '暂无数据',
+    strDetail: '详情',
+    strSelectionColumn: '选择',
+    strSingleCellEditOnly: '当前表格只允许单个单元格修改',
+    strSummary: '合计',
+    strSearch: '搜索',
+    strReset: '重置',
+    strCollapse: '收起',
+    strExpand: '展开',
+    fnRemoteSearchAriaLabel: (strLabel) => `${strLabel}远程搜索`,
+    strSearchPlaceholder: '输入关键字搜索',
+    strAll: '全部',
+    fnStartDateAriaLabel: (strLabel) => `${strLabel}开始日期`,
+    fnEndDateAriaLabel: (strLabel) => `${strLabel}结束日期`,
+    strDateSeparator: '至',
+    strOperatorIncludes: '包含',
+    strOperatorEquals: '等于',
+    strOperatorNotEquals: '不等于',
+    fnQueryOperatorAriaLabel: (strLabel) => `${strLabel}查询运算符`,
+    strColumnSettings: '列设置',
+    strColumnSettingsPanel: '列设置面板',
+    strSearchColumns: '搜索字段',
+    fnVisibleCount: (nVisible, nTotal) => `已显示 ${nVisible}/${nTotal}`,
+    strShowAll: '全部显示',
+    strHideAll: '全部隐藏',
+    fnShowColumnAriaLabel: (strLabel) => `显示列 ${strLabel}`,
+    fnMoveColumnUpAriaLabel: (strLabel) => `上移列 ${strLabel}`,
+    fnMoveColumnDownAriaLabel: (strLabel) => `下移列 ${strLabel}`,
+    strNoMatchingColumns: '没有匹配字段',
+    strFreezeTopRows: '冻结顶部数据行',
+    strKeepOneColumn: '至少保留一列',
+    strRestoreDefaults: '恢复默认',
+    strFilterSettings: '筛选设置',
+    fnDragConditionAriaLabel: (strLabel) => `拖动排序 ${strLabel}`,
+    fnMoveConditionUpAriaLabel: (strLabel) => `上移 ${strLabel}`,
+    fnMoveConditionDownAriaLabel: (strLabel) => `下移 ${strLabel}`,
+    strKeepOneCondition: '至少保留一个条件',
+    strClearCellSelectionAriaLabel: '清空选择',
+    strSearchOptions: '搜索选项',
+    strLoadingOptions: '正在加载选项…',
+    strNoOptions: '暂无选项',
+    fnSelectedCellSum: (strValue) => `选中单元格合计：${strValue}`,
+    fnTotalRows: (nTotal) => `共 ${nTotal} 条`,
+    strPageSizeAriaLabel: '每页条数',
+    fnRowsPerPage: (nSize) => `${nSize} 条/页`,
+    fnPageAriaLabel: (nPage) => `第 ${nPage} 页`,
+    strGoTo: '前往',
+    strTargetPageAriaLabel: '目标页码',
+    strPage: '页',
+    strJump: '跳转',
+    strBottomPanel: '底部面板',
+    strResizeBottomPanelAriaLabel: '调整底部面板高度',
+    strRightPanel: '右侧面板',
+    strResizeRightPanelAriaLabel: '调整右侧面板宽度',
+    fnClosePanelAriaLabel: (strTitle) => `关闭${strTitle}`,
+    strExportRange: '选中区域',
+    strExportPage: '当前页',
+    strExportSelection: '已选数据',
+    strExportAll: '全部数据',
+  } satisfies IAppTableMessages),
+})
+
+/** 合并单张表的局部覆盖，语言区域只使用脚手架当前内建的中英文。 */
+export function resolveAppTableMessages(
+  strLocale: string,
+  objOverrides?: Partial<IAppTableMessages>
+): IAppTableMessages {
+  const strMessageLocale: TAppLocale = strLocale.toLowerCase().startsWith('en')
+    ? 'en-US'
+    : 'zh-CN'
+  return { ...objAppTableMessages[strMessageLocale], ...objOverrides }
+}
+
+export const AppTableMessagesContext = createContext<IAppTableMessages>(
+  objAppTableMessages['zh-CN']
+)
+
+/** 读取当前 TableComponent 已合并局部覆盖的文案。 */
+export function useAppTableMessages() {
+  return useContext(AppTableMessagesContext)
+}