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

package/template/src/components/AppTable/engine/columns/column.ts

@@ -0,0 +1,430 @@
+import type { ColumnSettings } from 'handsontable'
+import type { BaseRenderer } from 'handsontable/renderers'
+import type { TableCellComponentProps } from '../cell/customCell/types'
+import type { TableValueFormat } from '../cell/formatting'
+import type { TableFormulaInputOptions } from '../cell/formula'
+import type { TableMultiSelectConfig } from '../cell/multiSelect'
+import type { TableOptionCachePolicy, TableOptionSource } from '../cell/options'
+import type { TableAction, TableCellContext } from '../cell/types'
+import type { TableKeyOf, TableOption, TableRow } from '../shared/types'
+import type {
+  TableSummaryColumn,
+  TableSummaryOperation,
+} from '../summary/summary'
+import type { TableTransferConfig } from '../table/clipboard'
+import type {
+  TableChangeGuard,
+  TableDerivedChanges,
+  TableNumberInputOptions,
+  TableValidationRule,
+  TableValueParser,
+} from '../table/editing'
+import { TABLE_COLUMN_DEFAULTS } from './constants'
+import {
+  resolveTableRendererPolicy,
+  type TableRendererType,
+} from './rendererPolicies'
+
+interface TableAutocompleteConfig {
+  /** 静态建议列表或 Handsontable 原生查询回调。 */
+  source: NonNullable<ColumnSettings['source']>
+  /** 只接受 source 中的值；默认 false，允许自由文本输入。 */
+  strict?: boolean
+  /** 是否按编辑器输入过滤建议，默认 true。 */
+  filter?: boolean
+  /** 出现滚动条前最多展示的建议行数。 */
+  visibleRows?: number
+  /** 非法输入时是否保留当前值，而不是恢复旧值。 */
+  allowInvalid?: boolean
+  /** 建议数量少于 visibleRows 时是否收缩下拉高度。 */
+  trimDropdown?: boolean
+}
+
+interface ResolvedTableAutocompleteConfig {
+  /** 已解析的候选数据源。 */
+  source: NonNullable<ColumnSettings['source']>
+  /** 是否只接受候选值。 */
+  strict: boolean
+  /** 是否按输入文本过滤候选项。 */
+  filter: boolean
+  /** 下拉面板最大可见行数。 */
+  visibleRows: number
+  /** 是否允许非法输入暂时保留。 */
+  allowInvalid: boolean
+  /** 候选较少时是否收缩面板高度。 */
+  trimDropdown: boolean
+}
+
+export const resolveTableAutocompleteConfig = (
+  config: TableAutocompleteConfig
+): ResolvedTableAutocompleteConfig => ({
+  source: config.source,
+  strict: config.strict ?? false,
+  filter: config.filter ?? true,
+  visibleRows: Math.max(
+    1,
+    Math.trunc(
+      config.visibleRows ?? TABLE_COLUMN_DEFAULTS.autocompleteVisibleRows
+    )
+  ),
+  allowInvalid: config.allowInvalid ?? !config.strict,
+  trimDropdown: config.trimDropdown ?? true,
+})
+
+interface TableItemListConfig<T extends TableRow = TableRow> {
+  /** 字符串拆分为多个条目时使用的分隔符，默认分号。 */
+  separator?: string
+  /** 对象数组通过该字段读取显示文本，避免渲染成 `[object Object]`。 */
+  labelKey?: string
+  /** 每个条目的对齐方式；auto 会让数字右对齐、其他内容左对齐。 */
+  align?: 'auto' | 'left' | 'center' | 'right'
+  /** 是否把每个非空条目渲染为可点击链接。 */
+  link?: boolean
+  /** 点击某个链接条目时触发，收到原始条目值和完整单元格上下文。 */
+  onItemClick?: (
+    item: unknown,
+    context: TableCellContext<T>
+  ) => void | Promise<void>
+}
+
+interface TableStepConfig<T extends TableRow = TableRow> {
+  /** 根据当前行生成步骤组；嵌套数组会被展平并用箭头连接。 */
+  resolve: (
+    context: TableCellContext<T>
+  ) => readonly (readonly unknown[] | unknown)[]
+  /** 步骤为对象时读取该字段作为显示文案。 */
+  labelKey?: string
+}
+
+interface TableConfirmInputConfig<T extends TableRow = TableRow> {
+  /** 单元格内确认按钮文案，默认“提交”。 */
+  buttonLabel?: string
+  /** 确认动作的 DOM 触发时机，默认 click。 */
+  trigger?: 'click' | 'mousedown' | 'mouseup'
+  /** 是否允许双击整个单元格执行确认动作，默认 false。 */
+  doubleClickTrigger?: boolean
+  /** 静态或按行计算的按钮禁用状态。 */
+  disabled?: boolean | ((context: TableCellContext<T>) => boolean)
+  /** 用户确认时执行的业务回调。 */
+  onConfirm: (context: TableCellContext<T>) => void | Promise<void>
+}
+
+export interface TableLink<T extends TableRow = TableRow> {
+  /** 单元格内链接的稳定唯一 key。 */
+  key: string
+  /** 静态或按行计算的显示文案。 */
+  label: string | ((context: TableCellContext<T>) => string)
+  /** 静态或按行计算的原生安全跳转地址；省略时作为按钮链接。 */
+  href?: string | ((context: TableCellContext<T>) => string | undefined)
+  /** 静态或按行计算的禁用状态。 */
+  disabled?: boolean | ((context: TableCellContext<T>) => boolean)
+  /** 单击链接时执行的业务回调。 */
+  onClick?: (context: TableCellContext<T>) => void | Promise<void>
+  /** 双击链接时执行的业务回调；存在时单击会等待双击判定窗口。 */
+  onDoubleClick?: (context: TableCellContext<T>) => void | Promise<void>
+  /** 提供后在链接旁显示清除入口。 */
+  onClear?: (context: TableCellContext<T>) => void | Promise<void>
+  /** 清除入口的无障碍文案。 */
+  clearLabel?: string
+}
+
+/** 静态第三方组件属性，或根据当前单元格上下文按行生成的属性。 */
+type TableCellComponentPropsSource<T extends TableRow = TableRow> =
+  | TableCellComponentProps
+  | ((context: TableCellContext<T>) => TableCellComponentProps)
+
+type TableColumnSummaryConfig<T extends TableRow> =
+  TableSummaryColumn<T> extends infer TSummary
+    ? TSummary extends TableSummaryColumn<T>
+      ? Omit<TSummary, 'key' | 'label'>
+      : never
+    : never
+
+/**
+ * 业务列允许直接使用的 Handsontable 原生列属性。
+ *
+ * 完整原生设置仍可通过 `table.settings` 透传；这里显式列出列级安全属性，避免
+ * Handsontable `GridSettings` 的 `[key: string]: any` 让拼错的业务属性静默通过。
+ */
+interface TableNativeColumnSettings {
+  /** Handsontable 内置单元格类型，如 text、numeric、date 或 checkbox。 */
+  type?: ColumnSettings['type']
+  /** 列宽，支持像素数或 Handsontable 接受的宽度值。 */
+  width?: ColumnSettings['width']
+  /** 应用于该列数据单元格的 CSS 类名。 */
+  className?: ColumnSettings['className']
+  /** 应用于该列表头单元格的 CSS 类名。 */
+  headerClassName?: ColumnSettings['headerClassName']
+  /** 是否允许提交空值。 */
+  allowEmpty?: ColumnSettings['allowEmpty']
+  /** 校验失败后是否仍允许保留无效值。 */
+  allowInvalid?: ColumnSettings['allowInvalid']
+  /** checkbox 列选中状态写入数据源的值。 */
+  checkedTemplate?: ColumnSettings['checkedTemplate']
+  /** 是否允许把该列内容复制到剪贴板。 */
+  copyable?: ColumnSettings['copyable']
+  /** 是否允许该列进入客户端或远程导出元数据，默认 true。 */
+  exportable?: boolean
+  /** date 列解析和展示使用的日期格式。 */
+  dateFormat?: ColumnSettings['dateFormat']
+  /** 日期编辑器打开时使用的默认日期。 */
+  defaultDate?: ColumnSettings['defaultDate']
+  /** Handsontable 原生编辑器名称、类或禁用标识。 */
+  editor?: ColumnSettings['editor']
+  /** password 列显示的遮罩字符数量。 */
+  hashLength?: ColumnSettings['hashLength']
+  /** password 列临时显示明文前的延迟毫秒数。 */
+  hashRevealDelay?: ColumnSettings['hashRevealDelay']
+  /** password 列使用的遮罩字符。 */
+  hashSymbol?: ColumnSettings['hashSymbol']
+  /** numeric 列使用的数字格式和区域语言配置。 */
+  numericFormat?: ColumnSettings['numericFormat']
+  /** 空单元格在编辑器或渲染器中显示的占位文案。 */
+  placeholder?: ColumnSettings['placeholder']
+  /** dropdown 或 select 编辑器的候选项。 */
+  selectOptions?: ColumnSettings['selectOptions']
+  /** Handsontable 原生列标题。业务列通常优先使用 `label`。 */
+  title?: ColumnSettings['title']
+  /** 文本编辑完成后是否移除首尾空白。 */
+  trimWhitespace?: ColumnSettings['trimWhitespace']
+  /** checkbox 列未选中状态写入数据源的值。 */
+  uncheckedTemplate?: ColumnSettings['uncheckedTemplate']
+  /** Handsontable 原生同步或异步校验器。 */
+  validator?: ColumnSettings['validator']
+  /** 从源数据读取当前列值的 Handsontable 原生转换函数。 */
+  valueGetter?: ColumnSettings['valueGetter']
+  /** 把编辑值写回源数据的 Handsontable 原生转换函数。 */
+  valueSetter?: ColumnSettings['valueSetter']
+  /** 是否允许单元格文本自动换行。 */
+  wordWrap?: ColumnSettings['wordWrap']
+}
+
+/**
+ * TableComponent 的业务列合同。
+ *
+ * 它扩展 Handsontable 公共 ColumnSettings，同时把 renderer、校验、格式化、编辑准入、
+ * 剪贴板策略和汇总等企业能力显式化。engine 与 React 层必须共享该类型，不能
+ * 在视图层再定义一套含义不同的列配置。
+ */
+interface TableColumnBase<
+  T extends TableRow = TableRow,
+> extends TableNativeColumnSettings {
+  /** 对应后端 DTO 的稳定字段 key，也是偏好、排序、筛选和变更跟踪身份。 */
+  key: TableKeyOf<T>
+  /** 列表头及列设置中展示的业务名称。 */
+  label: string
+  /** false 时从 engine 编译阶段完全排除，也不会进入列设置；不同于用户可恢复的 hidden。 */
+  enabled?: boolean
+  /** 静态或按行计算的只读状态；受控展示型 renderer 会强制只读。 */
+  readOnly?: boolean | ((row: T, rowIndex: number) => boolean)
+  /** 初始隐藏但允许用户在列设置中恢复显示。 */
+  hidden?: boolean
+  /** 是否为必填列；会合并到保存前校验规则。 */
+  required?: boolean
+  /** 长度、数值边界和异步业务校验规则。 */
+  validation?: Omit<TableValidationRule<T>, 'required'>
+  /** 参与汇总时使用的聚合操作或完整列级汇总配置。 */
+  summary?:
+    | Exclude<TableSummaryOperation, 'custom'>
+    | TableColumnSummaryConfig<T>
+  /** 在 renderer、排序和导出前转换显示值，不修改源数据。 */
+  formatter?: (value: unknown, row: T, rowIndex: number) => unknown
+  /** 声明式数字、货币、百分比或日期时间显示格式。 */
+  format?: TableValueFormat
+  /** select/multiSelect 的静态、函数或远程选项源。 */
+  options?: TableOptionSource<T>
+  /** 远程选项缓存的键、有效期和容量策略。 */
+  optionCache?: TableOptionCachePolicy<T>
+  /** 远程选项搜索防抖毫秒数，默认 300。 */
+  optionDebounceMs?: number
+  /** 选项编辑器未选择值时的占位文案。 */
+  optionPlaceholder?: string
+  /**
+   * 使用框架浮层时，透传给 select/multiSelect/date/time/datetime 的第三方编辑组件。
+   *
+   * 支持静态对象和按单元格计算；modelValue、提交/关闭事件等编辑事务属性由表格保留，
+   * 其余 props 与 attrs 由当前框架适配层原样下传。
+   */
+  componentProps?: TableCellComponentPropsSource<T>
+  /** 是否允许清空选项值，默认 true。 */
+  optionClearable?: boolean
+  /** 是否允许导入/API 写入静态选项表中不存在的历史值。 */
+  allowUnknownOption?: boolean
+  /** select renderer 是否按多选工作；推荐直接使用 multiSelect renderer。 */
+  multiple?: boolean
+  /** 多选引擎、上限、搜索和标签折叠配置。 */
+  multiSelect?: TableMultiSelectConfig
+  /** Handsontable 原生 autocomplete 行为配置。 */
+  autocomplete?: TableAutocompleteConfig
+  /** itemList renderer 的条目拆分、显示和点击行为。 */
+  itemList?: TableItemListConfig<T>
+  /** button renderer 的行级动作列表。 */
+  actions?: TableAction<T>[]
+  /** 可见操作槽位总数，包含“更多”入口，默认 3。 */
+  buttonLimit?: number
+  /** 设为 false 时不折叠“更多”，始终展示所有动作。 */
+  foldActions?: boolean
+  /** 超量动作入口文案，默认“更多”。 */
+  moreActionLabel?: string
+  /** 一格多链接，每个链接拥有独立的单击、双击和清除动作。 */
+  links?:
+    | readonly TableLink<T>[]
+    | ((context: TableCellContext<T>) => readonly TableLink<T>[])
+  /** 单链接场景的简化 href 解析函数。 */
+  link?: (context: TableCellContext<T>) => string | undefined
+  /** 受控编辑器提交后回传原始值、更新后的上下文及命中的选项对象。 */
+  onChange?: (
+    value: unknown,
+    context: TableCellContext<T>,
+    option?: TableOption | readonly TableOption[]
+  ) => void
+  /** 受控 Select/Date 编辑器的触发方式，默认双击。 */
+  editorTrigger?: 'doubleClick' | 'click' | 'icon'
+  /** 标准数字输入归一化；Handsontable numeric 列默认启用。 */
+  numberInput?: TableNumberInputOptions | false
+  /** 显式开启以 `=` 开头的安全四则运算，不使用 eval。 */
+  formulaInput?: boolean | TableFormulaInputOptions
+  /** 数据进入事务前的列级值解析器。 */
+  parseValue?: TableValueParser<T>
+  /** 解析后决定是否接受修改；返回字符串会作为拒绝原因。 */
+  acceptChange?: TableChangeGuard<T>
+  /** 根据本次修改生成同一事务内的关联字段变更。 */
+  deriveChanges?: TableDerivedChanges<T>
+  /** 带来源识别的粘贴/填充策略及关联字段传播。 */
+  transfer?: TableTransferConfig
+  /** 禁止原生文本编辑器，但仍允许受控组件编辑。 */
+  allowInput?: boolean
+  /** 是否允许粘贴写入本列；未设置时按 renderer 安全策略推导。 */
+  allowPaste?: boolean
+  /** 是否允许拖拽填充写入本列；未设置时按 renderer 安全策略推导。 */
+  allowAutofill?: boolean
+}
+
+type TableColumnRendererContract<T extends TableRow> =
+  | {
+      /** step renderer 必须同时提供步骤解析器。 */
+      renderer: 'step'
+      step: TableStepConfig<T>
+      confirmInput?: never
+    }
+  | {
+      /** 确认输入 renderer 必须同时提供确认回调。 */
+      renderer: 'confirmInput' | 'pasteConfirmInput'
+      confirmInput: TableConfirmInputConfig<T>
+      step?: never
+    }
+  | {
+      /** 其他内置 renderer 或 Handsontable 原生 renderer 不接受专用配置。 */
+      renderer?:
+        | Exclude<
+            TableRendererType,
+            'step' | 'confirmInput' | 'pasteConfirmInput'
+          >
+        | BaseRenderer
+      step?: never
+      confirmInput?: never
+    }
+
+/** renderer 与其必需配置在编译期保持一致的业务列联合类型。 */
+export type TableColumn<T extends TableRow = TableRow> = TableColumnBase<T> &
+  TableColumnRendererContract<T>
+
+interface TableColumnMutationPolicy {
+  /** 是否允许原生或受控编辑器写入。 */
+  allowInput: boolean
+  /** 是否允许剪贴板粘贴写入。 */
+  allowPaste: boolean
+  /** 是否允许拖拽填充写入。 */
+  allowAutofill: boolean
+}
+
+/** 使用外部 UI 浮层、但仍通过 Handsontable 标准事务提交的编辑器。 */
+export const isTableControlledEditorColumn = <T extends TableRow>(
+  column: TableColumn<T>
+) =>
+  typeof column.renderer !== 'function' &&
+  resolveTableRendererPolicy(column.renderer).layerEditor
+
+/** 先解析 renderer 默认权限，再应用列级输入/粘贴/填充覆盖。 */
+export const resolveTableColumnMutationPolicy = <T extends TableRow>(
+  column: TableColumn<T>
+): TableColumnMutationPolicy => {
+  const policy =
+    typeof column.renderer === 'function'
+      ? resolveTableRendererPolicy()
+      : resolveTableRendererPolicy(column.renderer)
+  return {
+    allowInput:
+      column.allowInput ?? (policy.pasteOnly || !policy.managedMutation),
+    allowPaste:
+      column.allowPaste ?? (policy.pasteOnly || !policy.managedMutation),
+    allowAutofill:
+      column.allowAutofill ?? (policy.pasteOnly || !policy.managedMutation),
+  }
+}
+
+/** 对无法由类型系统表达的 renderer 必填配置给出显式诊断。 */
+export const assertTableColumnConfiguration = <T extends TableRow>(
+  column: TableColumn<T>
+) => {
+  if (column.renderer === 'step' && !column.step?.resolve) {
+    throw new Error(
+      `[TableComponent] Column "${String(column.key)}" with renderer "step" requires step.resolve.`
+    )
+  }
+  if (
+    (column.renderer === 'confirmInput' ||
+      column.renderer === 'pasteConfirmInput') &&
+    !column.confirmInput?.onConfirm
+  ) {
+    throw new Error(
+      `[TableComponent] Column "${String(column.key)}" with renderer "${column.renderer}" requires confirmInput.onConfirm.`
+    )
+  }
+}
+
+/** 列设置搜索期间只重排命中的槽位，未命中列保持原位置。 */
+export const reorderTableColumnsByFilteredIndex = <T extends TableRow>(
+  columns: readonly TableColumn<T>[],
+  filteredKeys: readonly string[],
+  oldIndex: number,
+  newIndex: number
+) => {
+  if (
+    oldIndex === newIndex ||
+    oldIndex < 0 ||
+    newIndex < 0 ||
+    oldIndex >= filteredKeys.length ||
+    newIndex >= filteredKeys.length
+  ) {
+    return [...columns]
+  }
+  const reorderedKeys = [...filteredKeys]
+  const [moved] = reorderedKeys.splice(oldIndex, 1)
+  reorderedKeys.splice(newIndex, 0, moved)
+  const byKey = new Map(columns.map((column) => [String(column.key), column]))
+  const filteredKeySet = new Set(filteredKeys)
+  let filteredIndex = 0
+  return columns.map((column) =>
+    filteredKeySet.has(String(column.key))
+      ? (byKey.get(reorderedKeys[filteredIndex++]) ?? column)
+      : column
+  )
+}
+
+/** renderer 或动作声明任一命中时，该列都按操作列处理。 */
+export const isTableActionColumn = <T extends TableRow>(
+  column: TableColumn<T>
+) => column.renderer === 'button' || Boolean(column.actions?.length)
+
+/** 从表格逻辑起始侧向后统计连续的操作列。 */
+export const countTableStartActionColumns = <T extends TableRow>(
+  columns: readonly TableColumn<T>[]
+) => {
+  let count = 0
+  for (const column of columns) {
+    if (!isTableActionColumn(column)) break
+    count++
+  }
+  return count
+}

