# @affino/datagrid-vue 中文文档

规范地址：https://npmcn.com/package/%40affino/datagrid-vue/

版本：0\.17\.0
npm 元数据更新时间：2026-10-26T11:34:39.122Z
中文译文更新时间：2026-11-07T04:18:24.739Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40affino/datagrid-vue
原文对照：https://npmcn.com/package/%40affino/datagrid-vue/?lang=original
项目主页：https://github.com/affinio/datagrid/tree/main/packages/datagrid-vue#readme
源码仓库：https://github.com/affinio/datagrid

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.5 MB，618 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：vue ^3\.3\.0，pinia ^2\.1\.0 \|\| ^3\.0\.0，@affino/datagrid-gantt ^0\.2\.0
- 首次发布：2026-02-12T20:15:57.269Z
- 最新版本发布：2026-10-26T11:34:38.896Z
- 近 30 天下载量：2051（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：70（近 12 个月 70 个）

## 中文简介

Vue DataGrid 组件和 Affino DataGrid 无头适配器

## 安装

```sh
npm install @affino/datagrid-vue
```

也可以使用：`pnpm add @affino/datagrid-vue`、`yarn add @affino/datagrid-vue`、`bun add @affino/datagrid-vue`

## README

# @affino/datagrid-vue (英语)

该软件包结合了现成的Vue DataGrid和下等Vue 适配器. 从包根导入组件并使用 `/headless` 何时 构建自定义渲染器 :

```ts
import { DataGrid } from "@affino/datagrid-vue"
import { useDataGridRuntime } from "@affino/datagrid-vue/headless"
```

