Ag Grid 组件 Vue Data Grid: Components

郑卜鹰

2023-12-01

前往官网查看原文档：Vue Data Grid: Components

您可以创建自己的自定义组件来自定义网格的行为。例如，您可以自定义单元格的呈现方式、值的编辑方式以及创建自己的过滤器。

您可以在 AG Grid 中提供的组件类型的完整列表如下：

Cell Renderer: 自定义单元格的内容。
Cell Editor: 自定义单元格的编辑。
Date Component: 自定义日期过滤器中的日期选择组件。
Filter Component: 对于显示在列菜单内的自定义列过滤器。
Floating Filter: 对于显示在列菜单内的自定义列浮动过滤器。
Header Component: 自定义列和列组的标题。
Loading Cell Renderer: 使用服务器端行模型时自定义加载单元格行。
Overlay Component: 自定义加载和无行覆盖组件。
Status Bar Component: 用于自定义状态栏组件。
Tool Panel Component: 用于自定义工具面板组件。
Tooltip Component: 用于自定义单元格工具提示组件。

本页的其余部分提供了所有组件类型的通用信息。

声明自定义组件

VueJS 组件可以定义为简单的内联组件，也可以定义为完整/复杂的外部组件（即在单独的文件中）。

“内联”组件

export default {
  data() {
      return {
          ...data 
      }
  },
  components: {
      AgGridVue,              // 实际的 AgGridVue 网格组件
      CubeComponent: {        // 内联自定义组件
          template: '<span>{{ valueCubed() }}</span>',
          methods: {
              valueCubed() {
                  return this.params.value * this.params.value * this.params.value;
              }
          }
      }
  }
}

请注意，我们可以定义带引号或不带引号的属性名称，但请注意，为了在你的列定义中引用这些组件，你需要将它们作为 区分大小写 的字符串来提供。

本地声明的组件

const SquareComponent = {
   template: '<span>{{ valueSquared() }}</span>',
   methods: {
       valueSquared() {
           return this.params.value * this.params.value;
       }
   }
};

外部化的 JavaScript 组件（.js 文件）

// SquareComponent.js
export default {
   template: '<span>{{ valueSquared() }}</span>',
   methods: {
       valueSquared() {
           return this.params.value * this.params.value;
       }
   }
};

外部化单文件组件（SFC / .vue 文件）

<template>
    <span class="currency">{{ params.value | currency('EUR') }}</span>
</template>

<script>
export default {
    filters: {
        currency(value, symbol) {
            let result = value;
            if (!isNaN(value)) {
                result = value.toFixed(2);
            }
            return symbol ? symbol + result : result;
        }
    }
};
</script>

<style scoped>
    .currency {
        color: blue;
    }
</style>

请注意，在这种情况下，组件名称将与实际引用相匹配，但如果您选择，则可以指定不同的名称：

components: {
    AgGridVue,
    'MySquareComponent': SquareComponent
}

如果您要按名称注册组件（见下文），则以上所有方法都有效。如果你希望通过直接引用注册组件，那么你需要用 Vue.extend(...your component...)( 对于 Vue 2 )或 defineComponent(...your component...)( 对于 Vue 3)。

我们强烈建议按名称注册，因为它提供了灵活性——我们所有的示例都使用按名称注册。

注册自定义组件

每种组件类型（单元格渲染器、单元格编辑器等）的页面都包含如何注册和使用每种组件类型的例子。然而，在这里，退一步讲，把注意力集中在所有组件类型所共有的组件注册过程上，是很有用的。

注册自定义组件一般有两种方式（“内联”组件只能按名称注册）：

按名称
直接引用（已弃用）

网格完全支持这两个选项 - 但是我们建议按名称引用，因为不推荐使用直接引用注册。按名称注册也是两种选择中更灵活的一种，鉴于此，文档中的所有示例都使用按名称注册。保留直接引用方法是为了向后兼容，因为这是在 AG Grid 中的原始方法。

注册内联自定义组件

内联自定义组件只能按名称在网格中注册：

<template>
  <ag-grid-vue :columnDefs="columnDefs" ...other properties>
  </ag-grid-vue>
</template>

<script>
//...other imports
import {AgGridVue} from "ag-grid-vue3";

export default {
  components: {
      AgGridVue,
      CubeComponent: {
          template: '<span>{{ valueCubed() }}</span>',
          methods: {
              valueCubed() {
                  return this.params.value * this.params.value * this.params.value;
              }
          }
      }
  },
  data() {
      return {
          columnDefs: [
               {
                  headerName: "Cube",
                  field: "value",
                  cellRenderer: 'CubeComponent',     
              }
          ]
      }
  }
  //...other properties & methods
}
</script>

注册非内联自定义组件

1. 按名称

要在网格中使用组件，您将通过区分大小写的名称引用组件，例如：

