ag-grid学习笔记：了解 ag-Grid 编辑的基本功能（二）

了解 ag-Grid 编辑功能

ag-Grid 是一个强大的 JavaScript 数据网格库，广泛用于展示和处理大量数据。其中一个突出的功能是编辑功能，允许用户直接在网格中编辑数据。本文将深入探讨 ag-Grid 编辑功能，包括基础知识、内置编辑器、自定义编辑器以及一些实用技巧和最佳实践。

编辑基础

在使用 ag-Grid 编辑功能之前，首先需要了解如何将单元格设置为可编辑状态。这可以通过简单的配置来实现：

columnDefs: [
  { headerName: '姓名', field: 'name', editable: true },
  { headerName: '年龄', field: 'age', editable: true },
  // 其他列配置...
],

上述代码中，我们将 '姓名' 和 '年龄' 列设置为可编辑。用户现在可以点击这些单元格，并直接在网格中编辑相应的数据。

内置编辑器

ag-Grid 提供了一些内置编辑器，使得常见的编辑需求更加便捷。例如，如果你希望用户能够直接在网格中输入文本，可以使用内置的文本框编辑器。以下是一个示例：

columnDefs: [
  { headerName: '姓名', field: 'name', editable: true, cellEditor: 'agTextCellEditor' },
  // 其他列配置...
],

通过将 cellEditor​ 属性设置为 'agTextCellEditor'​，我们启用了文本框编辑器。用户现在可以在 '姓名' 列中直接输入文本。

自定义编辑器

有时候，内置编辑器无法满足特定需求，这时可以使用自定义编辑器。假设我们想要在 '年龄' 列中使用一个自定义的下拉列表编辑器：

columnDefs: [
  { headerName: '姓名', field: 'name', editable: true, cellEditor: CustomEditor, cellEditorParams: {} },
  // 其他列配置...
],

通过将 cellEditor​ 属性设置为自定义编辑器组件，cellEditorParams​属性设置自定义编辑器组件的入参。我们可以轻松地实现对 '年龄' 列的自定义编辑。

实用技巧和最佳实践

动态设置编辑状态

editable可以设置为一个函数，根据参数中的data设置是否可以编辑，data为当前行对象。

let editableYear = 2012;

const isCellEditable = (params) => {
  return params.data.year === editableYear;
};

editable: (params) => {
    return isCellEditable(params);
},

批量编辑

如果你需要让用户批量编辑数据，可以考虑使用 ag-Grid 的批量编辑功能。通过选中多个单元格，用户可以一次性编辑它们的值，提高了编辑效率。

gridOptions: {
  enableRangeSelection: true,
},

设置 enableRangeSelection​ 为 true​ 启用批量编辑功能。

验证和错误处理

在处理编辑数据时，不要忽视数据的验证和错误处理。ag-Grid 提供了相应的事件和回调，可以用于实现验证逻辑和处理错误情况。

onCellValueChanged: function (params) {
  // 编辑数据变化时的逻辑...
  if (params.newValue < 0) {
    // 处理错误情况...
    params.node.setDataValue(params.colDef.field, 0); // 将值重置为0
  }
},

在 onCellValueChanged​ 事件中，我们可以检查编辑后的值，并进行相应的处理。

‍

进阶

ag-Grid 不仅提供了基本的编辑功能，还支持许多高级配置和数据结构。

Column Types（列类型）

​columnTypes​ 允许你定义一组列的通用配置，以便在列定义中重复使用。这对于具有相似特性的列非常有用。例如，如果你有多个需要相同编辑器的列，可以使用 columnTypes​ 统一定义：