应用程序的应用 `src/app-layer`;适配器源和 `/headless` 建筑物仍然分开。 见 [Vue 软件包迁移指南](https://npmcn.com/package/docs/vue-package-migration.md) 旧的移民地图.

`@affino/datagrid-vue` 提供声明数据Grid和Vue适配器 层上 `@affino/datagrid-core` 财务报告和审定财务报表 `@affino/datagrid-orchestration`。 。 。 .

## 文档

-   [Vue 适配器指南](https://npmcn.com/package/docs/vue-adapter.md)
-   [DataGrid 组件指南](https://npmcn.com/package/%40affino/datagrid-vue/README.component.md)
-   [核心 API 指南](https://npmcn.com/package/packages/datagrid-core/docs/README.md)

## Canonical 地物目录

平台能力的单一真相来源:

-   [数据Grid 特性目录](https://github.com/affinio/datagrid/blob/main/docs/datagrid-feature-catalog.md)

## 公式引擎边界

如果 Vue 应用程序需要直接的公式引擎 API,请从 :

-   [@affino/datagrid-formula-engine (英语)](https://github.com/affinio/datagrid/tree/main/packages/datagrid-formula-engine#readme)

不导入公式编译/图表助手 `@affino/datagrid-core` 直接在新的整合.

## 关键边界

如果Vue app公司需要直接的枢轴合同,请从以下来源导入:

-   [@affino/ datagrid- vivot](https://github.com/affinio/datagrid/tree/main/packages/datagrid-pivot#readme)

不导入关键合同 `@affino/datagrid-core` 直接在新的整合.

## 运行时模式决定( 主线程对工作对服务器侧)

| 假设 | 建议模式 | 为什么 |
| --- | --- | --- |
| 高达~10k行, 简单的表格, 低补丁率 | `main-thread` | 最低的设置复杂度,良好的基线耐久性 |
| 20k+行,交互式编辑,用户动作下的重排序/组/过滤器 | `worker-owned` | 保持UI线程响应, 显著降低同步调度成本 |
| 甚大数据集、远程寻呼/汇总、后端自主查询 | `server-side row model` | 将数据形状和重计算移动到后端, 将客户端内存压力最小化 |

实际默认 :

-   开始 `main-thread`。 。 。 .
-   切换到 `worker-owned` 当UI在补丁压力下的反应成为瓶颈时.
-   移动到 `server-side` 当数据集大小和查询形状主要是后端关切时.

## 特征概述(适应器表面)

出框( 通过此包) :

-   客户行模式:排序,过滤,分组,页码,取景所范围.
-   支点:行/栏/值轴,生成支点列,小计和总计,布局出/入,钻.
-   选择/距离引擎:锁定/焦点/距离,填充手柄,拖放,双击填充,拖放,剪贴板工作流程.
-   编辑流程:基于补丁的更新,类似Excel的冻结/再应用控制(`applyEdits`, (中文(简体) ), `reapplyView`, (中文(简体) ), `autoReapply`) (中文(简体) ).
-   上下文菜单和键盘管弦原生.
-   用于确定性整合和测试的运行时间快照/修订版.
-   工人自有行模型支持离主线计算路径.
-   服务器/数据源行模式合同后端拉出/推出流.

单元格范围坐标与活行投影相接并可见 列顺序。 Vue 应用程序层的邮票, 用于选择这些修改 服务,当行变化时清除 stale 位置范围。 记录选择 使用行标识; `mode: "all"` 范围为当前预测,改为: 在预测修改后暂停.

## 性能快照(如何阅读)

代表的压力基准趋势 `artifacts/performance/worker-pressure-matrix-scaled`数字 :

-   时 `20k` 行:工人路径将端到端的压力时间大致减少 `~5.4x` vs 主行脚.
-   时 `100k` 排行:工人的道路仍然大致领先 `~1.6x`。 。 。 .
-   时 `200k` 行(有更重的补丁尺寸):工人的行道仍然大致领先 `~1.34x`。 。 。 .

综合人员口译:

-   工作模式在同步的UI线程补丁发送变得昂贵时给出了最强值.
-   主行可以足够更小的表格和更简单的交互剖面.
-   服务器-侧模式是数据量/克列成本主导客户端约束的下一步.

## 稳定 API (`@affino/datagrid-vue`(中文(简体) )

-   `createDataGridVueRuntime`
-   `useDataGridRuntime`
-   `useDataGridSettingsStore`
-   `createDataGridSettingsAdapter`
-   `buildDataGridOverlayTransform`
-   `buildDataGridOverlayTransformFromSnapshot`
-   `mapDataGridA11yGridAttributes`
-   `mapDataGridA11yCellAttributes`
-   `useDataGridContextMenu`
-   `DATA_GRID_SELECTORS`
-   `DATA_GRID_DATA_ATTRS`
-   `dataGridCellSelector`
-   `dataGridHeaderCellSelector`
-   `dataGridResizeHandleSelector`

稳定选择者合同(对等测试/一体化安全查询):

```ts
import {
  DATA_GRID_SELECTORS,
  dataGridCellSelector,
} from "@affino/datagrid-vue"

const viewportSelector = DATA_GRID_SELECTORS.viewport
const ownerCellSelector = dataGridCellSelector("owner")
```

## DataGrid 组件

套件根导出组件表面 :

-   `DataGrid`

`DataGrid` 也是支持的外置填充器集成:

-   从选择角拖入
-   双击填充到当前投影中最后一行
-   填充后 `Series` 编号 : `Copy` 重新应用锁定在可见视图区域的菜单

此路径不需要遗留的糖包装.

## 自定义渲染器电子表格填充集成

如果你正在建造自己的制造器而不是使用 `DataGrid`,使用当前导出从 `@affino/datagrid-vue`。 。 。 .

建议的组成:

-   `useDataGridAppSelection` 选择所有权
-   `useDataGridAppClipboard` 用于复制/剪接/粘贴状态和填充源矩阵
-   `useDataGridAppFill` 应用填充范围 `copy` 编号 : `series` 行为
-   `useDataGridAppInteractionController` 用于集成指针/键盘流,包括填入式拖放、双击填入式并重新应用上一个填入行为

```ts
import {
  useDataGridAppClipboard,
  useDataGridAppFill,
  useDataGridAppInteractionController,
  useDataGridAppSelection,
} from "@affino/datagrid-vue"
```

用此路径代替已删除的路径 `useAffinoDataGrid*` 包装.

## 高级 API (E)`@affino/datagrid-vue/advanced`(中文(简体) )

高级入场点. 对于新集成,则倾向于域入分:

-   `@affino/datagrid-vue/advanced/layout`
-   `@affino/datagrid-vue/advanced/pointer`
-   `@affino/datagrid-vue/advanced/selection`
-   `@affino/datagrid-vue/advanced/editing`
-   `@affino/datagrid-vue/advanced/clipboard`
-   `@affino/datagrid-vue/advanced/filtering`
-   `@affino/datagrid-vue/advanced/history`

示例

```ts
import {
  useDataGridManagedWheelScroll,
  useDataGridColumnLayoutOrchestration,
} from "@affino/datagrid-vue/advanced/layout"
```

-   `createDataGridViewportController`
-   `useDataGridCellPointerDownRouter`
-   `useDataGridCellPointerHoverRouter`
-   `useDataGridDragSelectionLifecycle`
-   `useDataGridDragPointerSelection`
-   `useDataGridFillSelectionLifecycle`
-   `useDataGridFillHandleStart`
-   `useDataGridRangeMoveLifecycle`
-   `useDataGridRangeMoveStart`
-   `useDataGridSelectionMoveHandle`
-   `useDataGridTabTargetResolver`
-   `useDataGridCellNavigation`
-   `useDataGridClipboardValuePolicy`
-   `useDataGridCellDatasetResolver`
-   `useDataGridCellRangeHelpers`
-   `useDataGridNavigationPrimitives`
-   `useDataGridMutationSnapshot`
-   `useDataGridCellVisualStatePredicates`
-   `useDataGridRangeMutationEngine`
-   `useDataGridA11yCellIds`
-   `useDataGridColumnUiPolicy`
-   `useDataGridEditableValuePolicy`
-   `useDataGridMoveMutationPolicy`
-   `useDataGridInlineEditorSchema`
-   `useDataGridInlineEditOrchestration`
-   `useDataGridInlineEditorTargetNavigation`
-   `useDataGridInlineEditorKeyRouter`
-   `useDataGridHeaderContextActions`
-   `useDataGridHeaderLayerOrchestration`
-   `useDataGridCopyRangeHelpers`
-   `useDataGridHeaderSortOrchestration`
-   `useDataGridHeaderResizeOrchestration`
-   `useDataGridHeaderInteractionRouter`
-   `useDataGridColumnFilterOrchestration`
-   `useDataGridEnumTrigger`
-   `useDataGridGroupValueLabelResolver`
-   `useDataGridGroupMetaOrchestration`
-   `useDataGridGroupBadge`
-   `useDataGridGroupingSortOrchestration`
-   `useDataGridViewportMeasureScheduler`
-   `useDataGridVisibleRowsSyncScheduler`
-   `useDataGridColumnLayoutOrchestration`
-   `useDataGridSelectionOverlayOrchestration`
-   `useDataGridRowsProjection`
-   `useDataGridRowSelectionOrchestration`
-   `useDataGridRowSelectionInputHandlers`
-   `useDataGridVirtualRangeMetrics`
-   `useDataGridContextMenuAnchor`
-   `useDataGridContextMenuActionRouter`
-   `useDataGridViewportContextMenuRouter`
-   `useDataGridViewportBlurHandler`
-   `useDataGridViewportScrollLifecycle`
-   `useDataGridLinkedPaneScrollSync`
-   `useDataGridResizeClickGuard`
-   `useDataGridInitialViewportRecovery`
-   `useDataGridManagedWheelScroll`
-   `useDataGridManagedTouchScroll`
-   `useDataGridScrollIdleGate`
-   `useDataGridScrollPerfTelemetry`
-   `useDataGridClearSelectionLifecycle`
-   `useDataGridGlobalPointerLifecycle`
-   `useDataGridPointerAutoScroll`
-   `useDataGridPointerPreviewRouter`
-   `useDataGridPointerCellCoordResolver`
-   `useDataGridAxisAutoScrollDelta`
-   `useDataGridCellVisibilityScroller`
-   `useDataGridGlobalMouseDownContextMenuCloser`
-   `useDataGridKeyboardCommandRouter`
-   `useDataGridQuickFilterActions`
-   `useDataGridCellCoordNormalizer`
-   `useDataGridSelectionComparators`
-   `useDataGridRowSelectionModel`
-   `useDataGridPointerModifierPolicy`
-   `useDataGridHistoryActionRunner`
-   `useDataGridInlineEditorFocus`
-   `useDataGridClipboardBridge`
-   `useDataGridClipboardMutations`
-   `useDataGridIntentHistory`

## 快开始

```ts
import { ref } from "vue"
import { useDataGridRuntime } from "@affino/datagrid-vue"

const rows = ref([])
const columns = ref([
  { key: "service", label: "Service", initialState: { width: 220 } },
])

const { api, columnSnapshot } = useDataGridRuntime({
  rows,
  columns,
})
```

`useDataGridRuntime` 还揭露 `patchRows(updates, options?)` 对于不强制排序/过滤器/组在每次单元格变化上重算的部分行更新:

```ts
const runtime = useDataGridRuntime({ rows, columns })
runtime.patchRows(
  [{ rowId: "r-42", data: { tested_at: "2026-02-21T10:15:00Z" } }],
  { recomputeSort: false, recomputeFilter: false, recomputeGroup: false },
)
```

使用 `setRows` 用于完全数据替换 `patchRows` 当您想要避免立即投影跳出时,用于交互式/流式单元格更新. 在不重算模式下( N)`recomputeSort/filter/group = false`),行顺序/过滤器/组的能见度可以按设计暂时保持停滞状态,直到请求重算出出传.

对于应用级编辑流程,偏好高级 `applyEdits()` + 键 `reapplyView()` API : (英语)

```ts
const runtime = useDataGridRuntime({ rows, columns })

// default Excel-style behavior: update values, keep current view stable
runtime.applyEdits([{ rowId: "r-42", data: { tested_at: "2026-02-21T10:15:00Z" } }])

// explicit reapply when the user clicks "Reapply" or leaves edit mode
runtime.reapplyView()

// optional live-reapply mode
runtime.autoReapply.value = true
```

枢轴可直接由运行时间 API 控制(不直接导入核心/节点):

```ts
runtime.setPivotModel({
  rows: ["team"],
  columns: ["year"],
  values: [{ field: "revenue", agg: "sum" }],
  rowSubtotals: true,
  grandTotal: true,
})

const activePivot = runtime.getPivotModel()
runtime.setPivotModel(null)
```

当鼠标活动时,运行时间会自动调节 `snapshot.pivotColumns` 输入列模型 因此适配器无需手动即可制取导线列 `setColumns` 接线 基柱仍然是真相的来源.

### 框架独立读取和单元格值

由 Core API 曝光 `runtime.api` 提供 `read.captureView()` 对请求的行、列、计算和选择快照进行同步、有修订标签的捕获。 在导出或处理数据源后行之前检查当前预测覆盖范围。 使用 `cells.resolveValue({ rowId, columnKey, purpose })` 当工作流程需要源,访问者/计算,或为逻辑单元格格式化显示值时. 过 `snapshot: { row, column }` 在同步操作中解析值时从被捕获视图中取出;然后解析器只使用被捕获的输入。 内置编辑和选择摘要使用计算/存取器目的。 XLSX 导出在将矩阵交给工人之前先解析并解析工作表单元格值,先尊重明确的输出值回调,并拒绝不完整或中枢预测. 内容 `preparing` 矩阵准备后进度召回火;导出不需要行克隆召回. 这些方法是框架独立的;Vue拥有编辑器草稿和DOM焦点.

国家进口用途 `runtime.api.state.validate()` 飞行前诊断和 `runtime.api.state.set()` 用于编写应用/删除的章节报告。 失败包括 失败的部分和回滚状态。 应用程序的手动行调整存储大小 由稳定的行 ID 覆盖; 索引覆盖保留给虚拟化器 测量.

## 受控轮轴(高级)

使用 `useDataGridManagedWheelScroll` 当您想要确定方向盘所有权时( 轴锁、 防止默认政策、 以及一致的页眉/ 身体水平同步) .

```ts
import { useDataGridManagedWheelScroll } from "@affino/datagrid-vue/advanced"

const managedWheelScroll = useDataGridManagedWheelScroll({
  resolveWheelMode: () => "managed", // "managed" | "native"
  resolveWheelAxisLockMode: () => "dominant",
  resolvePreventDefaultWhenHandled: () => true,
  resolveBodyViewport: () => viewportRef.value,
  resolveMainViewport: () => viewportRef.value
    ? {
        scrollLeft: viewportRef.value.scrollLeft,
        scrollWidth: viewportRef.value.scrollWidth,
        clientWidth: viewportRef.value.clientWidth,
      }
    : null,
  setHandledScrollTop: (nextTop) => {
    if (viewportRef.value) {
      viewportRef.value.scrollTop = nextTop
    }
  },
  setHandledScrollLeft: (nextLeft) => {
    if (viewportRef.value) {
      viewportRef.value.scrollLeft = nextLeft
    }
  },
})

function onViewportWheel(event: WheelEvent) {
  managedWheelScroll.onBodyViewportWheel(event)
}
```

```vue
<div ref="viewportRef" @wheel="onViewportWheel" @scroll="onViewportScroll" />
```

-   打电话 `managedWheelScroll.reset()` 在卸载.
-   将 DOM 保存在适配器/demo/UI层中读取/写入;不要将轮子 DOM 处理移入核心.

## 管弦乐-重力取景器集成

使用来自 `@affino/datagrid-vue/advanced` 在保留高真实性互动行为的同时保持组件代码的细长.

```ts
import {
  useDataGridLinkedPaneScrollSync,
  useDataGridResizeClickGuard,
  useDataGridInitialViewportRecovery,
  useDataGridRowSelectionModel,
} from "@affino/datagrid-vue/advanced"

const linkedPaneSync = useDataGridLinkedPaneScrollSync({
  resolveSourceScrollTop: () => viewportRef.value?.scrollTop ?? 0,
  mode: "css-var",
  resolveCssVarHost: () => gridRootRef.value,
})

const resizeGuard = useDataGridResizeClickGuard()

const viewportRecovery = useDataGridInitialViewportRecovery({
  resolveShouldRecover: () => totalRows.value > 1 && renderedRowsCount.value <= 1,
  runRecoveryStep: () => syncViewportMetrics(),
})

const rowSelectionModel = useDataGridRowSelectionModel({
  resolveFilteredRows: () => filteredRows.value,
  resolveRowId: row => String(row.rowId),
  resolveAllRows: () => allRows.value,
})
```

建议的所有权:

-   `@affino/datagrid-core`:确定性数据/运行时间合同.
-   `@affino/datagrid-orchestration`:互动政策和国家协调.
-   `@affino/datagrid-vue`:回转/调制接线和DOM生命周期集成.

## 60秒融合(初级友好型)

```ts
import { ref } from "vue"
import { DataGrid } from "@affino/datagrid-vue"

const rows = ref([
  { rowId: "1", service: "edge-gateway", owner: "NOC" },
  { rowId: "2", service: "billing-api", owner: "Payments" },
])

const columns = [
  { key: "service", label: "Service", initialState: { width: 220 } },
  { key: "owner", label: "Owner", initialState: { width: 180 } },
]

const columnState = ref(null)
const gridState = ref(null)
```

```vue
<DataGrid
  :rows="rows"
  :columns="columns"
  :features="['selection', 'sorting', 'filterDsl', 'filterBuilderUI', 'columnMenu', 'cellEditors']"
  v-model:column-state="columnState"
  v-model:state="gridState"
/>
```

-   使用内置的应用组件并配有声明特性接线.
-   支持国家所有权 `v-model:column-state` 财务报告和审定财务报表 `v-model:state`。 。 。 .
-   当你想要一个犬类高级组件,而不是单独的"简单"和"先进"组件分级时,最合适.

## 残留糖的去除

遗产 `useAffinoDataGrid`, (中文(简体) ), `useAffinoDataGridUi`,以及 `useAffinoDataGridMinimal` 包装被移除.

关于新的整合:

-   使用 `DataGrid` 从 `@affino/datagrid-vue` 用于峡谷组件路径.
-   使用 `useDataGridRuntime` 从 `@affino/datagrid-vue/headless` 当你需要一个无头运行时间.
-   使用 `@affino/datagrid-vue/advanced/*` 和用于自定义交互流量的应用级钩子.

对于端到端的UI行为,使用公共指南:

-   [数据网-vue-稳定输入点.md](https://github.com/affinio/datagrid/blob/main/docs/reference/datagrid-vue-stable-entrypoint.md)
-   [应用层指南](https://github.com/affinio/datagrid/blob/main/docs/app-layer.md)
-   [编辑](https://github.com/affinio/datagrid/blob/main/docs/datagrid-editing.md)
-   [剪贴板和范围工作流程](https://github.com/affinio/datagrid/blob/main/docs/datagrid-clipboard.md)

## 常见问题

### @affino/datagrid-vue 是什么？

Vue DataGrid 组件和 Affino DataGrid 无头适配器

### 如何安装 @affino/datagrid-vue？

在项目目录运行 npm install @affino/datagrid-vue，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.3\.0）、pinia（^2\.1\.0 \|\| ^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @affino/datagrid-vue 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @affino/datagrid-vue 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @affino/datagrid-vue 可以商用吗？

@affino/datagrid-vue 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @affino/datagrid-vue 的下载量有多少？

根据 npm 官方下载统计，@affino/datagrid-vue 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,051 次，日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @affino/datagrid-vue 还在维护吗？

最新版本 0\.17\.0 发布于 2026/10/26（12 天前）；至今共发布 70 个版本，其中过去 12 个月发布了 70 个；首次发布于 2026/02/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。