@affino/datagrid-vue (英语)
该软件包结合了现成的Vue DataGrid和下等Vue
适配器. 从包根导入组件并使用 /headless 何时
构建自定义渲染器 :
import { DataGrid } from "@affino/datagrid-vue"
import { useDataGridRuntime } from "@affino/datagrid-vue/headless"
应用程序的应用 src/app-layer;适配器源和
/headless 建筑物仍然分开。 见 Vue 软件包迁移指南 旧的移民地图.
@affino/datagrid-vue 提供声明数据Grid和Vue适配器
层上 @affino/datagrid-core 财务报告和审定财务报表 @affino/datagrid-orchestration。 。 。 .
文档
Canonical 地物目录
平台能力的单一真相来源:
公式引擎边界
如果 Vue 应用程序需要直接的公式引擎 API,请从 :
不导入公式编译/图表助手 @affino/datagrid-core 直接在新的整合.
关键边界
如果Vue app公司需要直接的枢轴合同,请从以下来源导入:
不导入关键合同 @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.4xvs 主行脚. - 时
100k排行:工人的道路仍然大致领先~1.6x。 。 。 . - 时
200k行(有更重的补丁尺寸):工人的行道仍然大致领先~1.34x。 。 。 .
综合人员口译:
- 工作模式在同步的UI线程补丁发送变得昂贵时给出了最强值.
- 主行可以足够更小的表格和更简单的交互剖面.
- 服务器-侧模式是数据量/克列成本主导客户端约束的下一步.
稳定 API (@affino/datagrid-vue(中文(简体) )
createDataGridVueRuntimeuseDataGridRuntimeuseDataGridSettingsStorecreateDataGridSettingsAdapterbuildDataGridOverlayTransformbuildDataGridOverlayTransformFromSnapshotmapDataGridA11yGridAttributesmapDataGridA11yCellAttributesuseDataGridContextMenuDATA_GRID_SELECTORSDATA_GRID_DATA_ATTRSdataGridCellSelectordataGridHeaderCellSelectordataGridResizeHandleSelector
稳定选择者合同(对等测试/一体化安全查询):
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用于集成指针/键盘流,包括填入式拖放、双击填入式并重新应用上一个填入行为
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
示例
import {
useDataGridManagedWheelScroll,
useDataGridColumnLayoutOrchestration,
} from "@affino/datagrid-vue/advanced/layout"
createDataGridViewportControlleruseDataGridCellPointerDownRouteruseDataGridCellPointerHoverRouteruseDataGridDragSelectionLifecycleuseDataGridDragPointerSelectionuseDataGridFillSelectionLifecycleuseDataGridFillHandleStartuseDataGridRangeMoveLifecycleuseDataGridRangeMoveStartuseDataGridSelectionMoveHandleuseDataGridTabTargetResolveruseDataGridCellNavigationuseDataGridClipboardValuePolicyuseDataGridCellDatasetResolveruseDataGridCellRangeHelpersuseDataGridNavigationPrimitivesuseDataGridMutationSnapshotuseDataGridCellVisualStatePredicatesuseDataGridRangeMutationEngineuseDataGridA11yCellIdsuseDataGridColumnUiPolicyuseDataGridEditableValuePolicyuseDataGridMoveMutationPolicyuseDataGridInlineEditorSchemauseDataGridInlineEditOrchestrationuseDataGridInlineEditorTargetNavigationuseDataGridInlineEditorKeyRouteruseDataGridHeaderContextActionsuseDataGridHeaderLayerOrchestrationuseDataGridCopyRangeHelpersuseDataGridHeaderSortOrchestrationuseDataGridHeaderResizeOrchestrationuseDataGridHeaderInteractionRouteruseDataGridColumnFilterOrchestrationuseDataGridEnumTriggeruseDataGridGroupValueLabelResolveruseDataGridGroupMetaOrchestrationuseDataGridGroupBadgeuseDataGridGroupingSortOrchestrationuseDataGridViewportMeasureScheduleruseDataGridVisibleRowsSyncScheduleruseDataGridColumnLayoutOrchestrationuseDataGridSelectionOverlayOrchestrationuseDataGridRowsProjectionuseDataGridRowSelectionOrchestrationuseDataGridRowSelectionInputHandlersuseDataGridVirtualRangeMetricsuseDataGridContextMenuAnchoruseDataGridContextMenuActionRouteruseDataGridViewportContextMenuRouteruseDataGridViewportBlurHandleruseDataGridViewportScrollLifecycleuseDataGridLinkedPaneScrollSyncuseDataGridResizeClickGuarduseDataGridInitialViewportRecoveryuseDataGridManagedWheelScrolluseDataGridManagedTouchScrolluseDataGridScrollIdleGateuseDataGridScrollPerfTelemetryuseDataGridClearSelectionLifecycleuseDataGridGlobalPointerLifecycleuseDataGridPointerAutoScrolluseDataGridPointerPreviewRouteruseDataGridPointerCellCoordResolveruseDataGridAxisAutoScrollDeltauseDataGridCellVisibilityScrolleruseDataGridGlobalMouseDownContextMenuCloseruseDataGridKeyboardCommandRouteruseDataGridQuickFilterActionsuseDataGridCellCoordNormalizeruseDataGridSelectionComparatorsuseDataGridRowSelectionModeluseDataGridPointerModifierPolicyuseDataGridHistoryActionRunneruseDataGridInlineEditorFocususeDataGridClipboardBridgeuseDataGridClipboardMutationsuseDataGridIntentHistory
快开始
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?) 对于不强制排序/过滤器/组在每次单元格变化上重算的部分行更新:
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 : (英语)
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 控制(不直接导入核心/节点):
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 当您想要确定方向盘所有权时( 轴锁、 防止默认政策、 以及一致的页眉/ 身体水平同步) .
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)
}
<div ref="viewportRef" @wheel="onViewportWheel" @scroll="onViewportScroll" />
- 打电话
managedWheelScroll.reset()在卸载. - 将 DOM 保存在适配器/demo/UI层中读取/写入;不要将轮子 DOM 处理移入核心.
管弦乐-重力取景器集成
使用来自 @affino/datagrid-vue/advanced 在保留高真实性互动行为的同时保持组件代码的细长.
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秒融合(初级友好型)
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)
<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行为,使用公共指南: