文档维护人：张功

文档维护时间：2026.04.07

## 适用范围

Web 端e-builder低代码平台「数据列表 - 表格式」「表格视图 - 表格式」组件自定义渲染开发。

## 使用前提

- 代码需粘贴至平台 **ecode 编辑器** 中运行

---

## 一、数据列表 - 表格式

通过插件注册方式，重写表格单元格、整行渲染，支持动态修改列配置、绑定自定义事件、修改单元格原始内容。

### 示例 1：高级自定义渲染（单元格 + 行样式 + 事件）

支持：自定义单元格内容、行背景色、点击事件、重写单元格数据

jsx

```
import { eventEmitter } from '@weapp/utils';

// 替换为你的列表组件唯一 ID（从平台组件配置中获取）
const comId = 'eff5f11f260749e9a6d6fb151e3da51b';

class ExtraPlugin {
  name = 'ExtraPlugin';

  // 单元格自定义点击事件
  handleClick = (e) => {
    e?.stopPropagation();
    console.log('单元格自定义点击');
  };

  // 行渲染钩子：自定义行样式
  renderListItem = (hook) => {
    return (rowDatas, index, ...args) => {
      // 偶数行设置红色背景
      if (index % 2 === 0) {
        return (
          <div style={{ background: 'red' }}>
            {hook(rowDatas, index, ...args)}
          </div>
        );
      }
      return hook(rowDatas, index, ...args);
    };
  };

  // 单元格渲染钩子：重写内容、样式、数据
  renderCell = (hook) => {
    return (opts, ...args) => {
      const newOpts = {
        ...opts,
        data: {
          ...opts.data,
          '1': '自定义标题内容',
        },
        originValue: opts.field.id === '1' ? '自定义标题内容' : opts.originValue,
        value: opts.field.id === '1' ? '自定义标题内容' : opts.value,
      };

      return (
        <div onClick={this.handleClick}>
          <div style={{ color: 'red', fontWeight: 'bold' }}>自定义渲染标识</div>
          {hook(newOpts, ...args)}
        </div>
      );
    };
  };

  // 动态配置表格列（支持异步）
  getTableColumns() {
    const columns = [
      {
        id: 'id',
        name: 'id',
        objId: '910199253473665025',
        text: 'id',
        compType: 'Text',
        type: 'String',
        mainField: true,
        mainPrimaryKey: true,
        compMarkType: 'Field',
        uid: 'df1b7a4fd598479cba4e1a107a96ba7e',
        multiSelect: ''
      }
    ];

    const syncFields = () => {
      return new Promise(resolve => {
        setTimeout(() => {
          console.log('列配置同步完成');
          resolve(columns);
        }, 4000);
      });
    };

    return [[syncFields]];
  }
}

// 列表挂载前注册插件
eventEmitter.once('@weapp/designer', `onBeforeMount_${comId}`, (plugin) => {
  plugin.registerPlugin(ExtraPlugin);
});
```

### 示例 2：轻量修改单元格原内容

适合仅替换 / 包裹单元格内容的简单场景。

jsx

```
import { eventEmitter } from '@weapp/utils';

class EbCusListViewPluginHook {
  name = 'EbCusListViewPluginHook';
  pluginCenter = null;

  renderCell = (hook) => {
    return (opts, ...args) => {
      const { field, data } = opts || {};

      // 根据字段名 dhwb1 进行判断
      if (field?.name === 'dhwb1') {
        const cellValue = data?.[field?.id];

        if (cellValue === '111') {
          return '自定义内容';
        }
        if (cellValue === '222') {
          return <span className='custom-cls-bg-change'>{hook(opts, ...args)}</span>;
        }
      }

      // 默认返回原始渲染内容
      return hook(opts, ...args);
    };
  };
}

// 全局注册插件
window.weappUtils.eventEmitter.on('@weapp/designer', 'plugin_center.ready.NList', ({ registerPlugin }) => {
  registerPlugin(EbCusListViewPluginHook);
});
```

---

## 二、表格视图 - 表格式

使用轻量 `renderHandler` 钩子，支持表格 / 网格 / 分组视图自定义渲染，代码简洁，适合快速修改 HTML 结构。

### 完整示例

jsx

```
import { regOvProps } from '@weapp/utils';
/**
 * 自定义渲染钩子
 * @param {string} fieldId - 列字段 key
 * @param {any} value - 单元格原始值
 * @param {'table'|'grid'|'group'} type - 视图类型
 * @param {React.ReactNode} dom - 修改前原始 DOM
 * @param {object} otherInfo - 行数据、序号、列信息等附加数据
 * @returns {React.ReactNode}
 */
const renderHandler = (fieldId, value, type, dom, otherInfo) => {
  if (type === 'table') {
    // 给 field_1 包裹自定义样式
    if (fieldId === 'field_1') {
      return <div className='custom-cls'>{dom}</div>;
    }

    // field_2 直接替换为视图类型
    if (fieldId === 'field_2') {
      return type;
    }

    // field_3 使用原生 React.createElement
    if (fieldId === 'field_3') {
      return React.createElement('div', { className: 'custom-cls' }, dom);
    }
  }

  return dom;
};

// 注册到指定表格视图
regOvProps('weappEbdfpage', 'TList', (props) => {
  // 替换为你的表格视图 ID
  const targetViewId = '1126869989796036609';

  if (props.tableViewStore.viewId === targetViewId) {
    props.tableViewStore.setTableRenderHandler(renderHandler);
  }

  return props;
},0);
```

### 参数说明

表格

| **参数名** | **类型** | **必需** | **说明** |
| --- | --- | --- | --- |
| fieldId | string | 是 | 列字段唯一 key |
| value | any | 是 | 单元格原始数据 |
| type | string | 是 | 视图类型：table/grid/group（移动端不支持 group） |
| dom | ReactNode | 是 | 修改前的原始 DOM |
| otherInfo | object | 否 | 附加信息：行数据、行序号、列配置等 |

---

## 三、通用注意事项

1. **ID 获取**
  
  - 数据列表：选中列表组件 → 右侧配置栏获取组件 ID
  - 表格视图：在视图配置中获取视图 ID
2. **事件处理**
  
  自定义点击建议使用 `e.stopPropagation()`，避免触发列表默认行点击行为。
3. **样式规范**
  
  自定义类名建议添加唯一前缀，防止与平台默认样式冲突。
4. **数据修改**
  
  禁止直接修改原始 `opts`/`data`，优先使用对象展开或深拷贝。
5. **适用场景**
  
  - 复杂渲染（行样式、多事件、动态列）→ 数据列表插件方式
  - 简单内容 / 样式修改 → 表格视图 renderHandler 方式
