Angular中如何自定义AgGrid的键盘导航逻辑

需求说明 #

• 当焦点位于非最后一列的列头时，按下Tab键，焦点移动到下一列的列头；
• 当焦点位于最后一列的列头时，按下Tab键，焦点移动到第一行并整行高亮，避免默认聚焦到该行第一个单元格；
• 当某一行被聚焦时，按下Tab键：
  • 优先移动到该行的下一个可编辑单元格；
  • 若该行无可编辑单元格，则移动到下一行并整行高亮。

实现代码 #

HTML模板修改 #

<ag-grid-angular
  theme="legacy"
  class="ag-theme-quartz"
  style="height: 700px;"
  [rowData]="rowData"
  [columnDefs]="colDefs"
  [gridOptions]="gridOptions"
  (gridReady)="onGridReady($event)"
/>

组件逻辑实现 #

import { Component } from '@angular/core';
import { AgGridAngular } from 'ag-grid-angular';
import type { ColDef, GridApi, GridOptions, ColumnApi, KeyboardEventParams } from 'ag-grid-community';
import 'ag-grid-community/styles/ag-grid.css';
import 'ag-grid-community/styles/ag-theme-quartz.css';

import { AllCommunityModule, ModuleRegistry } from 'ag-grid-community';
ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
  selector: 'app-root',
  imports: [AgGridAngular],
  templateUrl: './app.component.html',
  styleUrl: './app.component.scss'
})
export class AppComponent {
  rowData = [
    { make: "Tesla", model: "Model Y", price: 64950, electric: true },
    { make: "Ford", model: "F-Series", price: 33850, electric: false },
    { make: "Toyota", model: "Corolla", price: 29600, electric: false },
  ];

  colDefs: ColDef[] = [
    { field: "make", headerName: "Company" },
    { field: "model" },
    { field: "price" },
    { field: "electric", editable: true }
  ];

  private gridApi!: GridApi;
  private columnApi!: ColumnApi;
  gridOptions: GridOptions = {
    onKeyDown: this.handleKeyDown.bind(this)
  };

  onGridReady(params: { api: GridApi; columnApi: ColumnApi }) {
    this.gridApi = params.api;
    this.columnApi = params.columnApi;
  }

  handleKeyDown(params: KeyboardEventParams) {
    const event = params.event;
    if (event.key !== 'Tab') return;

    event.preventDefault(); // 禁用默认Tab导航行为

    // 处理列头焦点的情况
    const focusedHeader = this.columnApi.getFocusedHeader();
    if (focusedHeader) {
      const allColumns = this.columnApi.getAllDisplayedColumns();
      const currentColIdx = allColumns.indexOf(focusedHeader);
      const isLastCol = currentColIdx === allColumns.length - 1;

      if (!isLastCol) {
        // 聚焦下一列列头
        this.columnApi.setFocusedColumn(allColumns[currentColIdx + 1]);
      } else {
        // 聚焦第一行并整行高亮，清除单元格焦点
        const firstRow = this.gridApi.getDisplayedRowAtIndex(0);
        this.gridApi.setFocusedCell(-1, '');
        this.gridApi.selectNode(firstRow, true);
        this.gridApi.setFocusedRow(firstRow);
      }
      return;
    }

    // 处理行/单元格焦点的情况
    const focusedCell = params.api.getFocusedCell();
    const focusedRow = focusedCell ? this.gridApi.getRowNode(focusedCell.rowIndex!) : this.gridApi.getFocusedRow();
    if (!focusedRow) return;

    const currentRowIdx = focusedRow.rowIndex!;
    const allColumns = this.columnApi.getAllDisplayedColumns();
    let targetColIdx = -1;

    if (focusedCell) {
      // 从当前单元格列之后查找下一个可编辑列
      const currentColIdx = allColumns.indexOf(this.columnApi.getColumn(focusedCell.columnId)!);
      for (let i = currentColIdx + 1; i < allColumns.length; i++) {
        if (allColumns[i].getColDef().editable) {
          targetColIdx = i;
          break;
        }
      }
    } else {
      // 整行聚焦时，查找该行第一个可编辑列
      for (let i = 0; i < allColumns.length; i++) {
        if (allColumns[i].getColDef().editable) {
          targetColIdx = i;
          break;
        }
      }
    }

    if (targetColIdx !== -1) {
      // 聚焦找到的可编辑单元格
      this.gridApi.setFocusedCell(currentRowIdx, allColumns[targetColIdx].getId());
    } else {
      // 该行无可编辑单元格，聚焦下一行并整行高亮
      const nextRowIdx = currentRowIdx + 1;
      const nextRow = this.gridApi.getDisplayedRowAtIndex(nextRowIdx);
      if (nextRow) {
        this.gridApi.setFocusedCell(-1, '');
        this.gridApi.selectNode(nextRow, true);
        this.gridApi.setFocusedRow(nextRow);
      }
    }
  }
}

核心逻辑说明 #

1. Tab键拦截：通过onKeyDown事件监听Tab键，调用event.preventDefault()覆盖AgGrid默认的Tab导航行为；
2. 列头导航：使用columnApi获取当前聚焦列头，判断是否为最后一列，分别处理下一列头聚焦或第一行整行聚焦；
3. 行/单元格导航：
   • 若当前聚焦单元格，从当前列向后查找第一个可编辑单元格；
   • 若当前为整行聚焦，查找该行第一个可编辑单元格；
   • 未找到可编辑单元格时，自动聚焦下一行并整行高亮。

内容的提问来源于stack exchange，提问作者Ritik Dhabekar