vxe-table 渲染器教程一：实现金额输入控件

在开发后台管理系统时，表格中的金额字段往往需要特殊的展示和编辑方式，例如右对齐、保留两位小数、带货币符号前缀等。vxe-table 的自定义渲染器（Renderer） 机制，允许我们将任何 Vue 组件嵌入到表格单元格中，实现高度定制化的交互体验。

一、什么是渲染器？

渲染器是 vxe-table 中用于控制单元格如何渲染和交互的核心机制。它主要解决两类问题

场景	说明
展示模式（只读）	单元格以什么样式显示数据，例如金额加“￥”前缀、状态标签加颜色等
编辑模式（可编辑）	单元格激活编辑时，使用什么组件来输入/选择数据，例如输入框、下拉选择器、日期选择器等

通过自定义渲染器，你可以将任意 Vue 组件嵌入表格单元格，实现表单控件与表格的无缝融合。

二、实现步骤

第 1 步：创建控件组件

首先，创建一个 Vue 组件来实现金额输入的逻辑。命名随意，这里以 DemoEditAmount.vue 为例。组件内部可以使用任意 UI 库的组件（如 Element Plus等），这里使用 vxe-table 自带的 vxe-number-input。

<template>
  <vxe-number-input v-if="currRow && currColumn" v-model="currRow[currColumn.field]" type="float" digits="2" prefix-icon="vxe-icon-rmb" align="right"> </vxe-number-input>
</template>

<script setup>
import { ref } from 'vue'

const props = defineProps({
  renderParams: {
    type: Object,
    default: () => ({})
  }
})

const currColumn = ref()

const currRow = ref()

const load = () => {
  const { renderParams } = props
  const { row, column } = renderParams
  currRow.value = row
  currColumn.value = column
}

load()
</script>

• 关键点：
  • 组件通过 renderParams 接收当前行的数据（row）和列配置（column）。
  • 通过 v-model="currRow[currColumn.field]" 实现双向绑定，修改会自动同步到表格数据源。

第 2 步：注册渲染器

在 main.js 引入 VxeUI.renderer.add 注册自定义渲染器。

import { VxeUI } from 'vxe-table'
import DemoEditAmount from './DemoEditAmount.vue'

// 创建一个金额输入渲染器
VxeUI.renderer.add('MyTableEditAmount', {
  // 如果是输入框类型，可以设置为激活自动聚焦 class
  tableAutoFocus: 'input',
  // 金额右对齐
  tableCellAlign: 'right',
  // 可编辑激活模板
  renderTableEdit(renderOpts, renderParams) {
    return <DemoEditAmount render-params={renderParams} />
  },
  // 可编辑显示模板
  renderTableCell(renderOpts, renderParams) {
    const { row, column } = renderParams
    return <span>￥{row[column.field]}</span>
  }
})

• 配置项说明：

属性	类型	说明
tableAutoFocus	string	编辑激活时，自动聚焦的选择器（如 'input'）
tableCellAlign	string	单元格内容对齐方式：'left'、'center'、'right'
renderTableEdit	function	编辑模式下的渲染函数，返回 Vue 组件
renderTableCell	function	只读模式下的渲染函数，返回展示内容

注意：渲染器的实现需要 JSX/TSX 环境支持，请确保项目已配置相关编译工具。

开始使用

<template>
  <div>
    <vxe-grid v-bind="gridOptions"></vxe-grid>
  </div>
</template>

<script lang="jsx" setup>
import { reactive } from 'vue'

const amountEditRender = reactive({
  name: 'MyTableEditAmount'
})

const numEditRender = reactive({
  name: 'MyTableEditAmount'
})

const gridOptions = reactive({
  border: true,
  showOverflow: true,
  height: 300,
  editConfig: {
    trigger: 'click',
    mode: 'cell'
  },
  columns: [
    { type: 'seq', width: 50 },
    { field: 'name', title: 'name' },
    { field: 'amount', title: 'Amount', editRender: amountEditRender },
    { field: 'num', title: 'Num', editRender: numEditRender }
  ],
  data: [
    { id: 10001, name: 'Test1', amount: '65', num: 28 },
    { id: 10002, name: 'Test2', amount: '31', num: 22 },
    { id: 10003, name: 'Test3', amount: '20', num: 32 },
    { id: 10004, name: 'Test4', amount: '12', num: 23 }
  ]
})
</script>

• 通过自定义渲染器，vxe-table 的单元格渲染能力得到了极大扩展：
  • 展示灵活：可以渲染任意 HTML 或 Vue 组件。
  • 编辑强大：支持嵌入任意表单控件，实现复杂交互。
  • 复用便捷：一次注册，多列复用。

本文以金额输入控件为例，完整演示了从组件创建、渲染器注册到表格使用的全流程。下一期我们将探讨更复杂的渲染器场景——例如带校验、联动、异步数据等高级功能。

https://vxetable.cn