cx-chat 0.0.1

package/src/components/table-view/list-page-view.tsx

@@ -0,0 +1,1049 @@
+import { Form } from 'antd'
+import React, {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import { flushSync } from 'react-dom'
+
+import ConfirmDialog from '@/components/common/modal/confirm-dialog'
+import Pagination from '@/components/common/pagination'
+import { useAuth } from '@/contexts/AuthContext'
+import { useMenu } from '@/contexts/MenuContext'
+import { useRouter } from '@/hooks/useRouter'
+import { useStickyHeader } from '@/hooks/useStickyHeader'
+import { ChevronLeft, Plus, ShieldUser } from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+import { useLocation, useNavigate } from 'react-router-dom'
+
+import { CxButton, CxEmptyState, CxTable, CxTooltip } from '@cx-ui'
+import { getListPathFromSubRoutePathname } from '@/utils/menuRouteRegistry'
+import { flattenMenuTree, getIconComponent } from '@/utils/routeConfig'
+import { SearchArea } from './components/search-area'
+import {
+  ListPageViewProps,
+  ListRenderContext,
+  SearchButtonSize,
+  TABLE_VIEW_DEFAULT_PAGE_SIZE_OPTIONS,
+  TABLE_VIEW_TREE_DEFAULTS,
+  TreeConfig,
+  TreeContext,
+} from './components/table-view.types'
+import { normalizeTreeAPIResult } from './components/tree-api-normalize'
+import { annotateTreeDisableNode } from './components/tree-data-annotate'
+import { TreeSidebar } from './components/tree-sidebar'
+
+const isDev = import.meta.env.DEV
+
+function collectAllTreeNodeKeys(
+  nodes: any[] | undefined,
+  idKey: string,
+  childrenKey: string,
+): (string | number)[] {
+  const keys: (string | number)[] = []
+  const walk = (list: any[]) => {
+    for (const n of list) {
+      const id = n?.[idKey]
+      if (id !== undefined && id !== null) keys.push(id)
+      const children = n?.[childrenKey]
+      if (Array.isArray(children) && children.length) walk(children)
+    }
+  }
+  if (Array.isArray(nodes)) walk(nodes)
+  return keys
+}
+
+function normalizeSearchValuesByFields(
+  values: Record<string, any>,
+  searchFields: ListPageViewProps['pageConfig']['searchFields'],
+) {
+  const next: Record<string, any> = { ...values }
+  const fields = searchFields ?? []
+  for (const field of fields) {
+    if (field.type !== 'dateRange') continue
+
+    const startKey = field.rangeStartProp || `${field.prop}Start`
+    const endKey = field.rangeEndProp || `${field.prop}End`
+    const format = field.format || 'YYYY-MM-DD HH:mm:ss'
+    const range = values[field.prop]
+
+    if (Array.isArray(range) && range[0] && range[1]) {
+      if (field.showTime) {
+        next[startKey] = range[0].format(format)
+        next[endKey] = range[1].format(format)
+      } else {
+        next[startKey] = range[0].startOf('day').format(format)
+        next[endKey] = range[1].endOf('day').format(format)
+      }
+    } else {
+      next[startKey] = undefined
+      next[endKey] = undefined
+    }
+
+  }
+  return next
+}
+
+/** 删除确认文案 `t(content, …)` 的插值对象；未配 `contentFields` 时默认只取 `name` */
+function buildDeleteConfirmInterpolation(
+  record: any | null,
+  contentFields?: string | string[],
+): Record<string, unknown> {
+  if (record == null) return { name: '' }
+
+  let keys: string[]
+  if (contentFields == null || contentFields === '') {
+    keys = ['name']
+  } else if (Array.isArray(contentFields)) {
+    keys = contentFields.filter(
+      (x): x is string => typeof x === 'string' && x.length > 0,
+    )
+    if (keys.length === 0) keys = ['name']
+  } else {
+    keys = [contentFields]
+  }
+
+  const out: Record<string, unknown> = {}
+  for (const k of keys) {
+    out[k] = record[k]
+  }
+  return out
+}
+
+type TableActionsRender = (ctx: {
+  searchButtonSize: SearchButtonSize
+  tree?: TreeContext
+}) => React.ReactNode
+type HeaderActionsRender = (ctx: { tree?: TreeContext }) => React.ReactNode
+
+function TableActions({
+  children,
+  searchButtonSize,
+  tree,
+}: {
+  children?: React.ReactNode | TableActionsRender
+  searchButtonSize: SearchButtonSize
+  tree?: TreeContext
+}) {
+  if (children == null) return null
+
+  const content =
+    typeof children === 'function'
+      ? (children as TableActionsRender)({ tree, searchButtonSize })
+      : children
+  if (content == null || content === false) return null
+
+  return (
+    <div className="px-3 py-4 border-b border-gray-200 dark:border-gray-700 flex justify-between items-start">
+      {content}
+    </div>
+  )
+}
+
+/** 根 props 与 pageConfig 解构字段按字母序，便于与 `table-view.types` 对照。 */
+function ListPageView({
+  columns,
+  detailModalComponent,
+  headerActions,
+  pageConfig,
+  renderList,
+  searchAreaExtra,
+  searchSlot,
+  showBackToList,
+  submitModalComponent,
+  tableActions,
+  titleExtra,
+  titleIcon,
+}: ListPageViewProps) {
+  const { t } = useTranslation()
+  const navigate = useNavigate()
+  const location = useLocation()
+  const router = useRouter()
+  const { menus } = useMenu()
+  const { hasPermission } = useAuth()
+  const SubmitModalComp = submitModalComponent as React.ElementType | undefined
+  const DetailModalComp = detailModalComponent as React.ElementType | undefined
+
+  const {
+    afterStatusChange,
+    deleteConfirm,
+    detailAction,
+    getDetailModalOpenExtra,
+    fetchTableData,
+    handleDelete: rawHandleDelete,
+    handleUpdateStatus: rawHandleUpdateStatus,
+    handleReset,
+    handleSearch,
+    handleTableChange,
+    loading,
+    onAdd,
+    onDetail,
+    onEdit,
+    pageInfo = {
+      listTitle: undefined,
+      subTitle: undefined,
+      title: undefined,
+    },
+    pageSizeOptions: pageSizeOptionsFromConfig,
+    paginationData,
+    patchSearchAndRefresh,
+    replaceSearchAndRefresh,
+    searchFields,
+    searchFormData,
+    setSearchFormData,
+    statusToggle,
+    submitAction,
+    table: tableConfig = {},
+    tableData,
+    tree,
+    treeAPI,
+    treeReloadSignal = 0,
+  } = pageConfig
+
+  const searchButtonSize: SearchButtonSize =
+    pageInfo.searchButtonSize ?? 'default'
+
+  const pageSizeOptions =
+    pageSizeOptionsFromConfig?.length
+      ? pageSizeOptionsFromConfig
+      : [...TABLE_VIEW_DEFAULT_PAGE_SIZE_OPTIONS]
+
+  const table = tableConfig || {}
+  const tableScrollX =
+    table.scrollX === false ? undefined : ((table.scrollX ?? 'max-content') as any)
+  const isSlicePagination = table.paginationMode === 'slice'
+
+  const hasTree = !!(treeAPI || tree)
+  const mergedTree: TreeConfig | undefined = useMemo(() => {
+    if (!hasTree) return undefined
+    return {
+      ...TABLE_VIEW_TREE_DEFAULTS,
+      ...tree,
+      title: tree?.title ?? pageInfo.title,
+    }
+  }, [hasTree, tree, pageInfo.title])
+
+  const onTreeDataChangeRef = useRef(mergedTree?.onTreeDataChange)
+  onTreeDataChangeRef.current = mergedTree?.onTreeDataChange
+
+  const stickyTitle = pageInfo.title
+    ? t(String(pageInfo.title))
+    : t('common.list_page_title', { defaultValue: 'List' })
+  const titleRef = useStickyHeader(stickyTitle)
+
+  // 删除确认弹框状态
+  const [deleteState, setDeleteState] = useState<{
+    open: boolean
+    record: any | null
+  }>({
+    open: false,
+    record: null,
+  })
+
+  const openDeleteConfirm = useCallback((record: any) => {
+    setDeleteState({
+      open: true,
+      record,
+    })
+  }, [])
+
+  const closeDeleteConfirm = useCallback(() => {
+    setDeleteState({
+      open: false,
+      record: null,
+    })
+  }, [])
+
+  const [statusToggleState, setStatusToggleState] = useState<{
+    nextStatus: number | null
+    open: boolean
+    record: any | null
+  }>({
+    nextStatus: null,
+    open: false,
+    record: null,
+  })
+
+  const openStatusToggleConfirm = useCallback(
+    (payload: { nextStatus: number; data: any }) => {
+      setStatusToggleState({
+        nextStatus: payload.nextStatus,
+        open: true,
+        record: payload.data,
+      })
+    },
+    [],
+  )
+
+  const closeStatusToggleConfirm = useCallback(() => {
+    setStatusToggleState({
+      nextStatus: null,
+      open: false,
+      record: null,
+    })
+  }, [])
+
+  const activeStatusToggleConfirm = useMemo(() => {
+    const st = statusToggle ?? {}
+    const enabledStatus = st.enabledStatus ?? 1
+    if (statusToggleState.nextStatus == null) return undefined
+    return statusToggleState.nextStatus === enabledStatus
+      ? st.enableConfirm
+      : st.disableConfirm
+  }, [statusToggle, statusToggleState.nextStatus])
+
+  const statusToggleContentInterpolation = useMemo(
+    () =>
+      buildDeleteConfirmInterpolation(
+        statusToggleState.record,
+        activeStatusToggleConfirm?.contentFields,
+      ),
+    [activeStatusToggleConfirm?.contentFields, statusToggleState.record],
+  )
+
+  const statusToggleConfirmDanger = useMemo(() => {
+    const st = statusToggle ?? {}
+    const enabledStatus = st.enabledStatus ?? 1
+    if (statusToggleState.nextStatus == null) return false
+    const isDisable = statusToggleState.nextStatus !== enabledStatus
+    if (!isDisable) return false
+    return st.dangerOnDisable !== false
+  }, [statusToggle, statusToggleState.nextStatus])
+
+  const deleteContentInterpolation = useMemo(
+    () =>
+      buildDeleteConfirmInterpolation(
+        deleteState.record,
+        deleteConfirm?.contentFields,
+      ),
+    [deleteState.record, deleteConfirm?.contentFields],
+  )
+
+  const handleConfirmDelete = async () => {
+    if (!deleteState.record) return
+    const targetRecord = deleteState.record
+    if (typeof rawHandleDelete !== 'function') {
+      console.error('[ListPageView] handleDelete 未注入，无法执行删除请求')
+      closeDeleteConfirm()
+      return
+    }
+    const deleted = await rawHandleDelete(targetRecord)
+    if (deleted !== false && typeof pageConfig.afterDelete === 'function') {
+      await pageConfig.afterDelete(targetRecord)
+    }
+    closeDeleteConfirm()
+  }
+
+  const handleConfirmStatusToggle = async () => {
+    if (
+      statusToggleState.record == null ||
+      statusToggleState.nextStatus == null
+    ) {
+      return
+    }
+    const targetRecord = statusToggleState.record
+    const nextStatus = statusToggleState.nextStatus
+    if (typeof rawHandleUpdateStatus !== 'function') {
+      console.error(
+        '[ListPageView] handleUpdateStatus 未注入，无法执行状态更新请求',
+      )
+      closeStatusToggleConfirm()
+      return
+    }
+    const ok = await rawHandleUpdateStatus(targetRecord, nextStatus)
+    if (ok !== false && typeof afterStatusChange === 'function') {
+      await afterStatusChange(targetRecord, nextStatus)
+    }
+    closeStatusToggleConfirm()
+  }
+
+  // 提交弹框 ref（新增 / 编辑）
+  const submitModalRef = React.useRef<any>(null)
+
+  // 详情弹框 ref
+  const detailModalRef = React.useRef<any>(null)
+
+  const openEditDefault = useCallback(
+    (record: any) => {
+      const config = submitAction
+
+      if (config?.submitType === 'modal' && SubmitModalComp) {
+        submitModalRef.current?.open({
+          opeType: 'edit',
+          opeId: record?.id,
+          data: record,
+        })
+        return
+      }
+
+      if (config?.submitType === 'page') {
+        const id = record?.id
+        if (id) {
+          // 编辑模式，携带 ID
+          router.toEdit({
+            state: { editId: id },
+          })
+        } else {
+          // 新增模式
+          router.toAdd()
+        }
+        return
+      }
+
+      if (isDev) {
+        console.log(
+          '默认编辑处理（请在 submitAction 中配置 submitType 或在 onEdit 中重写）',
+          { record, config },
+        )
+      }
+    },
+    [submitAction, SubmitModalComp],
+  )
+
+  const getDetailModalOpenExtraRef = useRef(getDetailModalOpenExtra)
+  getDetailModalOpenExtraRef.current = getDetailModalOpenExtra
+
+  const openDetailDefault = useCallback(
+    (record: any) => {
+      const config = detailAction
+      const id = record?.id
+
+      if (config?.detailType === 'modal' && DetailModalComp) {
+        const extra =
+          typeof getDetailModalOpenExtraRef.current === 'function'
+            ? getDetailModalOpenExtraRef.current() ?? {}
+            : {}
+        detailModalRef.current?.open({
+          opeType: 'detail',
+          opeId: id,
+          data: record,
+          ...extra,
+        })
+        return
+      }
+
+      if (config?.detailType === 'page') {
+        const id = record?.id || record?.code
+        if (id) {
+          router.toDetail(id)
+        }
+        return
+      }
+
+      if (isDev) {
+        console.log(
+          '默认详情处理（请在 detailAction 中配置 detailType 或在 onDetail 中重写）',
+          { record, config },
+        )
+      }
+    },
+    [detailAction, DetailModalComp],
+  )
+
+  useLayoutEffect(() => {
+    const page = pageConfig
+    page.onDelete = openDeleteConfirm
+    page.onEdit = (payload: {
+      config?: any
+      data?: any
+      type: string
+    }) => {
+      if (onEdit) {
+        onEdit(payload)
+        return
+      }
+      openEditDefault(payload?.data)
+    }
+    page.onDetail = (payload: {
+      config?: any
+      data?: any
+      type: string
+    }) => {
+      if (onDetail) {
+        onDetail(payload)
+        return
+      }
+      openDetailDefault(payload?.data)
+    }
+    page.onStatusToggle = openStatusToggleConfirm
+    return () => {
+      if (page.onDelete === openDeleteConfirm) {
+        delete page.onDelete
+      }
+      delete page.onEdit
+      delete page.onDetail
+      if (page.onStatusToggle === openStatusToggleConfirm) {
+        delete page.onStatusToggle
+      }
+    }
+  }, [
+    pageConfig,
+    openDeleteConfirm,
+    openStatusToggleConfirm,
+    onEdit,
+    onDetail,
+    openEditDefault,
+    openDetailDefault,
+  ])
+
+  // 新增
+  const handleAdd = () => {
+    const config = submitAction
+
+    if (onAdd) {
+      onAdd({ type: 'add', config })
+      return
+    }
+
+    if (config?.submitType === 'modal' && SubmitModalComp) {
+      submitModalRef.current?.open({ opeType: 'add' })
+      return
+    }
+
+    if (config?.submitType === 'page') {
+      router.toAdd()
+      return
+    }
+
+    if (isDev) {
+      console.log(
+        '默认新增处理（请在 submitAction 中配置 submitType 或在 onAdd 中重写）',
+        config,
+      )
+    }
+  }
+
+  const renderCell = (col: any, record: any, rowIndex: number) => {
+    const fieldKey = col.dataIndex ?? col.key
+    if (col.render) {
+      return col.render(record[fieldKey], record, rowIndex)
+    }
+    const raw = record[fieldKey]
+    if (col.ellipsis) {
+      const s = raw != null && raw !== '' ? String(raw) : '-'
+      const inner = (
+        <div className="min-w-0 max-w-full overflow-hidden">
+          <span className="block truncate">{s}</span>
+        </div>
+      )
+      if (s === '-') return inner
+      const placement = col.ellipsisTooltipPlacement ?? 'right'
+      const tw = col.ellipsisTooltipWidth
+      const maxW =
+        tw == null || tw === ''
+          ? '300px'
+          : typeof tw === 'number'
+            ? `${tw}px`
+            : String(tw)
+      return (
+        <CxTooltip
+          placement={placement}
+          styles={{
+            root: { maxWidth: maxW },
+          }}
+          title={
+            <div
+              className="max-h-[50vh] overflow-y-auto whitespace-pre-wrap break-words text-left"
+              style={{ maxWidth: maxW }}
+            >
+              {s}
+            </div>
+          }
+        >
+          {inner}
+        </CxTooltip>
+      )
+    }
+    return raw
+  }
+
+  const [form] = Form.useForm()
+
+  const applySearchFromForm = () => {
+    const vals = form.getFieldsValue(true)
+    let normalizedVals = normalizeSearchValuesByFields(vals, searchFields)
+    const treeListSearchKey =
+      mergedTree?.searchField ??
+      (treeAPI ? TABLE_VIEW_TREE_DEFAULTS.searchField : undefined)
+    if (
+      treeListSearchKey &&
+      searchFormData &&
+      Object.prototype.hasOwnProperty.call(searchFormData, treeListSearchKey)
+    ) {
+      normalizedVals = {
+        ...normalizedVals,
+        [treeListSearchKey]: searchFormData[treeListSearchKey],
+      }
+    }
+    flushSync(() => {
+      setSearchFormData?.(normalizedVals)
+    })
+    handleSearch()
+  }
+
+  const onReset = () => {
+    handleReset()
+  }
+
+  const submitPermission = submitAction?.permission ?? ''
+  const primaryLabelKey = submitAction?.labelKey ?? 'p_system.role.add'
+
+  // ===== Tree 状态 & 渲染 =====
+  const [treeData, setTreeData] = useState<any[]>([])
+  const [treeDataLoaded, setTreeDataLoaded] = useState(!hasTree)
+  const [expandedKeys, setExpandedKeys] = useState<Set<string | number>>(
+    new Set(),
+  )
+  const [selectedKey, setSelectedKey] = useState<string | number | null>(null)
+
+  const idKey = mergedTree?.fieldNames?.id ?? 'id'
+  const childrenKey = mergedTree?.fieldNames?.children ?? 'children'
+  const treeDataForSidebar = useMemo(() => {
+    const disableNode = mergedTree?.disableNode
+    if (!disableNode || !treeData.length) return treeData
+    return annotateTreeDisableNode(
+      treeData,
+      idKey,
+      childrenKey,
+      disableNode,
+    )
+  }, [treeData, mergedTree?.disableNode, idKey, childrenKey])
+  const searchField = mergedTree?.searchField ?? 'id'
+  const autoSearch = mergedTree?.autoSearch ?? true
+  const unselectText = mergedTree?.unselectText ?? 'common.unselect_tree'
+
+  useEffect(() => {
+    if (!treeAPI) {
+      setTreeDataLoaded(true)
+      if (hasTree && isDev) {
+        console.warn('[ListPageView] 已启用树区域但未提供 treeAPI')
+      }
+      return
+    }
+
+    let mounted = true
+    setTreeDataLoaded(false)
+
+    treeAPI()
+      .then((raw) => {
+        if (!mounted) return
+        const normalized = normalizeTreeAPIResult(raw)
+        setTreeData(normalized)
+        setTreeDataLoaded(true)
+        onTreeDataChangeRef.current?.(normalized)
+      })
+      .catch((error) => {
+        if (!mounted) return
+        console.error('[ListPageView] Tree fetch error:', error)
+        setTreeDataLoaded(true)
+      })
+    return () => {
+      mounted = false
+    }
+  }, [treeAPI, hasTree, treeReloadSignal])
+
+  useEffect(() => {
+    if (!mergedTree?.defaultExpandAll || !treeData.length) return
+    setExpandedKeys(
+      new Set(collectAllTreeNodeKeys(treeData, idKey, childrenKey)),
+    )
+  }, [treeData, mergedTree?.defaultExpandAll, idKey, childrenKey])
+
+  const findNodeByKey = (nodes: any[], key: any): any | null => {
+    for (const n of nodes) {
+      if (n[idKey] === key) return n
+      const children = n[childrenKey]
+      if (Array.isArray(children)) {
+        const found = findNodeByKey(children, key)
+        if (found) return found
+      }
+    }
+    return null
+  }
+
+  const toggleTreeExpand = (key: any, e?: React.MouseEvent) => {
+    if (e) e.stopPropagation()
+    setExpandedKeys((prev) => {
+      const next = new Set(prev)
+      if (next.has(key)) next.delete(key)
+      else next.add(key)
+      return next
+    })
+  }
+
+  const handleTreeSelect = (key: any) => {
+    const formSnap = normalizeSearchValuesByFields(
+      form.getFieldsValue(true),
+      searchFields ?? [],
+    )
+    const mergedBase = { ...(searchFormData || {}), ...formSnap }
+
+    if (key == null) {
+      setSelectedKey(null)
+      mergedTree?.onSelect?.(null)
+      if (!mergedTree?.searchField) return
+      const next = { ...mergedBase }
+      delete next[searchField]
+      if (replaceSearchAndRefresh && autoSearch) {
+        replaceSearchAndRefresh(next)
+      } else if (setSearchFormData) {
+        flushSync(() => {
+          setSearchFormData(next)
+        })
+        if (autoSearch) handleSearch()
+      }
+      return
+    }
+
+    setSelectedKey(key)
+    const node = findNodeByKey(treeData, key)
+    if (!node) return
+
+    if (mergedTree?.onSelect) {
+      mergedTree.onSelect(node)
+    }
+
+    if (!mergedTree?.searchField) return
+
+    const full = { ...mergedBase, [searchField]: node[idKey] }
+
+    if (patchSearchAndRefresh && autoSearch) {
+      patchSearchAndRefresh(full)
+    } else if (setSearchFormData) {
+      flushSync(() => {
+        setSearchFormData(full)
+      })
+      if (autoSearch) handleSearch()
+    }
+  }
+
+  // 默认 defaultSelectRoot 为 true；仅显式 false 时不自动选根
+  useEffect(() => {
+    if (mergedTree?.defaultSelectRoot === false) return
+    if (!treeDataLoaded || treeData.length === 0) return
+    if (selectedKey != null) return
+    const root = treeData[0]
+    const key = root?.[idKey]
+    if (key === undefined || key === null) return
+    handleTreeSelect(key)
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- 仅在树就绪且无选中时触发；避免 handleTreeSelect 变化导致重复
+  }, [
+    mergedTree?.defaultSelectRoot,
+    treeDataLoaded,
+    treeData,
+    idKey,
+    selectedKey,
+  ])
+
+  const selectedNode =
+    selectedKey != null ? findNodeByKey(treeData, selectedKey) : null
+  const treeCtx: TreeContext | undefined = mergedTree
+    ? { selectedKey, selectedNode, treeData, treeDataLoaded }
+    : undefined
+
+  const listRenderContext: ListRenderContext & {
+    tree?: TreeContext
+  } = {
+    columns: columns ?? [],
+    renderCell,
+    tableData,
+    t,
+    tree: treeCtx,
+  }
+
+  // 将 treeContext 暴露给 pageConfig，供页面组件使用
+  React.useEffect(() => {
+    if (pageConfig) {
+      ;(pageConfig as any).treeContext = treeCtx
+    }
+  }, [treeCtx, pageConfig])
+
+  const showListArea =
+    !mergedTree ||
+    !!selectedKey ||
+    mergedTree?.sameNodeReselect === 'deselect'
+  const showNoDataEmpty = showListArea &&
+    (isSlicePagination ? tableData.length === 0 : paginationData.total === 0)
+
+  // 分页与表格边线处理交给 CSS（分页区 -1px 覆盖最后一行 border），避免监听滚动带来的卡顿
+  const headerActionsContent =
+    typeof headerActions === 'function'
+      ? (headerActions as HeaderActionsRender)({ tree: treeCtx })
+      : headerActions
+  const hasHeaderActionsContent =
+    headerActionsContent !== undefined &&
+    headerActionsContent !== null &&
+    headerActionsContent !== false
+
+  const searchAreaExtraNode =
+    searchAreaExtra == null || searchAreaExtra === false
+      ? null
+      : typeof searchAreaExtra === 'function'
+        ? (
+            searchAreaExtra as (ctx: {
+              searchButtonSize: SearchButtonSize
+              tree?: TreeContext
+            }) => React.ReactNode
+          )({ tree: treeCtx, searchButtonSize })
+        : searchAreaExtra
+
+  /** 顶部标题图标：未显式传入时从菜单配置自动推导。 */
+  const resolvedTitleIcon = useMemo(() => {
+    if (titleIcon) return titleIcon
+    const currentPath = location.pathname || ''
+    const listPath = getListPathFromSubRoutePathname(currentPath) || currentPath
+    const normalize = (p: string) =>
+      (p || '')
+        .replace(/\/(index|detail|submit)(\/.*)?$/, '')
+        .replace(/\/+$/, '')
+    const target = normalize(listPath)
+    if (!target) return undefined
+
+    const flat = flattenMenuTree(menus || [])
+    const matched = flat.find((m) => normalize(m?.path || '') === target)
+    const Icon = getIconComponent(matched?.icon)
+    if (!Icon) return undefined
+    return <Icon className="text-blue-400" size={32} />
+  }, [location.pathname, menus, titleIcon])
+
+  // ===== 统一外层布局：顶部标题区域 + 中间内容（可选左树右表） =====
+  return (
+    <div className="p-8 mx-auto w-full flex-1 h-full min-h-0 flex flex-col box-border overflow-hidden">
+      {/* 顶部标题区域 */}
+      <div className="flex justify-between items-center mb-6">
+        <div
+          className={`flex min-w-0 gap-3 ${showBackToList ? 'items-center' : 'items-start gap-2'}`}>
+          {showBackToList ? (
+            <CxButton.Icon
+              className="!p-2.5 shrink-0 rounded-lg border border-solid border-gray-300 bg-white shadow-sm dark:border-gray-600 dark:bg-gray-900"
+              icon={<ChevronLeft size={22} strokeWidth={2.25} />}
+              title={t('common.back')}
+              tooltipTone="default"
+              type="default"
+              onClick={() => router.toIndex()}
+            />
+          ) : null}
+          <div className="min-w-0 flex-1">
+            <h1
+              ref={titleRef}
+              className="text-3xl font-bold bg-clip-text text-transparent bg-gradient-to-r from-blue-400 to-purple-500 flex flex-wrap items-center gap-3">
+              {resolvedTitleIcon ?? <ShieldUser className="text-blue-400" size={32} />}
+              {pageInfo.title ? t(String(pageInfo.title)) : ''}
+              {titleExtra}
+            </h1>
+            <p className="text-gray-500 dark:text-gray-400 mt-1">
+              {pageInfo.subTitle ? t(String(pageInfo.subTitle)) : ''}
+            </p>
+          </div>
+        </div>
+        <div className="flex flex-wrap gap-2 items-center justify-end">
+          {headerActionsContent}
+          {!hasHeaderActionsContent && submitPermission && hasPermission(submitPermission) && (
+            <CxButton.Add
+              size="medium"
+              icon={<Plus size={20} />}
+              onClick={handleAdd}>
+              {t(primaryLabelKey)}
+            </CxButton.Add>
+          )}
+        </div>
+      </div>
+      {/* 中间区域：有树时左右分栏，否则只显示右侧卡片 */}
+      <div
+        className="flex flex-1 min-h-0 gap-6"
+        style={{ minHeight: 0 }}>
+        {/* 左侧树：数据来自 treeAPI；tree 仅合并 TreeConfig（字段名、defaultSelectRoot 等） */}
+        {mergedTree && (
+          <TreeSidebar
+            expandedKeys={expandedKeys}
+            onSelect={handleTreeSelect}
+            onToggleExpand={toggleTreeExpand}
+            selectedKey={selectedKey}
+            tree={mergedTree}
+            treeData={treeDataForSidebar}
+          />
+        )}
+        {/* 右侧：Header / Toolbar + 搜索 + 表格 + 分页，统一包在一张大卡片里 */}
+        <div
+          className="flex-1 min-w-0 flex flex-col"
+        >
+          <div className="flex-1 bg-white dark:bg-gray-800 rounded-xl shadow-sm border border-gray-200 dark:border-gray-700 flex flex-col overflow-hidden">
+            {/* Header / Toolbar（可访问树上下文） */}
+            {tableActions &&
+            (!mergedTree ||
+              selectedKey != null ||
+              mergedTree?.sameNodeReselect === 'deselect') ? (
+              <TableActions
+                searchButtonSize={searchButtonSize}
+                tree={treeCtx}>
+                {tableActions}
+              </TableActions>
+            ) : null}
+            {/* 搜索区域 */}
+            {searchSlot ? (
+              searchSlot
+            ) : ((mergedTree &&
+                (selectedKey != null ||
+                  mergedTree?.sameNodeReselect === 'deselect')) ||
+                !mergedTree) &&
+              searchFields &&
+              searchFields.length > 0 ? (
+              <SearchArea
+                extra={searchAreaExtraNode}
+                form={form}
+                listTitle={pageInfo.listTitle}
+                onReset={onReset}
+                onSearch={applySearchFromForm}
+                searchButtonSize={searchButtonSize}
+                searchFields={searchFields}
+                searchFormData={searchFormData}
+                total={paginationData.total}
+              />
+            ) : null}
+            {/* 表格区域（表头固定：由 Table 内部滚动承载） */}
+            <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+              {showListArea && (!showNoDataEmpty || renderList) && (
+                <div className="min-h-0 flex-1">
+                  {renderList ? (
+                    renderList(listRenderContext)
+                  ) : (
+                    <div className="h-full min-h-0">
+                      <CxTable
+                        autoScrollY
+                        minScrollY={160}
+                        sticky
+                        dataSource={tableData}
+                        rowKey="id"
+                        // 透传列配置，避免丢失 minWidth/ellipsis/fixed/onCell 等属性
+                        columns={(columns ?? []).map((col: any) => ({
+                          ...col,
+                          key: col.key ?? col.dataIndex,
+                          dataIndex: col.dataIndex ?? col.key,
+                          title:
+                            typeof col.title === 'string' ? t(col.title) : col.title,
+                          render: (_: unknown, record: any, rowIndex: number) =>
+                            renderCell(col, record, rowIndex),
+                        }))}
+                        tableLayout={tableScrollX ? 'auto' : 'fixed'}
+                        scroll={tableScrollX ? ({ x: tableScrollX } as any) : undefined}
+                      />
+                    </div>
+                  )}
+                </div>
+              )}
+
+              {mergedTree &&
+                selectedKey == null &&
+                mergedTree?.sameNodeReselect !== 'deselect' && (
+                <CxEmptyState message={t(unselectText)} />
+              )}
+
+              {!renderList && showNoDataEmpty && <CxEmptyState message={t('common.no_data')} />}
+            </div>
+            {/* 分页 */}
+            {table.showPagination !== false &&
+              (isSlicePagination || paginationData.total > 0) && (
+              <div className="relative z-[1] -mt-px px-3 py-3 bg-white dark:bg-gray-800 border-t border-gray-200 dark:border-gray-700">
+                <Pagination
+                  onPageChange={(page) => {
+                    handleTableChange({
+                      current: page,
+                      pageSize: paginationData.pageSize,
+                    })
+                  }}
+                  onPageSizeChange={(size) => {
+                    handleTableChange({
+                      current: paginationData.page,
+                      pageSize: size,
+                    })
+                  }}
+                  page={paginationData.page}
+                  pageSize={paginationData.pageSize}
+                  pageSizeOptions={pageSizeOptions}
+                  showSizeChanger
+                  showStats={!isSlicePagination}
+                  variant={isSlicePagination ? 'slice' : 'spread'}
+                  total={paginationData.total}
+                  isFirst={paginationData.first}
+                  isLast={paginationData.last}
+                  zeroIndexed={false}
+                  disabled={loading}
+                />
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* 删除确认弹窗 & 提交 / 详情弹窗 */}
+      <ConfirmDialog
+        cancelText={
+          deleteConfirm?.cancelText ? String(t(deleteConfirm.cancelText)) : undefined
+        }
+        confirmText={
+          deleteConfirm?.okText ? String(t(deleteConfirm.okText)) : undefined
+        }
+        danger
+        isOpen={deleteState.open}
+        message={
+          deleteConfirm?.content
+            ? String(t(deleteConfirm.content, deleteContentInterpolation))
+            : ''
+        }
+        title={String(t(deleteConfirm?.title ?? 'common.tip'))}
+        onClose={closeDeleteConfirm}
+        onConfirm={handleConfirmDelete}
+      />
+
+      <ConfirmDialog
+        cancelText={
+          activeStatusToggleConfirm?.cancelText
+            ? String(t(activeStatusToggleConfirm.cancelText))
+            : undefined
+        }
+        confirmText={
+          activeStatusToggleConfirm?.okText
+            ? String(t(activeStatusToggleConfirm.okText))
+            : undefined
+        }
+        danger={statusToggleConfirmDanger}
+        isOpen={statusToggleState.open}
+        message={
+          activeStatusToggleConfirm?.content
+            ? String(
+                t(
+                  activeStatusToggleConfirm.content,
+                  statusToggleContentInterpolation,
+                ),
+              )
+            : ''
+        }
+        title={String(t(activeStatusToggleConfirm?.title ?? 'common.tip'))}
+        onClose={closeStatusToggleConfirm}
+        onConfirm={handleConfirmStatusToggle}
+      />
+
+      {SubmitModalComp && (
+        <SubmitModalComp
+          ref={submitModalRef}
+          onOk={async (values: unknown) => {
+            if (isDev) {
+              console.log('提交表单', values)
+            }
+            await fetchTableData?.()
+          }}
+          onCancel={() => {
+            // 取消时的清理逻辑(可选)
+          }}
+        />
+      )}
+
+      {DetailModalComp && <DetailModalComp ref={detailModalRef} />}
+    </div>
+  )
+}
+
+export default ListPageView