@pnt-team/pnt-component-frontend 0.0.138 → 0.0.139

package/lib/esm/components/PntTable/index.js

@@ -0,0 +1,404 @@
+/**
+ * PntTable — 统一表格组件
+ *
+ * 封装 tdesign-react Table，落地产品规范 12 章 47 条规则：
+ *   排序三态循环、筛选草稿/生效分离、多选三态+翻页清空、分页越界校验、
+ *   请求顺序控制、7 种状态管理、蓝紫双主题、同字段 sort+headerFilter 互斥。
+ *
+ * 零业务侵入：业务项目通过 fetcher 注入数据源，不依赖组件库内部 API。
+ */
+
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useState } from 'react';
+import { Table } from 'tdesign-react';
+import "./index.scss";
+import { getPntTableTextsByLocale } from "./types";
+import { useTableCore, validateColumnConflicts } from "./useTableCore";
+
+// ============================================================
+// 常量
+// ============================================================
+import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment } from "react/jsx-runtime";
+const DEFAULT_PAGE_SIZE_OPTIONS = [10, 20, 50];
+
+// ============================================================
+// 工具：列定义转换
+// ============================================================
+
+function getDefaultAlign(type) {
+  switch (type) {
+    case 'number':
+    case 'money':
+    case 'percent':
+      return 'right';
+    default:
+      return 'left';
+  }
+}
+function mapPntColumns(pntCols) {
+  return pntCols.map(col => {
+    const mapped = {
+      colKey: col.key,
+      title: col.title,
+      width: col.width,
+      fixed: col.fixed,
+      align: col.align ?? getDefaultAlign(col.type),
+      ellipsis: col.ellipsis === false ? undefined : col.ellipsis ?? true
+    };
+
+    // 排序
+    if (col.sort) {
+      mapped.sorter = true;
+    }
+
+    // 筛选
+    if (col.headerFilter) {
+      if (col.headerFilter.mode === 'custom') {
+        // 自定义组件（例：DateRangePickerPanel）
+        mapped.filter = {
+          type: 'custom',
+          component: col.headerFilter.component,
+          ...(col.headerFilter.extra ?? {})
+        };
+      } else if (col.headerFilter.options?.length) {
+        // 静态选项单选/多选
+        mapped.filter = {
+          type: col.headerFilter.mode === 'multiple' ? 'multiple' : 'single',
+          list: col.headerFilter.options,
+          ...(col.headerFilter.extra ?? {})
+        };
+      }
+    }
+
+    // 自定义渲染
+    if (col.cell) {
+      mapped.cell = ({
+        row,
+        rowIndex
+      }) => col.cell(row, rowIndex);
+    }
+
+    // 表头说明（用 title 包裹 + CSS tooltip）
+    if (col.help && typeof mapped.title === 'string') {
+      mapped.title = /*#__PURE__*/_jsxs("span", {
+        className: "pnt-table-col-title",
+        children: [mapped.title, /*#__PURE__*/_jsx("span", {
+          className: "pnt-table-help-icon",
+          title: col.help,
+          children: "\u24D8"
+        })]
+      });
+    }
+    return mapped;
+  });
+}
+
+// ============================================================
+// 主组件
+// ============================================================
+
+export const PntTable = /*#__PURE__*/forwardRef((props, ref) => {
+  const {
+    tableId,
+    theme = 'business',
+    rowKey,
+    columns,
+    dataMode,
+    fetcher,
+    data,
+    total: clientTotal,
+    selectable = false,
+    currentPageOnly = true,
+    pageable = true,
+    initialPage = 1,
+    pageSize: initialPageSize = 10,
+    pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
+    empty,
+    locale = 'zh',
+    texts,
+    emptyText,
+    emptyWithFilterHint,
+    bordered = false,
+    size = 'medium',
+    loading: controlledLoading,
+    bodyMaxHeight,
+    businessId,
+    env,
+    timezone,
+    onQueryChange,
+    onSelectionChange,
+    className,
+    style,
+    rowClassName
+  } = props;
+
+  // --- 文案合并：texts 逐字段覆盖 > locale 内置文案 ---
+  const mergedTexts = useMemo(() => ({
+    ...getPntTableTextsByLocale(locale),
+    ...(texts ?? {})
+  }), [locale, texts]);
+  // 兼容既有 props：emptyText / emptyWithFilterHint 优先级高于 texts / locale
+  const finalEmptyText = emptyText ?? mergedTexts.empty;
+  const finalEmptyWithFilterHint = emptyWithFilterHint ?? mergedTexts.emptyWithFilter;
+
+  // --- selectable 配置展开 ---
+  const selectConfig = useMemo(() => {
+    if (!selectable) return null;
+    if (typeof selectable === 'object') return selectable;
+    return {}; // 空对象表示启用多选但无额外配置
+  }, [selectable]);
+  const isSelectable = !!selectConfig;
+  const effectiveCurrentPageOnly = selectConfig?.currentPageOnly ?? currentPageOnly;
+  const controlledSelectedRowKeys = selectConfig?.selectedRowKeys;
+  const disabledRowKeysFn = selectConfig?.disabledRowKeysFn;
+
+  // --- 受控选中行 state ---
+  const [internalSelectedRowKeys, setInternalSelectedRowKeys] = useState(() => controlledSelectedRowKeys ?? []);
+  // 同步受控 prop 变化
+  useEffect(() => {
+    if (controlledSelectedRowKeys !== undefined) {
+      setInternalSelectedRowKeys(controlledSelectedRowKeys);
+    }
+  }, [controlledSelectedRowKeys]);
+
+  // --- core hook ---
+  const core = useTableCore({
+    tableId,
+    rowKey,
+    columns,
+    dataMode,
+    fetcher,
+    data,
+    total: clientTotal,
+    initialPage,
+    pageSize: initialPageSize,
+    pageSizeOptions,
+    businessId,
+    env,
+    timezone,
+    onQueryChange,
+    onSelectionChange,
+    selectable: isSelectable,
+    currentPageOnly: effectiveCurrentPageOnly
+  });
+
+  // --- imperative handle ---
+  useImperativeHandle(ref, () => ({
+    refresh: () => core.refresh(),
+    reset: () => {
+      core.resetFilters();
+      core.setPage(1);
+    },
+    getQuerySnapshot: () => ({
+      sort: core.sort,
+      filters: core.appliedFilters,
+      page: core.page,
+      pageSize: core.pageSize,
+      total: core.total
+    })
+  }));
+
+  // --- 开发阶段互斥校验 ---
+  const conflicts = useMemo(() => validateColumnConflicts(columns), [columns]);
+  useEffect(() => {
+    if (conflicts.length > 0) {
+      conflicts.forEach(c => console.error(c));
+    }
+  }, [conflicts]);
+
+  // --- 列定义转换 ---
+  const tdesignCols = useMemo(() => {
+    const mapped = mapPntColumns(columns);
+    // 多选模式：插入选择列
+    if (isSelectable) {
+      mapped.unshift({
+        colKey: 'pnt-row-select',
+        type: 'multiple',
+        width: 64,
+        checkProps: disabledRowKeysFn ? ({
+          row
+        }) => ({
+          disabled: disabledRowKeysFn(row)
+        }) : undefined
+      });
+    }
+    return mapped;
+  }, [columns, isSelectable, disabledRowKeysFn]);
+
+  // --- defaultSort 映射（TDesign 用 SortInfo：{ sortBy, descending }） ---
+  const defaultSortInfo = useMemo(() => {
+    if (!core.sort) return undefined;
+    return {
+      sortBy: core.sort.field,
+      descending: core.sort.direction === 'desc'
+    };
+  }, [core.sort]);
+
+  // --- 筛选 filterValue 映射 ---
+  const filterValue = useMemo(() => {
+    const fv = {};
+    Object.entries(core.appliedFilters).forEach(([k, v]) => {
+      fv[k] = v;
+    });
+    return Object.keys(fv).length > 0 ? fv : undefined;
+  }, [core.appliedFilters]);
+
+  // --- 排序三态处理（TDesign onSortChange 返回 TableSort） ---
+  const handleSortChange = useCallback(sort => {
+    // TDesign 可能返回 SortInfo 或 SortInfo[]，取第一个
+    const info = Array.isArray(sort) ? sort[0] : sort;
+    if (!info) return;
+    const field = info.sortBy;
+    const currentDir = info.descending ? 'desc' : 'asc';
+    core.toggleSort(field);
+    void currentDir; // core.toggleSort 内部会自己处理三态
+  }, [core]);
+
+  // --- 筛选处理 ---
+  const handleFilterChange = useCallback(filterVal => {
+    core.applyFilters(filterVal);
+  }, [core]);
+
+  // --- 分页处理 ---
+  const pagination = useMemo(() => {
+    if (!pageable) return undefined;
+    return {
+      total: core.total,
+      current: core.page,
+      pageSize: core.pageSize,
+      pageSizeOptions,
+      showJumper: true,
+      showPageSize: true,
+      onChange: pageInfo => {
+        const {
+          current,
+          pageSize: size
+        } = pageInfo;
+        if (current !== core.page) core.setPage(current);
+        if (size !== core.pageSize) core.setPageSize(size);
+      }
+    };
+  }, [pageable, core.total, core.page, core.pageSize, pageSizeOptions, core.setPage, core.setPageSize]);
+
+  // --- 加载态 ---
+  const isLoading = typeof controlledLoading === 'boolean' ? controlledLoading : core.status === 'loading' || core.status === 'refreshing';
+
+  // --- 空态内容（不用 Empty 组件，直接 ReactNode） ---
+  const emptyContent = useMemo(() => {
+    if (core.status === 'error') {
+      return /*#__PURE__*/_jsx("div", {
+        className: "pnt-table-empty",
+        children: /*#__PURE__*/_jsx("div", {
+          className: "pnt-table-empty-desc",
+          children: core.error || mergedTexts.loadFailed
+        })
+      });
+    }
+    if (core.status === 'no-permission') {
+      return /*#__PURE__*/_jsx("div", {
+        className: "pnt-table-empty",
+        children: /*#__PURE__*/_jsx("div", {
+          className: "pnt-table-empty-desc",
+          children: mergedTexts.noPermission
+        })
+      });
+    }
+    if (core.status === 'empty-with-filter') {
+      return /*#__PURE__*/_jsxs("div", {
+        className: "pnt-table-empty",
+        children: [/*#__PURE__*/_jsx("div", {
+          className: "pnt-table-empty-desc",
+          children: finalEmptyText
+        }), /*#__PURE__*/_jsx("div", {
+          className: "pnt-table-empty-hint",
+          children: finalEmptyWithFilterHint
+        })]
+      });
+    }
+    if (core.status === 'empty') {
+      if (empty) return /*#__PURE__*/_jsx(_Fragment, {
+        children: empty
+      });
+      return /*#__PURE__*/_jsx("div", {
+        className: "pnt-table-empty",
+        children: /*#__PURE__*/_jsx("div", {
+          className: "pnt-table-empty-desc",
+          children: finalEmptyText
+        })
+      });
+    }
+    return undefined;
+  }, [core.status, core.error, empty, mergedTexts, finalEmptyText, finalEmptyWithFilterHint]);
+
+  // --- 多选处理 ---
+  const handleSelectChange = useCallback(selectedRowKeys => {
+    if (!isSelectable) return;
+    const currentPageKeys = core.data.map(r => String(r[rowKey]));
+    const disabledKeys = disabledRowKeysFn ? core.data.filter(disabledRowKeysFn).map(r => String(r[rowKey])) : [];
+    const disabledSet = new Set(disabledKeys);
+
+    // 过滤掉禁用行的勾选
+    let keys = selectedRowKeys.map(String).filter(k => !disabledSet.has(k));
+    if (effectiveCurrentPageOnly) {
+      keys = keys.filter(k => currentPageKeys.includes(k));
+    }
+    if (controlledSelectedRowKeys === undefined) {
+      // 非受控：内部维护
+      setInternalSelectedRowKeys(keys);
+    }
+    const selectedRows = keys.map(k => core.data.find(r => String(r[rowKey]) === k) ?? {
+      [rowKey]: k
+    });
+    onSelectionChange?.(selectedRows, {
+      tableId,
+      pageKeys: currentPageKeys,
+      disabledKeys,
+      trigger: 'select'
+    });
+  }, [isSelectable, core.data, rowKey, disabledRowKeysFn, effectiveCurrentPageOnly, controlledSelectedRowKeys, tableId, onSelectionChange]);
+
+  // --- 滚动（类型宽松，TDesign 不同版本 TScroll 定义不同） ---
+  const scroll = useMemo(() => {
+    if (!bodyMaxHeight) return undefined;
+    return {
+      y: bodyMaxHeight
+    };
+  }, [bodyMaxHeight]);
+
+  // ============================================================
+  // 渲染
+  // ============================================================
+
+  return /*#__PURE__*/_jsx("div", {
+    "data-theme": theme,
+    className: `pnt-table ${className ?? ''}`,
+    style: style,
+    children: /*#__PURE__*/_jsx(Table, {
+      rowKey: rowKey,
+      data: core.data,
+      columns: tdesignCols,
+      loading: isLoading,
+      hover: true,
+      stripe: false,
+      bordered: bordered,
+      verticalAlign: "middle",
+      size: size,
+      defaultSort: defaultSortInfo,
+      filterValue: filterValue,
+      loadingProps: {
+        text: mergedTexts.loading
+      },
+      pagination: pagination,
+      scroll: scroll,
+      empty: emptyContent,
+      selectedRowKeys: isSelectable ? controlledSelectedRowKeys ?? internalSelectedRowKeys : undefined,
+      onSortChange: handleSortChange,
+      onFilterChange: handleFilterChange,
+      onSelectChange: handleSelectChange,
+      rowClassName: rowClassName
+    })
+  });
+});
+PntTable.displayName = 'PntTable';
+export default PntTable;