columnTypes: {
  editableColumn: { 
	editable: (params) => {
       return isCellEditable(params);
    },
    cellStyle: (params) => {
       if (isCellEditable(params)) {
         return { backgroundColor: "lightBlue" };
       }
    },
	cellEditor: 'agTextCellEditor' 
},

columnDefs: [
  { headerName: '姓名', field: 'name', type: 'editableColumn' },
  { headerName: '年龄', field: 'age', type: 'editableColumn' },
  // 其他列配置...
],

通过使用 type​ 属性引用 columnTypes​ 中定义的配置，我们可以更简洁地管理列的编辑设置。控制可编辑的单元格以及可编辑单元格样式

Data Types Definitions（数据类型定义）

​dataTypeDefinitions​ 允许你定义特定列的数据类型，从而影响编辑器的行为。例如，你可以指定一个列为日期类型，以使用日期选择器编辑器：

dataTypeDefinitions: {
  'date': { editable: true, cellEditor: 'agDateInput' },
},

columnDefs: [
  { headerName: '生日', field: 'birthday', type: 'date' },
  // 其他列配置...
],

通过使用 type​ 属性引用 dataTypeDefinitions​ 中定义的数据类型，我们可以为不同的列应用不同的编辑器。

Reference Data（引用数据）

在某些情况下，我们需要使用引用数据（refData​）来提供单元格的选项。这在使用下拉列表等编辑器时非常有用：

const genderMappings = {
	"male": "男",
	"female": "女"
}

function lookupKey(mappings, name) {
  const keys = Object.keys(mappings);

  for (let i = 0; i < keys.length; i++) {
    const key = keys[i];

    if (mappings[key] === name) {
      return key;
    }
  }
}

refData: genderMappings,
columnDefs: [
  {
	headerName: '性别', 
	field: 'gender', 
	editable: true, 
	cellEditor: 'agSelectCellEditor', // agSelectCellEditor是ag-grid内置的下拉框选择器
	cellEditorParams: { values: Object.keys(genderMappings) }, // values是agSelectCellEditor下拉框的选项列表
	// 对编辑器返回的值进行解析
	valueParser: (params) => {
      return lookupKey(genderMappings, params.newValue);
    },
  },
  // 其他列配置...
],

这里，我们使用 refData​ 定义了 'gender' 列的可选项，然后通过 cellEditorParams​ 将这些选项传递给下拉列表编辑器。

同一列存在多种编辑器

有时候存在这种同一列下，数据类型或来源不一致的情况，要求可以动态设置编辑器。可以通过设置 colDef.cellEditorSelector​ 属性来实现，该属性是一个函数，用于为给定行选择不同的编辑器和编辑器参数。

// 在 ag-Grid 组件中的使用方式
<AgGridReact
  // 其他配置...
  columnDefs={[
    {
      headerName: '值',
      field: 'value',
      editable: true,
      cellEditorSelector: (params) => {
        // 根据行数据的类型选择不同的编辑器
        if (params.data.type === 'age') {
          return {
            component: NumericCellEditor,
          };
        }

        if (params.data.type === 'gender') {
          return {
            component: 'agRichSelectCellEditor',
            params: {
              values: ['Male', 'Female'],
            },
          };
        }

        if (params.data.type === 'mood') {
          return {
            component: MoodEditor,
            popup: true,
            popupPosition: 'under',
          };
        }

        // 如果没有匹配的类型，返回 undefined
        return undefined;
      },
    },
    {
      headerName: 'Type',
      field: 'type',
    },
    // 其他列配置...
  ]}
/>

处理复杂数据结构

如果你的数据具有更复杂的结构，例如嵌套对象或数组，你可以通过 valueGetter​ 和 valueSetter​ 配置来实现自定义的数据处理逻辑。例如，如果数据是嵌套对象：

columnDefs: [
  { headerName: '国家', field: 'address.country', editable: true,
    valueGetter: function (params) {
      return params.data.address ? params.data.address.country : '';
    },
    valueSetter: function (params) {
      if (!params.data.address) {
        params.data.address = {};
      }
      params.data.address.country = params.newValue;
      return true;
    },
  },
  // 其他列配置...
],

通过使用 valueGetter​ 和 valueSetter​，我们可以自定义提取和设置嵌套属性的逻辑。

结论

ag-Grid 编辑功能为处理大量数据提供了灵活性和便捷性。通过简单的配置，你可以启用单元格编辑，并通过内置或自定义编辑器满足特定需求。在实际项目中，结合实用技巧和最佳实践，你可以更好地利用 ag-Grid 的编辑功能，使数据编辑变得更加轻松。通过合理使用 columnTypes​、dataTypeDefinitions​、refData​ 以及自定义的数据处理逻辑，可以更好地适应不同的编辑需求。

这只是一个简单的入门，希望它能帮助你更好地了解和使用 ag-Grid 的编辑功能。

‍