package/template/src/components/AppTable/engine/columns/config/columns.ts

@@ -0,0 +1,33 @@
+import type { TableRow } from '../../shared/types'
+import type { TableColumn } from '../column'
+
+class TableColumnsConfigError extends Error {
+  readonly code = 'TABLE_COLUMNS_CONFIG_INVALID'
+
+  constructor(message: string) {
+    super(`[TableComponent] ${message}`)
+    this.name = 'TableColumnsConfigError'
+  }
+}
+
+/**
+ * 校验并复制业务列声明。
+ *
+ * 列 key 是编辑、偏好、汇总和后端字段映射的共同身份，空 key 或重复 key 必须在创建
+ * Controller 时失败，不能等到用户编辑后再产生错列写入。
+ */
+export const resolveTableColumns = <T extends TableRow>(
+  columns: readonly TableColumn<T>[]
+): TableColumn<T>[] => {
+  const keys = new Set<string>()
+  return columns.flatMap((column) => {
+    const key = String(column.key)
+    if (!key.trim())
+      throw new TableColumnsConfigError('Column key is required.')
+    if (keys.has(key)) {
+      throw new TableColumnsConfigError(`Duplicate column key "${key}".`)
+    }
+    keys.add(key)
+    return column.enabled === false ? [] : [{ ...column }]
+  })
+}

