# https://github.com/icflorescu/mantine-datatable 项目说明书

生成时间：2026-06-05 17:09:41 UTC

## 目录

- [项目概览与快速上手](#page-1)
- [DataTable 核心组件与列管理](#page-2)
- [行级特性：选择、展开、拖拽与上下文菜单](#page-3)
- [Hooks、类型系统、样式扩展与已知问题](#page-4)

<a id='page-1'></a>

## 项目概览与快速上手

### 相关页面

相关主题：[DataTable 核心组件与列管理](#page-2), [Hooks、类型系统、样式扩展与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/icflorescu/mantine-datatable/blob/main/README.md)
- [app/getting-started/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/getting-started/page.tsx)
- [app/config.ts](https://github.com/icflorescu/mantine-datatable/blob/main/app/config.ts)
- [app/contribute-and-support/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/contribute-and-support/page.tsx)
- [app/examples/pagination/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pagination/page.tsx)
- [app/examples/column-properties-and-styling/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-properties-and-styling/page.tsx)
- [app/examples/column-grouping/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-grouping/page.tsx)
- [app/examples/expanding-rows/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/expanding-rows/page.tsx)
- [app/examples/overriding-the-default-styles/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/overriding-the-default-styles/page.tsx)
- [app/examples/rtl-support/RTLSupportExample.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/rtl-support/RTLSupportExample.tsx)
</details>

# 项目概览与快速上手

## 一、项目定位与核心目标

`mantine-datatable` 是一个基于 [Mantine](https://mantine.dev/) 组件库构建的 React 数据表格组件，专注于为开发者提供开箱即用、功能丰富且高度可定制的 Datagrid/DataTable 体验。项目源码与文档站点共存于同一 GitHub 仓库，根目录下的 [`README.md`](https://github.com/icflorescu/mantine-datatable/blob/main/README.md) 明确说明其设计目标是帮助开发者"构建数据丰富的 React 应用程序"。

根据 [`app/config.ts`](https://github.com/icflorescu/mantine-datatable/blob/main/app/config.ts) 中定义的产品元数据，组件涵盖的主要功能域包括：列属性与样式、分页、行选择、排序、上下文菜单、嵌套表、行展开、固定列、列分组、RTL 支持、CSS 主题自定义等，几乎覆盖了企业级数据表格的全部常见需求。

```mermaid
graph LR
  A[DataTable 组件] --> B[列定义 columns]
  A --> C[数据源 records]
  A --> D[分页与排序]
  A --> E[选择与上下文菜单]
  A --> F[行展开 / 嵌套表]
  A --> G[列分组 / 固定列]
  A --> H[主题与样式覆盖]
```

资料来源：[README.md:1-50]()，[app/config.ts:1-80]()。

## 二、依赖关系与安装步骤

`mantine-datatable` 强依赖 `@mantine/core`、`@mantine/hooks` 以及 `clsx` 三个包。文档 [`app/getting-started/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/getting-started/page.tsx) 明确指出安装方式应使用以下任意一种主流包管理器：

```bash
yarn add mantine-datatable clsx
npm i mantine-datatable clsx
pnpm i mantine-datatable clsx
```

需要特别注意的是，**样式文件的加载顺序至关重要**。[`app/getting-started/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/getting-started/page.tsx) 以"非常重要"的提示强调：必须先应用 `@mantine/core` 的 CSS，再应用 `mantine-datatable` 的样式，否则主题色与背景色会出现覆盖异常。这一点也呼应了社区中关于"striped 和 highlightOnHover 样式被覆盖"的反馈（见 Issue #707）。

关于 React 版本，社区曾反馈希望保持与 Mantine 同步（见 Issue #737），目前主分支要求 `react >= 19`。如果项目仍停留在 React 18，需锁定历史版本或等待后续兼容更新。

资料来源：[app/getting-started/page.tsx:1-60]()。

## 三、最小可运行示例

`app/getting-started` 页面配套提供了 `GettingStartedExample.tsx`，演示了最简形式的使用方式。典型代码结构如下：

```tsx
import { DataTable } from 'mantine-datatable';

const records = [
  { id: 1, name: 'Ada Lovelace', role: '工程师' },
  { id: 2, name: 'Linus Torvalds', role: '维护者' },
];

export function Demo() {
  return (
    <DataTable
      withTableBorder
      striped
      highlightOnHover
      records={records}
      columns={[
        { accessor: 'id', title: 'ID' },
        { accessor: 'name', title: '姓名' },
        { accessor: 'role', title: '角色' },
      ]}
    />
  );
}
```

上例中 `withTableBorder`、`striped`、`highlightOnHover` 是最常用的视觉属性开关。 [`app/examples/column-properties-and-styling/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-properties-and-styling/page.tsx) 进一步展示了列级别的细粒度属性，例如 `width`、`ellipsis`、`noWrap`、`textAlign`、`hidden` 等，并明确指出 `ellipsis` 与 `noWrap` **不可同时为 true**，否则会出现不可预期的渲染。

资料来源：[app/getting-started/page.tsx:1-80]()，[app/examples/column-properties-and-styling/page.tsx:1-60]()。

## 四、常用功能与配置速查

| 功能域 | 主要 Prop / 配置 | 文档示例 |
| --- | --- | --- |
| 分页 | `page`, `recordsPerPage`, `recordsPerPageOptions`, `onRecordsPerPageChange` | [`app/examples/pagination/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pagination/page.tsx) |
| 行展开 | `rowExpansion={{ content, trigger }}`，支持 `recordIds`/`onRecordIdsChange` 受控模式 | [`app/examples/expanding-rows/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/expanding-rows/page.tsx) |
| 列分组 | 使用 `groups` 替代 `columns`，每个组包含 `id` 和 `columns` | [`app/examples/column-grouping/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-grouping/page.tsx) |
| 固定列 | `pinFirstColumn`、`pinLastColumn` 或列级 `pinned: 'left' \| 'right'` | [`app/examples/pinning-arbitrary-columns/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pinning-arbitrary-columns/page.tsx) |
| 样式覆盖 | `c`, `backgroundColor`, `borderColor` 主题色键；`classNames`、`styles` 对象 | [`app/examples/overriding-the-default-styles/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/overriding-the-default-styles/page.tsx) |
| RTL 支持 | 包裹 `<DirectionProvider>` 并在 `<Box dir="rtl">` 中渲染 | [`app/examples/rtl-support/RTLSupportExample.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/rtl-support/RTLSupportExample.tsx) |

### 4.1 分页与页大小选择器

分页模块通过 `recordsPerPageOptions: number[]` 数组启用页大小下拉选择器；`onRecordsPerPageChange` 回调接收新页大小，可与 `useState` 协同完成双向绑定。 [`app/examples/pagination/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pagination/page.tsx) 同时支持自定义 `paginationBreakpoint`（默认 `sm`）和 `paginationActiveTextColor` 等主题键。

### 4.2 行展开的受控与延迟加载

[`app/examples/expanding-rows/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/expanding-rows/page.tsx) 指出 `content` 函数是**延迟执行**的，仅在行被展开时调用。这种设计允许把远端数据请求放在 `content` 内部，从而实现"按需加载"。在受控模式下，开发者可通过 `recordIds` 与 `onRecordIdsChange` 完全接管展开状态。

资料来源：[app/examples/pagination/page.tsx:1-80]()，[app/examples/expanding-rows/page.tsx:1-80]()。

## 五、社区反馈与已知陷阱

1. **列宽调整行为**：Issue #778 反馈拖动列宽时会同时影响相邻列，这是为了维持表格总宽度稳定的设计，但多列场景下易造成挤压。可通过显式 `width` 或容器外层尺寸约束来缓解。
2. **底部 + 选择复选框的滚动条异常**：Issue #743 指出当 `footer` 与 `isRecordSelected` 同时启用时，垂直滚动条会出现"双重"或异常现象，建议反馈前先在最小复现中确认。
3. **Sticky 底部遮挡滚动条**：Issue #808 报告在固定高度表格中，水平滚动条会被 sticky 底栏遮住，解决方案包括增加 `min-height` 或将 footer 改为非 sticky 渲染。
4. **`useDataTableColumns` 引用不稳定**：Issue #727 与 #759 指出该 Hook 在每次渲染时返回新对象，直接作为 `useEffect` 依赖会触发 `Maximum update depth exceeded`，官方建议使用列的 `id` 字段或 `useMemo` 做稳定化。
5. **静态类型检查慢**：Issue #651 报告在大型项目里包含 DataTable 的文件 TypeScript 检查可长达 10 秒，建议拆分列定义为独立常量文件以减小推断压力。

资料来源：[README.md:1-30]()，[app/contribute-and-support/page.tsx:1-80]()。

## 六、贡献与支持渠道

[`app/contribute-and-support/page.tsx`](https://github.com/icflorescu/mantine-datatable/blob/main/app/contribute-and-support/page.tsx) 详细说明了参与路径：

- **功能建议**：在 Discussions 区发起讨论，避免直接提 Issue 占用维护者时间。
- **代码贡献**：提交 PR 时**必须**以 `next` 为目标分支，指向 `main` 会触发部署工作流并被拒收。
- **本地开发**：仓库使用 `pnpm-lock.yaml`，需要通过 `pnpm` 管理依赖；常用脚本包括 `pnpm dev`、`pnpm lint`、`pnpm build` 和 `pnpm format`（基于 Biome）。
- **其他支持方式**：Star 仓库、社交媒体扩散、GitHub Sponsors 赞助，或通过 [hire-the-author](https://github.com/icflorescu/mantine-datatable/blob/main/app/hire-the-author/page.tsx) 雇佣作者进行商业合作。

资料来源：[app/contribute-and-support/page.tsx:1-100]()，[app/hire-the-author/page.tsx:1-40]()。

---

## See Also

- [分页与页大小](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pagination/page.tsx)
- [列属性与样式](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-properties-and-styling/page.tsx)
- [行展开（受控与延迟加载）](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/expanding-rows/page.tsx)
- [覆盖默认样式](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/overriding-the-default-styles/page.tsx)
- [RTL 双向布局](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/rtl-support/RTLSupportExample.tsx)

---

<a id='page-2'></a>

## DataTable 核心组件与列管理

### 相关页面

相关主题：[项目概览与快速上手](#page-1), [行级特性：选择、展开、拖拽与上下文菜单](#page-3), [Hooks、类型系统、样式扩展与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [app/examples/column-properties-and-styling/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-properties-and-styling/page.tsx)
- [app/examples/column-grouping/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-grouping/page.tsx)
- [app/examples/pinning-arbitrary-columns/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pinning-arbitrary-columns/page.tsx)
- [app/examples/expanding-rows/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/expanding-rows/page.tsx)
- [app/examples/asynchronous-data-loading/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/asynchronous-data-loading/page.tsx)
- [app/examples/complex-usage-scenario/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/complex-usage-scenario/page.tsx)
- [app/examples/pagination/PaginationExampleWithControlProps.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pagination/PaginationExampleWithControlProps.tsx)
- [app/getting-started/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/getting-started/page.tsx)
- [README.md](https://github.com/icflorescu/mantine-datatable/blob/main/README.md)
</details>

# DataTable 核心组件与列管理

## 概述与核心概念

`mantine-datatable` 是一个为 [Mantine](https://mantine.dev/) 设计的轻量级、零外部业务依赖的 React 数据表组件，旨在为数据密集型应用提供 datagrid 风格的功能（如排序、筛选、分页、行选择、列钉列、可调整列宽等）。其核心入口是 `<DataTable />`，通过 `columns`（或 `groups`）属性驱动表头与单元格的渲染，并通过 `records` 驱动行数据。

资料来源：[README.md]()

组件依赖 `@mantine/core`、`@mantine/hooks` 与 `clsx`，且样式必须 **在 `@mantine/core` 样式之后** 应用，否则会出现样式覆盖问题（如社区反馈的 `striped` 与 `highlightOnHover` 被覆盖的 Bug）。资料来源：[app/getting-started/page.tsx]()

---

## 列定义系统（columns & groups）

### 基础列属性

每个列对象接受一组通用属性，用于控制单元格渲染与对齐：

| 属性 | 类型 | 用途 |
| --- | --- | --- |
| `width` | `number \| string` | 列宽；可使用 `'100%'` 让该列占据剩余空间 |
| `ellipsis` | `boolean` | 文本截断省略（不可与 `noWrap` 同时启用） |
| `noWrap` | `boolean` | `white-space: nowrap` |
| `textAlign` | `'left' \| 'center' \| 'right'` | 默认 `'left'` |
| `hidden` | `boolean` | 隐藏列 |
| `visible` | （推断） | 条件性显示列 |

资料来源：[app/examples/column-properties-and-styling/page.tsx]()

### 列分组（groups）

当一组数据列在语义上高度相关时，可以使用 `groups` 替代 `columns`，从而渲染两层表头。`groups` 的最小结构为：

```ts
{
  id: string,            // React key，唯一即可
  columns: DataTableColumn[]  // 子列定义
}
```

未提供 `title` 时，会以 `id` 的人性化形式作为表头标签。资料来源：[app/examples/column-grouping/page.tsx]()

> 社区长期存在「支持列分组」的功能请求（[issue #207](https://github.com/icflorescu/mantine-datatable/issues/207)），目前 `groups` 即是对该诉求的实现路径之一。

---

## useDataTableColumns 与性能陷阱

`useDataTableColumns` 是库提供的列管理钩子。社区中有多个高频反馈指出：**该 hook 在每次渲染时返回新的引用**，若将其返回值直接放入 `useEffect` / `useMemo` 的依赖中，会引发「不必要的更新」甚至「Maximum update depth exceeded」无限循环。资料来源：社区 Issue [#727](https://github.com/icflorescu/mantine-datatable/issues/727)、[#605](https://github.com/icflorescu/mantine-datatable/issues/605)

对应的另一类 Bug 是「`columns` 参数变化时渲染列顺序不稳定」（[issue #759](https://github.com/icflorescu/mantine-datatable/issues/759)）。当 `columns` 的基数组变化时，应确保每个列对象具备稳定的 `accessor`/`id`，或在外层用 `useMemo` 包裹列定义以保持引用稳定。

另外，社区反馈 VS Code 中静态类型推断非常慢（[issue #651](https://github.com/icflorescu/mantine-datatable/issues/651)），这是泛型列类型递归深度较大导致的工程折衷，建议拆分文件、避免在巨型 `columns` 数组中嵌套复杂 `render` 函数。

---

## 高级列功能

### 任意列钉列（pinned columns）

除 `pinFirstColumn` / `pinLastColumn` 这两个 DataTable 顶层 prop 外，还可在单列上设置 `pinned: 'left' | 'right'`，实现任意列的左右固定，并可与行选择、排序、分页、列宽调整组合使用。资料来源：[app/examples/pinning-arbitrary-columns/page.tsx]()

### 列宽调整（resizable）

列级 `resizable: true` 启用拖拽改宽。但社区报告了如下两类已知问题：

- 调整一列宽度时，**兄弟列会被同时调整**以维持总宽（[issue #778](https://github.com/icflorescu/mantine-datatable/issues/778)），列数较多时容易把列挤到不可见宽度。
- 初始计算时，可调整列呈「等宽分布」而非按内容自适应（[issue #736](https://github.com/icflorescu/mantine-datatable/issues/736)），需结合 `width` 显式指定初始宽度。

### 行展开与异步加载

行展开通过 `rowExpansion` 启用，`content` 回调是 **懒执行的**——仅在行被展开时调用，因此天然适合用作「行内编辑器」或「懒加载子数据」。受控模式通过 `recordIds` + `onRecordIdsChange` 维护展开状态。资料来源：[app/examples/expanding-rows/page.tsx]()

### 异步加载

`fetching: true` 会在表格上覆盖一层 Mantine `Loader`，可通过 `loaderSize`、`loaderType`、`loaderColor`、`loaderBackgroundBlur` 调整外观；若表格未设置垂直滚动且无初始数据，务必设置 `minHeight` 避免加载完成后内容跳动。资料来源：[app/examples/asynchronous-data-loading/page.tsx]()

### 复杂场景与分页控制

官方示例展示了将自定义列、异步数据加载（TanStack Query）、排序、分页、行选择、行展开、Action 单元格、ContextMenu 组合在一起的「复杂用法」。资料来源：[app/examples/complex-usage-scenario/page.tsx]()

分页可通过 `getPaginationControlProps` 注入 `title`、`aria-label` 等 a11y 属性，自定义 `previous` / `next` 按钮语义。资料来源：[app/examples/pagination/PaginationExampleWithControlProps.tsx]()

---

## 常见故障与维护说明

| 现象 | 触发条件 | 参考 |
| --- | --- | --- |
| `striped` / `highlightOnHover` 失效 | 样式导入顺序错误 | [#707](https://github.com/icflorescu/mantine-datatable/issues/707) |
| 列宽调整时兄弟列被改宽 | 启用 `resizable` | [#778](https://github.com/icflorescu/mantine-datatable/issues/778) |
| `useDataTableColumns` 引用变化 | 直接做 effect 依赖 | [#727](https://github.com/icflorescu/mantine-datatable/issues/727) |
| React 18 项目无法安装 | peer dep 锁定了 React ≥19 | [#737](https://github.com/icflorescu/mantine-datatable/issues/737) |
| Mantine 9 下可折叠行失效 | `Collapse` API 从 `in` 改为 `expanded` | [#798](https://github.com/icflorescu/mantine-datatable/issues/798) |

> 安全提示：仓库曾发生通过 GitHub Actions 注入恶意提交的安全事件（[discussion #813](https://github.com/icflorescu/mantine-datatable/discussions/813)），请始终从官方 npm 源安装，并锁定版本。

---

## See Also

- [DataTable 排序、筛选与分页]()
- [DataTable 行选择、Action 与 ContextMenu]()
- [DataTable 样式与主题定制]()
- [与 Mantine ContextMenu 集成]()

---

<a id='page-3'></a>

## 行级特性：选择、展开、拖拽与上下文菜单

### 相关页面

相关主题：[DataTable 核心组件与列管理](#page-2), [Hooks、类型系统、样式扩展与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [app/examples/expanding-rows/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/expanding-rows/page.tsx)
- [app/examples/using-with-mantine-contextmenu/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/using-with-mantine-contextmenu/page.tsx)
- [app/examples/complex-usage-scenario/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/complex-usage-scenario/page.tsx)
- [app/examples/column-properties-and-styling/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-properties-and-styling/page.tsx)
- [app/examples/pinning-arbitrary-columns/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pinning-arbitrary-columns/page.tsx)
- [app/examples/pagination/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pagination/page.tsx)
- [app/examples/rtl-support/RTLSupportExample.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/rtl-support/RTLSupportExample.tsx)
- [app/examples/default-column-properties/DefaultColumnPropertiesExample.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/default-column-properties/DefaultColumnPropertiesExample.tsx)
- [app/getting-started/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/getting-started/page.tsx)
- [README.md](https://github.com/icflorescu/mantine-datatable/blob/main/README.md)
- [app/contribute-and-support/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/contribute-and-support/page.tsx)
</details>

# 行级特性：选择、展开、拖拽与上下文菜单

## 概述

`mantine-datatable` 是一套基于 [Mantine](https://mantine.dev/) 的 React 数据表格组件。本页聚焦于**行级交互特性**：记录（行）选择、行展开、右键 / 左键上下文菜单，以及与列固定、分页、RTL 排版等周边特性的协同使用方式。这些特性均围绕 `DataTable` 根组件的 props 与列定义（`columns`）展开，几乎所有示例都可在官方文档站点的 `app/examples/` 目录下找到对应源码 ([README.md:1-20]())。

> ⚠️ **安全提示**：社区曾报告通过 `github-actions` 注入恶意提交的安全事件，参见 [issues/814](https://github.com/icflorescu/mantine-datatable/issues/814) 与 [discussions/813](https://github.com/icflorescu/mantine-datatable/discussions/813)，在升级前请核对 commit 历史。

## 记录选择 (Records Selection)

`DataTable` 支持单选与多选模式，配置主要通过 `selectedRecords`、`onSelectedRecordsChange`、`isRecordSelectable` 等 props 驱动；通常配合表头的全选复选框与每行的复选框列一起使用 ([app/examples/complex-usage-scenario/page.tsx:1-30]())。典型组合包括：

- 与分页 (`pagination`)、排序 (`sortStatus`) 一起使用：选择状态需由父组件托管，避免分页 / 排序变化后丢失 ([app/examples/pagination/page.tsx:1-30]())。
- 与列固定 (`pinFirstColumn` / `pinLastColumn` / `pinned`) 同时启用：选择列可以固定到最左侧或最右侧 ([app/examples/pinning-arbitrary-columns/page.tsx:1-20]())。
- 在 RTL 方向下：选择状态与方向无关，但需在外层包裹 `DirectionProvider` 并设置 `dir` ([app/examples/rtl-support/RTLSupportExample.tsx:1-30]())。

常见社区问题：当 `footer` 与选择同时启用时，固定高度容器内会出现多余的纵向滚动条，参见 [issues/743](https://github.com/icflorescu/mantine-datatable/issues/743)。

## 行展开 (Expanding Rows)

行展开由 `rowExpansion` 属性控制，可声明式传入 `content` 渲染函数，该函数**延迟执行**——只有当用户真正展开一行时才会创建对应的 DOM，从而避免不必要的渲染开销 ([app/examples/expanding-rows/page.tsx:1-30]())。

### 关键能力

- **受控模式**：通过 `recordIds` + `onRecordIdsChange` 维护展开状态，便于与外部状态管理（Redux、Zustand 等）集成 ([app/examples/expanding-rows/page.tsx:1-30]())。
- **懒加载数据**：因为 `content` 是惰性求值的，可以借此在行展开时按需请求后端数据 ([app/examples/expanding-rows/page.tsx:1-30]())。
- **内联编辑器**：可在展开区域中嵌入表单，常见的做法是同时使用 `onRowClick` 与 `content` 回调 ([app/examples/expanding-rows/page.tsx:1-30]())。

### 兼容性问题

Mantine v9 将 `Collapse` 组件的 `in` prop 改为 `expanded`，旧版 `mantine-datatable` 中的可折叠行实现会因此失效，参见 [issues/798](https://github.com/icflorescu/mantine-datatable/issues/798)。升级 Mantine 时请同时关注 `mantine-datatable` 的兼容版本与 changelog。

## 上下文菜单 (Context Menu)

通过与 [`mantine-contextmenu`](https://github.com/icflorescu/mantine-contextmenu) 配合，可在行 / 单元格上挂载右键菜单 ([app/examples/using-with-mantine-contextmenu/page.tsx:1-20]())。

### 触发方式

- **右键触发**：`onRowContextMenu` 与 `onCellContextMenu` 是最常用的入口 ([app/examples/using-with-mantine-contextmenu/page.tsx:1-20]())。
- **左键触发**：若希望左键即弹出菜单，可改用 `onRowClick` / `onCellClick` 配合 `mantine-contextmenu` ([app/examples/using-with-mantine-contextmenu/page.tsx:1-30]())。
- **模态框内使用**：上下文菜单也可以在 Modal 中渲染的表格上工作 ([app/examples/using-with-mantine-contextmenu/page.tsx:1-30]())。

### 与选择、固定的组合

上下文菜单常与列固定、记录选择同时启用，因此行交互的优先级与事件冒泡需要开发者显式控制；`onRowClick` 与 `onRowContextMenu` 可共存，但要注意点击复选框时不要误触菜单 ([app/examples/complex-usage-scenario/page.tsx:1-30]())。

## 周边特性与故障排查

下表汇总了与行级特性密切相关的社区高频问题与建议做法：

| 问题 | 现象 | 缓解方式 | 参考 |
| --- | --- | --- | --- |
| 静态类型极慢 (#651) | IDE 内 TypeScript 检查耗时高 | 收窄 `DataTableSortStatus<T>` 泛型，避免大对象 union | [#651](https://github.com/icflorescu/mantine-datatable/issues/651) |
| 渲染死循环 (#605, #727) | `Maximum update depth exceeded` | 稳定 `columns` 引用；`useDataTableColumns` 返回值避免作为 `useEffect` 依赖 | [#605](https://github.com/icflorescu/mantine-datatable/issues/605)、[#727](https://github.com/icflorescu/mantine-datatable/issues/727) |
| 固定表头滚动条被遮挡 (#808) | footer / 选择列同时启用时滚动条异常 | 调整 `height` 与 footer 内边距 | [#808](https://github.com/icflorescu/mantine-datatable/issues/808) |
| `useDataTableColumns` 顺序错乱 (#759) | 基础列变更时顺序与配置不符 | 锁定 `key` / 稳定引用后再传入 | [#759](https://github.com/icflorescu/mantine-datatable/issues/759) |
| React 18 不兼容 (#737) | `mantine-datatable` 要求 React ≥ 19 | 锁版本或等待官方放宽 peer 依赖 | [#737](https://github.com/icflorescu/mantine-datatable/issues/737) |

使用前请确认依赖：除 `@mantine/core`、`@mantine/hooks` 外，还需要安装 `clsx` 并按顺序加载样式 ([app/getting-started/page.tsx:1-30]())。如果希望贡献代码，请将 PR 提交到 `next` 分支（推到 `main` 会触发部署工作流，PR 会被拒绝）([app/contribute-and-support/page.tsx:1-30]())。

## 进阶用法

复杂业务场景下，常见组合是：自定义列定义 + 异步数据加载（TanStack Query）+ 排序 + 分页 + 多选 + 行展开 + 行操作 + 右键菜单，官方在 `examples/complex-usage-scenario` 给出端到端示例 ([app/examples/complex-usage-scenario/page.tsx:1-30]())。复用其结构可快速搭建生产级表格页。

## See Also

- [列属性与样式](列属性与样式.md) — 来自 [app/examples/column-properties-and-styling/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-properties-and-styling/page.tsx)
- [列分组 (Column Groups)](列分组.md) — 来自 [app/examples/column-grouping/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-grouping/page.tsx)
- [列固定 (Pinning)](列固定.md) — 来自 [app/examples/pinning-arbitrary-columns/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/pinning-arbitrary-columns/page.tsx)
- [样式覆盖指南](样式覆盖指南.md) — 来自 [app/examples/overriding-the-default-styles/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/overriding-the-default-styles/page.tsx)
- [复杂使用场景](复杂使用场景.md) — 来自 [app/examples/complex-usage-scenario/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/complex-usage-scenario/page.tsx)

---

<a id='page-4'></a>

## Hooks、类型系统、样式扩展与已知问题

### 相关页面

相关主题：[项目概览与快速上手](#page-1), [DataTable 核心组件与列管理](#page-2), [行级特性：选择、展开、拖拽与上下文菜单](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package/hooks/index.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/hooks/index.ts)
- [package/hooks/useStableValue.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/hooks/useStableValue.ts)
- [package/hooks/useIsomorphicLayoutEffect.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/hooks/useIsomorphicLayoutEffect.ts)
- [package/hooks/useMediaQueries.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/hooks/useMediaQueries.ts)
- [package/hooks/useDataTableColumns.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/hooks/useDataTableColumns.ts)
- [package/types/DataTableProps.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/types/DataTableProps.ts)
- [package/types/DataTableColumn.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/types/DataTableColumn.ts)
- [package/types/PaginationRenderContext.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/types/PaginationRenderContext.ts)
- [package/index.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/index.ts)
- [app/examples/overriding-the-default-styles/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/overriding-the-default-styles/page.tsx)
- [app/examples/column-properties-and-styling/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-properties-and-styling/page.tsx)
- [app/getting-started/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/getting-started/page.tsx)
- [app/contribute-and-support/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/contribute-and-support/page.tsx)
</details>

# Hooks、类型系统、样式扩展与已知问题

本页面向开发者深入说明 `mantine-datatable` 中的 Hooks 体系、公开类型系统、样式扩展机制，并汇总社区反馈中的已知问题与规避方法，便于在生产环境中正确集成。

## 一、Hooks 体系

`mantine-datatable` 通过 `package/hooks/index.ts` 导出若干内部 Hook，核心目标是为列定义、媒体查询、副作用执行提供稳定且可重用的封装。

### 1.1 `useDataTableColumns`

该 Hook 接收原始 `columns` 配置与若干状态量（如可见性、排序、固定列等），返回处理后的最终列数组。

```tsx
import { useDataTableColumns, DataTable, type DataTableColumn } from 'mantine-datatable';

const columns: DataTableColumn<Row>[] = [/* ... */];
const { effectiveColumns } = useDataTableColumns({ columns });
```

社区曾反馈两个与该 Hook 相关的问题（[issue #727](https://github.com/icflorescu/mantine-datatable/issues/727)、[issue #759](https://github.com/icflorescu/mantine-datatable/issues/759)）：

- **不必要的重渲染**：返回值在每次渲染时为新引用，作为 `useEffect`/`useMemo` 依赖会触发"Maximum update depth exceeded"。建议将原始 `columns` 作为依赖，或使用 `useStableValue` 包裹（见 `package/hooks/useStableValue.ts`）。
- **列顺序错乱**：当 `columns` 引用频繁变化时，渲染列顺序可能与传入顺序不一致，建议在外层使用 `useMemo` 稳定引用。

### 1.2 媒体查询与副作用

`useMediaQueries`、`useMediaQueryStringOrFunction` 与 `useMediaQueriesStringOrFunction`（见 [package/hooks/useMediaQueries.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/hooks/useMediaQueries.ts)）用于解析 Mantine 断点或像素值，驱动响应式分页与密度切换。`useIsomorphicLayoutEffect`（[package/hooks/useIsomorphicLayoutEffect.ts](https://github.com/icflorescu/mantine-datatable/blob/main/package/hooks/useIsomorphicLayoutEffect.ts)）则在 SSR 场景下退化为 `useEffect`，避免水合不一致。

```mermaid
flowchart LR
  A[用户传入 columns] --> B[useStableValue]
  B --> C[useDataTableColumns]
  C --> D[effectiveColumns]
  D --> E[DataTable 渲染]
  F[媒体查询断点] --> G[useMediaQueries]
  G --> E
```

## 二、类型系统与导出

`package/index.ts` 集中导出组件、Props 与部分类型。然而，开发者常希望复用内部类型（例如 [issue #772](https://github.com/icflorescu/mantine-datatable/issues/772) 中提到的 `PaginationRenderContext`）。

| 类型/组件 | 导出位置 | 用途 |
| --- | --- | --- |
| `DataTableProps` | `package/types/DataTableProps.ts` | 主组件 Props |
| `DataTableColumn<T>` | `package/types/DataTableColumn.ts` | 列定义泛型 |
| `PaginationRenderContext` | `package/types/PaginationRenderContext.ts` | 自定义分页上下文（曾未对外导出） |
| `DataTablePagination` | `package/index.ts` | 内置分页组件（[issue #713](https://github.com/icflorescu/mantine-datatable/issues/713) 建议） |

若需引用未公开类型，可通过 `import type { ... } from 'mantine-datatable/dist/types/...'` 临时绕过，但官方更推荐在 issue 中提出导出申请。TypeScript 静态分析慢的问题（[issue #651](https://github.com/icflorescu/mantine-datatable/issues/651)）通常由深层泛型推断造成，可通过显式标注 `DataTableColumn<Row>` 缓解。

## 三、样式扩展机制

`DataTable` 提供四层样式入口，按粒度从粗到细排列（见 [app/examples/overriding-the-default-styles/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/overriding-the-default-styles/page.tsx)）：

1. **颜色属性**：`c`、`backgroundColor`、`borderColor`、`rowBorderColor` 接受 `MantineColor` 或 `{ light, dark }` 对象。
2. **`classNames`**：按 root / table / header / footer / pagination 五个槽位传入 CSS Module。
3. **`styles`**：与 `classNames` 对应的内联样式对象或函数，函数签名接收当前 `MantineTheme`。
4. **列级样式**：`DataTableColumn` 上的 `cellsClassName`、`titleClassName` 等（[app/examples/column-properties-and-styling/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-properties-and-styling/page.tsx)）。

> ⚠️ **样式顺序**：根据 [app/getting-started/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/getting-started/page.tsx) 的提示，必须先导入 `@mantine/core` 样式，再导入 `mantine-datatable` 样式，否则会出现 `striped` / `highlightOnHover` 被覆盖的问题（[issue #707](https://github.com/icflorescu/mantine-datatable/issues/707)）。

## 四、已知问题与缓解措施

| 问题 | Issue | 根因 | 建议 |
| --- | --- | --- | --- |
| 列宽调整连带兄弟列 | [#778](https://github.com/icflorescu/mantine-datatable/issues/778) | 表格需维持总宽 | 显式设置全部列宽，或关闭 `resizable` |
| 底部条带与选择列叠加滚动条 | [#743](https://github.com/icflorescu/mantine-datatable/issues/743) | 容器高度计算 | 调整 `minHeight` 或禁用 sticky footer |
| sticky footer 遮挡滚动条 | [#808](https://github.com/icflorescu/mantine-datatable/issues/808) | z-index 冲突 | 自定义 `footerStyle` 提升层级 |
| 嵌套表末行边框缺失 | [#790](https://github.com/icflorescu/mantine-datatable/issues/790) | CSS Module 作用域 | 显式为子表传入 `rowClassName` |
| React 18 兼容 | [#737](https://github.com/icflorescu/mantine-datatable/issues/737) | peer dep `react@^19` | 锁定 Mantine 8 + React 19 |
| 安全事件 | [#814](https://github.com/icflorescu/mantine-datatable/issues/814) | 恶意 github-actions 提交 | 关注官方公告并升级至修复版本 |

更多历史问题（如 Mantine V7 支持 [#420](https://github.com/icflorescu/mantine-datatable/issues/420)、无限循环 [#605](https://github.com/icflorescu/mantine-datatable/issues/605)、列分组 [#207](https://github.com/icflorescu/mantine-datatable/issues/207)）可在仓库 `issues` 中检索。所有贡献请遵循 [app/contribute-and-support/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/contribute-and-support/page.tsx) 的规范——PR 须合并到 `next` 分支。

## See Also

- 入门与样式顺序：[app/getting-started/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/getting-started/page.tsx)
- 列属性与样式：[app/examples/column-properties-and-styling/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/column-properties-and-styling/page.tsx)
- 覆盖默认样式：[app/examples/overriding-the-default-styles/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/examples/overriding-the-default-styles/page.tsx)
- 贡献指南：[app/contribute-and-support/page.tsx](https://github.com/icflorescu/mantine-datatable/blob/main/app/contribute-and-support/page.tsx)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：icflorescu/mantine-datatable

摘要：发现 17 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Resizing behaviour。

## 1. 安装坑 · 来源证据：Resizing behaviour

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Resizing behaviour
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4f9958ef0c184e8fa05c6be1749c9065 | https://github.com/icflorescu/mantine-datatable/issues/778 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 运行坑 · 来源证据：Changing base table columns causes rendering loop

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Changing base table columns causes rendering loop
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d09c6777decb43189bf4522e2286412b | https://github.com/icflorescu/mantine-datatable/issues/759 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：Keep the same React peer dependencies as Mantine

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Keep the same React peer dependencies as Mantine
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_13072e282f9c4ff2b24c87d872528805 | https://github.com/icflorescu/mantine-datatable/issues/737 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安装坑 · 来源证据：Static typing extremely slow

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Static typing extremely slow
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_14c55ce66a8b4a608e4b8561bcca8eb9 | https://github.com/icflorescu/mantine-datatable/issues/651 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 5. 配置坑 · 来源证据：Resizable columns render with equal width instead of auto-fitting content

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Resizable columns render with equal width instead of auto-fitting content
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_21875b7fb04e4d41b74775cb6234d4f2 | https://github.com/icflorescu/mantine-datatable/issues/736 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 配置坑 · 来源证据：useDataTableColumns causing unnecessary updates (Maximum update depth exceeded)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：useDataTableColumns causing unnecessary updates (Maximum update depth exceeded)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_618d21f8ce684218a4ed3ece874679b1 | https://github.com/icflorescu/mantine-datatable/issues/727 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 7. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | hn_item:48414978 | https://news.ycombinator.com/item?id=48414978 | README/documentation is current enough for a first validation pass.

## 8. 运行坑 · 来源证据：Nested tables, missing row border on last element

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Nested tables, missing row border on last element
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a06a6d8844d9449eb39bdeb0fcfb5513 | https://github.com/icflorescu/mantine-datatable/issues/790 | 来源类型 github_issue 暴露的待验证使用条件。

## 9. 维护坑 · 来源证据：Abnormal vertical scroll bar When using both footer and selection at the same time

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Abnormal vertical scroll bar When using both footer and selection at the same time
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_464c51c7540f40e9b8ee4d0c585412a9 | https://github.com/icflorescu/mantine-datatable/issues/743 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 10. 维护坑 · 来源证据：ScrollBars are hidden behind sticky footer

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：ScrollBars are hidden behind sticky footer
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_00a1e7ec929f4d0fb1c6a05f9b801f2a | https://github.com/icflorescu/mantine-datatable/issues/808 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 11. 维护坑 · 来源证据：striped and highlightOnHover styling overrided

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：striped and highlightOnHover styling overrided
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e5d8715976b8461b9e665c4d07f9bf40 | https://github.com/icflorescu/mantine-datatable/issues/707 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 12. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | hn_item:48414978 | https://news.ycombinator.com/item?id=48414978 | last_activity_observed missing

## 13. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | hn_item:48414978 | https://news.ycombinator.com/item?id=48414978 | no_demo; severity=medium

## 14. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | hn_item:48414978 | https://news.ycombinator.com/item?id=48414978 | no_demo; severity=medium

## 15. 安全/权限坑 · 来源证据：⚠️ Security incident: malicious commits injected via github-actions -- maintainer locked out by GitHub for 20+ hours

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：⚠️ Security incident: malicious commits injected via github-actions -- maintainer locked out by GitHub for 20+ hours
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_de71bdc9aa1f485bad90a3601c6ab629 | https://github.com/icflorescu/mantine-datatable/issues/814 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 16. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | hn_item:48414978 | https://news.ycombinator.com/item?id=48414978 | issue_or_pr_quality=unknown

## 17. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | hn_item:48414978 | https://news.ycombinator.com/item?id=48414978 | release_recency=unknown

<!-- canonical_name: icflorescu/mantine-datatable; human_manual_source: deepwiki_human_wiki -->