<template>
  <ag-grid-vue ...other properties>
  </ag-grid-vue>
</template>

<script>
//...other imports
import {AgGridVue} from "ag-grid-vue3";
import CubeComponent from './CubeComponent.vue';

export default {
  components: {
      AgGridVue,
      CubeComponent
  }
  data() {
      return {
          columnDefs: [
               {
                  headerName: "Cube",
                  field: "value",
                  cellRenderer: 'CubeComponent'     
              }
          ]
      }
  }
  //...other properties & methods
}
</script>

2. 直接引用（已弃用）

弃用
此方法受支持但不推荐，并将在未来版本中删除。

通过直接引用在 Grid 中注册组件时，目标组件必须包装在 Vue.extend(...)（对于 Vue 2）或 defineComponent(...)（对于 Vue 3）中：

<template>
  <ag-grid-vue ...other properties>
  </ag-grid-vue>
</template>

<script>
//...other imports
import Vue from "vue";
import {AgGridVue} from "ag-grid-vue3";

// 包裹在 Vue.extend 中的组件可直接引用
const CubeComponent = Vue.extend({
  template: '<span>{{ valueCubed() }}</span>',
  methods: {
      valueCubed() {
          return this.params.value * this.params.value * this.params.value;
      }
  }
};


export default {
  components: {
      AgGridVue,
      // CubeComponent在直接引用注册的时候可以不用在这里注册
  }
  data() {
      return {
          columnDefs: [
               {
                  headerName: "Cube",
                  field: "value",
                  cellRenderer: CubeComponent
              }
          ]
      }
  }
  //...other properties & methods
}
</script>

按名称引用的优势

按名称注册组件具有以下优点：

无需更改所有列定义即可更改实现。例如，您可能有 20 列使用货币单元格渲染器。如果你想将单元格渲染器更新为另一个货币单元格渲染器，你只需要在唯一的地方（注册单元格渲染器的地方）进行更新，所有列都将采用新的实现。
指定列定义的网格部分是纯 JSON。这对于从静态数据读取列定义的应用程序很有帮助。如果您直接在列定义中引用类名，则无法将列定义转换为 JSON。
无需使用 Vue.extend(...)/ defineComponent(...)包装组件

提供附加参数

每个自定义组件都从网格中获取一组参数。例如，对于 Cell Renderer，除其他外，网格提供了要渲染的值。您可以通过提供特定于您的应用程序的附加参数来为自定义组件提供附加属性（例如要使用的货币符号）。

要提供额外的参数，请使用属性 [prop-name]Params，例如 cellRendererParams。

<ag-grid-vue
    :columnDefs="columnDefs"
    /* other grid options ... */>
</ag-grid-vue>

this.columnDefs = [
    { 
        field: 'price',
        cellRenderer: PriceCellRenderer,
        cellRendererParams: {
            currency: 'EUR'
        }
    },
]

混合 JavaScript 和 Vue

提供自定义组件时，您可以选择以下选项：

在 JavaScript 中提供一个 AG Grid 组件。
提供一个 AG Grid 组件作为 Vue 组件。

例如，如果你想构建一个单元格渲染器，你可以选择使用 Vue 或纯 JavaScript 来构建单元格渲染器。

下面的代码片段展示了如何同时使用 JavaScript 和 Vue 组件：

<template>
  <ag-grid-vue :components="components" 
               ...other properties>
  </ag-grid-vue>
</template>

<script>
//...other imports
import {AgGridVue} from "ag-grid-vue3";
import JavascriptComponent from './JavascriptComponent.js';
import VueComponent from './VueComponent.vue';

export default {
  components: {
      AgGridVue,
      // Vue组件在这里注册
      'vueComponent': VueComponent
  }
  data() {
      return {
          // JavaScript 组件在这里注册，用于按名称查找组件时
          components: {
              // 声明javascript组件
              'javascriptComponent': JavascriptComponent
          },          
          columnDefs: [
               {
                  headerName: "JS Cell",
                  field: "value",
                  cellRenderer: 'javascriptComponent',    // 按名称引用/使用 javascript 组件
              },
               {
                  headerName: "JS Cell",
                  field: "value",
                  cellRenderer: JavascriptComponent,    // 直接引用/使用javascript组件
              },
              {
                  headerName: "Vue Cell",
                  field: "value",
                  cellRenderer: 'vueComponent',  // 引用/使用 Vue 组件
              }
          ]
      }
  }
  //...other properties & methods
}
</script>

查看如何创建纯 JavaScript 组件

组件的使用情况

下表总结了组件的配置位置以及使用的属性

组件	名称	位置	属性
Cell Renderer	自定义单元格	Column Definition	cellRenderer cellRendererParams cellRendererSelector
Cell Editor	自定义单元格编辑器	Column Definition	cellEditor cellEditorParams cellEditorSelector
Filter	对于显示在列菜单内的自定义列过滤器	Column Definition	filter filterParams
Floating Filter	对于显示在列菜单内的自定义列浮动过滤器	Column Definition	floatingFilter floatingFilterParams
Header Component	用于呈现正常的列标题。为列配置。	Column Definition	headerComponent headerComponentParams
Header Group Component	用于呈现列组。为列组配置。	Column Definition	headerGroupComponent headerGroupComponentParams
Tooltip Component	工具提示组件允许您将自己的工具提示添加到网格的列标题和单元格中	Column Definition	tooltipComponent tooltipComponentParams
Group Row Cell Renderer		Grid Option	groupRowRenderer groupRowRendererParams
Group Row Inner Cell Renderer		Grid Option	innerRenderer innerRendererParams
Detail Cell Renderer		Grid Option	detailCellRenderer detailCellRendererParams
Full Width Cell Renderer		Grid Option	fullWidthCellRenderer fullWidthCellRendererParams
Loading Cell Renderer	加载中单元格渲染器	Grid Option	loadingCellRenderer loadingCellRendererParams
Loading Overlay	加载中覆盖组件	Grid Option	loadingOverlayComponent loadingOverlayComponentParams
No Rows Overlay	表格无数据时覆盖组件	Grid Option	noRowsOverlayComponent noRowsOverlayComponentParams
Date Component	自定义日期过滤器中的日期选择组件	Grid Option	dateComponent dateComponentParams
Status Bar Component	自定义状态栏组件	Grid Option -> Status Bar	statusPanel statusPanelParams
Tool Panel	自定义工具面板组件	Grid Option -> Side Bar	toolPanel toolPanelParams

网格自带提供的组件

网格带有可以使用的预注册组件。网格提供的每个组件都以命名空间 ag开头，以尽量减少与用户提供的组件的命名冲突。网格提供的组件的完整列表在下表中：

Date Inputs 日期输入
agDateInput	过滤器使用的默认日期输入

Column Headers 列标题
agColumnHeader	默认列标题
agColumnHeaderGroup	默认列组标题

Column Filters 列过滤器
agSetColumnFilter	设置过滤器（使用 AG Grid Enterprise 时的默认设置）
agTextColumnFilter	简单文本过滤器（使用 AG Grid Community 时的默认设置）
agNumberColumnFilter	数字过滤器
agDateColumnFilter	日期过滤器

Floating Filters 浮动过滤器
agSetColumnFloatingFilter	浮动组过滤器
agTextColumnFloatingFilter	浮动文本过滤器
agNumberColumnFloatingFilter	浮动数字过滤器
agDateColumnFloatingFilter	浮动日期过滤器

Cell Renderers 单元格渲染器
agAnimateShowChangeCellRenderer	使数值变化产生动画效果的单元格渲染器
agAnimateSlideCellRenderer	使数值变化产生动画效果的单元格渲染器
agGroupCellRenderer	用于显示组信息的单元格渲染器
agLoadingCellRenderer	使用企业行模型时，用于加载行的单元格渲染器

Overlays 覆盖器
agLoadingOverlay	加载中…覆盖器
agNoRowsOverlay	数据为空覆盖器

Cell Editors 单元格编辑器
agTextCellEditor	单元格文本编辑器
agSelectCellEditor	单元格选择编辑器
agRichSelectCellEditor	丰富的选择编辑器
agLargeTextCellEditor	大文本框单元格编辑器

Master Detail 细节网格
agDetailCellRenderer	主格/细节格的细节面板

覆盖网格组件

也可以覆盖组件。在网格使用默认值的地方，这意味着将改用覆盖组件。覆盖有意义的默认组件如下：

agDateInput: 更改所有过滤器的默认日期选择。
agColumnHeader: 更改所有列的默认列标题。
agColumnGroupHeader: 更改所有列的默认列组标题。
agLoadingCellRenderer: 更改企业行模型的默认加载单元格渲染器。
agLoadingOverlay: 更改默认的“加载”覆盖。
agNoRowsOverlay: 更改默认加载“无行”覆盖。
agCellEditor: 更改默认的单元格编辑器。
agDetailCellRenderer: 更改主/细节网格的默认细节面板。

要覆盖默认组件，请在上述名称下的 GridOptions components属性中注册自定义组件。

const MyApp = {
   // 这是我们指定要使用的组件而不是默认组件的地方
   components: {
       'ag-grid-vue': AgGridVue
       agDateInput: CustomDateComponent,
       agColumnHeader: CustomHeaderComponent
   },

可重写的网格组件是唯一需要用components额外指定的组件，以便将其使用与实际的组件联系起来。所有其他的注册类型在列定义中或在AgGridVue组件本身上指定它们的用途。

关于这方面的例子，请参考日期组件的文件。