package/template/src/components/AppTable/engine/columns/config/index.ts

@@ -0,0 +1,4 @@
+export * from './columns'
+export * from './mutation'
+export * from './temporal'
+export * from './validation'

package/template/src/components/AppTable/engine/columns/config/mutation.ts

@@ -0,0 +1,138 @@
+import {
+  parseTableFormulaInput,
+  parseTableTemporalInput,
+  resolveTableMultiSelectConfig,
+  validateTableMultiSelectValue,
+  validateTableSelectValue,
+} from '../../cell'
+import {
+  TABLE_ENGINE_MESSAGES_ZH_CN,
+  type TableEngineMessages,
+} from '../../shared/messages'
+import type { TableRow } from '../../shared/types'
+import {
+  parseTableNumberInput,
+  validateTableValue,
+  type TableValidationColumn,
+} from '../../table/editing'
+import { resolveTableColumnMutationPolicy, type TableColumn } from '../column'
+import { resolveTableColumns } from './columns'
+import { resolveTableColumnTemporalType } from './temporal'
+
+/** 提取可以在单元格提交阶段同步执行的字段规则。 */
+const createSynchronousValidation = <T extends TableRow>(
+  column: TableColumn<T>
+): TableValidationColumn<T> | undefined => {
+  const { validator: _asyncValidator, ...rules } = column.validation ?? {}
+  if (!column.required && !Object.keys(rules).length) return
+  return {
+    prop: String(column.key),
+    label: column.label,
+    required: column.required,
+    ...rules,
+  }
+}
+
+const resolveTableNumberInput = <T extends TableRow>(
+  column: TableColumn<T>
+) => {
+  if (column.numberInput === false) return
+  if (column.type !== 'numeric' && !column.numberInput) return
+  return column.numberInput || {}
+}
+
+/** 编译公式、数字/日期规范化和业务解析组成的值解析链。 */
+const createTableValueParser = <T extends TableRow>(
+  column: TableColumn<T>,
+  messages: TableEngineMessages
+) => {
+  const numberInput = resolveTableNumberInput(column)
+  const temporalType = resolveTableColumnTemporalType(column)
+  if (!numberInput && !temporalType) return column.parseValue
+
+  return (
+    value: unknown,
+    context: Parameters<NonNullable<typeof column.parseValue>>[1]
+  ) => {
+    const formulaValue =
+      numberInput && column.formulaInput
+        ? parseTableFormulaInput(
+            value,
+            column.formulaInput === true ? {} : column.formulaInput,
+            messages
+          )
+        : value
+    const normalized = numberInput
+      ? parseTableNumberInput(formulaValue, numberInput, messages)
+      : parseTableTemporalInput(formulaValue, temporalType!, messages)
+    return column.parseValue
+      ? column.parseValue(normalized, { ...context, value: normalized })
+      : normalized
+  }
+}
+
+/** 编译同步字段规则、选项协议和业务 acceptChange 组成的提交准入链。 */
+const createTableChangeGuard = <T extends TableRow>(
+  column: TableColumn<T>,
+  synchronousValidation: TableValidationColumn<T> | undefined,
+  messages: TableEngineMessages
+) => {
+  const multiSelect =
+    column.renderer === 'multiSelect'
+      ? resolveTableMultiSelectConfig(column.options, column.multiSelect)
+      : undefined
+  const select = column.renderer === 'select'
+  if (!select && !multiSelect && !synchronousValidation) {
+    return column.acceptChange
+  }
+
+  return (context: Parameters<NonNullable<typeof column.acceptChange>>[0]) => {
+    if (synchronousValidation) {
+      const issue = validateTableValue(
+        context.value,
+        synchronousValidation,
+        messages
+      )
+      if (issue) return issue.message
+    }
+    if (select) {
+      const result = validateTableSelectValue(
+        context.value,
+        column.options,
+        {
+          clearable: column.optionClearable,
+          allowUnknownValue: column.allowUnknownOption,
+        },
+        messages
+      )
+      if (result !== true) return result
+    }
+    if (multiSelect) {
+      const result = validateTableMultiSelectValue(
+        context.value,
+        multiSelect,
+        messages
+      )
+      if (result !== true) return result
+    }
+    return column.acceptChange?.(context) ?? true
+  }
+}
+
+/** 按列编译 Controller 编辑事务所需的解析、准入和派生字段规则。 */
+export const buildTableMutationColumns = <T extends TableRow>(
+  columns: readonly TableColumn<T>[],
+  messages: TableEngineMessages = TABLE_ENGINE_MESSAGES_ZH_CN
+) =>
+  resolveTableColumns(columns).map((column) => ({
+    prop: String(column.key),
+    messages,
+    parseValue: createTableValueParser(column, messages),
+    acceptChange: createTableChangeGuard(
+      column,
+      createSynchronousValidation(column),
+      messages
+    ),
+    deriveChanges: column.deriveChanges,
+    ...resolveTableColumnMutationPolicy(column),
+  }))

package/template/src/components/AppTable/engine/columns/config/temporal.ts

@@ -0,0 +1,11 @@
+import { isTableTemporalType, type TableTemporalType } from '../../cell'
+import type { TableRow } from '../../shared/types'
+import type { TableColumn } from '../column'
+
+/** 从列 renderer 解析日期/时间字段协议，供校验与 mutation 编译共享。 */
+export const resolveTableColumnTemporalType = <T extends TableRow>(
+  column: TableColumn<T>
+): TableTemporalType | undefined => {
+  const { renderer } = column
+  return isTableTemporalType(renderer) ? renderer : undefined
+}