package/lib/esm/components/PntTable/index.scss

@@ -0,0 +1,290 @@
+/**
+ * PntTable 蓝紫双主题样式
+ *
+ * CSS 变量映射：一套样式两类主题
+ *   data-theme="business"  → 蓝主题（业务侧，默认）
+ *   data-theme="internal"  → 紫主题（内部平台）
+ *
+ * 规范来源：管理端组件规范 TBL-02.01 / TBL-02.02
+ */
+
+// ============================================================
+// CSS 变量（默认蓝主题）
+// ============================================================
+
+.pnt-table {
+  // 主题品牌色
+  --pnt-table-brand: #3f8cff;
+  --pnt-table-brand-hover: #2875e3;
+  --pnt-table-brand-active: #1f65cc;
+  --pnt-table-brand-soft: #eaf3ff;
+
+  // 语义色（不随主题变化）
+  --pnt-table-danger: #d54941;
+  --pnt-table-danger-soft: #fdecea;
+  --pnt-table-success: #2ba471;
+  --pnt-table-success-soft: #e3f6ee;
+  --pnt-table-warning: #e37318;
+  --pnt-table-warning-soft: #fef3e8;
+
+  // 中性色
+  --pnt-table-bg: #ffffff;
+  --pnt-table-bg-header: #f8fafd;
+  --pnt-table-bg-hover: #f8fafd;
+  --pnt-table-bg-selected: var(--pnt-table-brand-soft);
+  --pnt-table-border: #e5e8ef;
+  --pnt-table-text-primary: #1d2129;
+  --pnt-table-text-secondary: #4e5969;
+  --pnt-table-text-tertiary: #86909c;
+  --pnt-table-text-placeholder: #bbbfc4;
+
+  // 尺寸（TBL-02.04 / TBL-02.05）
+  --pnt-table-header-height: 48px;
+  --pnt-table-row-min-height: 48px;
+  --pnt-table-cell-padding-v: 12px;
+  --pnt-table-cell-padding-h: 16px;
+}
+
+// 紫主题覆盖
+.pnt-table[data-theme='internal'] {
+  --pnt-table-brand: #624beb;
+  --pnt-table-brand-hover: #503bd1;
+  --pnt-table-brand-active: #412eb5;
+  --pnt-table-brand-soft: #f0edff;
+}
+
+// ============================================================
+// 表头（TBL-03.01 / TBL-03.02 / TBL-03.03）
+// ============================================================
+
+.pnt-table .t-table__header {
+  background-color: var(--pnt-table-bg-header);
+  font-weight: 600;
+  color: var(--pnt-table-text-primary);
+  font-size: 14px;
+  line-height: var(--pnt-table-header-height);
+}
+
+.pnt-table .t-table__header th {
+  height: var(--pnt-table-header-height);
+  padding: 0 var(--pnt-table-cell-padding-h);
+  border-bottom: 1px solid var(--pnt-table-border);
+  border-right: none;
+  background-color: var(--pnt-table-bg-header);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+// 表头单元格（左中右对齐）
+.pnt-table .t-table__header th.tdesign-table-td--left { text-align: left; }
+.pnt-table .t-table__header th.tdesign-table-td--center,
+.pnt-table .t-table__header th.tdesign-table-td--middle { text-align: center; }
+.pnt-table .t-table__header th.tdesign-table-td--right { text-align: right; }
+
+// ============================================================
+// 表体（TBL-03.03 / TBL-03.05 / TBL-03.06）
+// ============================================================
+
+.pnt-table .t-table__body td {
+  padding: var(--pnt-table-cell-padding-v) var(--pnt-table-cell-padding-h);
+  min-height: var(--pnt-table-row-min-height);
+  border-bottom: 1px solid var(--pnt-table-border);
+  font-size: 14px;
+  color: var(--pnt-table-text-primary);
+}
+
+// hover 态（TBL-02.03 / TBL-02.08）
+.pnt-table .t-table__body tr:hover > td {
+  background-color: var(--pnt-table-bg-hover);
+}
+
+// 选中态（TBL-02.09 / TBL-02.10）
+.pnt-table .t-table__body tr.is-selected > td {
+  background-color: var(--pnt-table-bg-selected);
+}
+// 选中后 hover 仍保持选中背景
+.pnt-table .t-table__body tr.is-selected:hover > td {
+  background-color: var(--pnt-table-bg-selected);
+}
+
+// 斑马纹：默认关闭（TBL-02.03 明确默认无）
+// 业务需要时显式传 stripe 开启，PntTable 默认 false
+
+// ============================================================
+// 对齐（TBL-03.06）
+// ============================================================
+
+.pnt-table .tdesign-table-td--left,
+.pnt-table .tdesign-table-td--start { text-align: left; }
+.pnt-table .tdesign-table-td--center,
+.pnt-table .tdesign-table-td--middle { text-align: center; }
+.pnt-table .tdesign-table-td--right,
+.pnt-table .tdesign-table-td--end { text-align: right; }
+
+// ============================================================
+// 列标题 + help icon
+// ============================================================
+
+.pnt-table-col-title {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+
+  .pnt-table-help-icon {
+    display: inline-flex;
+    width: 14px;
+    height: 14px;
+    border-radius: 50%;
+    background: var(--pnt-table-border);
+    color: var(--pnt-table-text-tertiary);
+    font-size: 10px;
+    line-height: 14px;
+    justify-content: center;
+    cursor: help;
+    flex-shrink: 0;
+
+    &:hover {
+      background: var(--pnt-table-brand);
+      color: #fff;
+    }
+  }
+}
+
+// ============================================================
+// 空态（TBL-09.03 / TBL-09.04）
+// ============================================================
+
+.pnt-table .t-table__empty,
+.pnt-table .t-empty {
+  padding: 48px 0;
+  color: var(--pnt-table-text-tertiary);
+  font-size: 14px;
+}
+
+.pnt-table-empty-with-filter {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+
+  .pnt-table-empty-hint {
+    font-size: 12px;
+    color: var(--pnt-table-text-tertiary);
+  }
+}
+
+// ============================================================
+// 分页（TBL-07.01 / TBL-07.06）
+// ============================================================
+
+.pnt-table .t-pagination {
+  padding: 16px 0;
+  justify-content: flex-end;
+  gap: 12px;
+  font-size: 14px;
+  color: var(--pnt-table-text-secondary);
+
+  .t-pagination__btn {
+    border: none;
+    border-radius: 4px;
+    padding: 0 8px;
+    height: 32px;
+
+    &:hover:not(.is-disabled) {
+      color: var(--pnt-table-brand);
+    }
+
+    &.is-active {
+      background: var(--pnt-table-brand);
+      color: #fff;
+    }
+  }
+
+  .t-pagination__total {
+    margin-right: auto;
+  }
+
+  .t-pagination__size,
+  .t-pagination__jump {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+}
+
+// ============================================================
+// 加载态（TBL-09.01 / TBL-09.02）
+// ============================================================
+
+.pnt-table .t-table__loading {
+  position: absolute;
+  inset: 0;
+  background: rgba(255, 255, 255, 0.6);
+  z-index: 1;
+
+  .t-table__loading-text {
+    color: var(--pnt-table-text-secondary);
+    font-size: 14px;
+  }
+}
+
+// 骨架（首次加载）
+.pnt-table .t-table__loading--skeleton {
+  .t-table__body tr td {
+    height: var(--pnt-table-row-min-height);
+  }
+}
+
+// ============================================================
+// 固定列（TBL-08.01 / TBL-08.02）
+// ============================================================
+
+
+// 固定列跟随 hover/选中背景
+.pnt-table .t-table__body tr:hover > td.t-table__cell--fixed-left,
+.pnt-table .t-table__body tr:hover > td.t-table__cell--fixed-right {
+  background-color: var(--pnt-table-bg-hover);
+}
+
+.pnt-table .t-table__body tr.is-selected > td.t-table__cell--fixed-left,
+.pnt-table .t-table__body tr.is-selected > td.t-table__cell--fixed-right {
+  background-color: var(--pnt-table-bg-selected);
+}
+
+// ============================================================
+// 多选列（TBL-06.01 / TBL-06.02）
+// ============================================================
+
+.pnt-table .t-table__select {
+  width: 44px;
+  text-align: center;
+
+  .t-checkbox {
+    cursor: pointer;
+  }
+}
+
+// ============================================================
+// 滚动容器
+// ============================================================
+
+.pnt-table .t-table__body-wrapper::-webkit-scrollbar,
+.pnt-table .t-table__header-wrapper::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+.pnt-table .t-table__body-wrapper::-webkit-scrollbar-thumb,
+.pnt-table .t-table__header-wrapper::-webkit-scrollbar-thumb {
+  background: #c9cdd4;
+  border-radius: 4px;
+
+  &:hover {
+    background: var(--pnt-table-brand);
+  }
+}
+
+.pnt-table .t-table__body-wrapper::-webkit-scrollbar-track,
+.pnt-table .t-table__header-wrapper::-webkit-scrollbar-track {
+  background: transparent;
+}