VTable表格自定义渲染:技术实践与案例

VTable简介

VTable是一款基于可视化渲染引擎VRender的高性能表格组件库，为用户提供卓越的性能和强大的多维分析能力，以及灵活强大的图形能力。相对于dom表格，VTable 基于canvas 画布进行渲染，性能与可视化能力具有碾压级的优势。

picture.image 介绍文档：VTable——不只是高性能的多维数据分析表格，开源，免费，百万数据秒级渲染

在用户实际的应用场景中，随着需求的不断迭代，对于 VTable 的自定义能力提出来更高的要求。用户期望能够更加灵活、便捷地根据自身的特定需求来定制 VTable 的各项功能和特性，以满足不同业务场景下的多样化需求。为了更好地满足用户的这些需求，VTable 的自定义能力也在不断地进行优化和改进，进行了多个阶段的功能迭代。接下来，我们将分享这部分自定义能力的演进历程和功能展示。

第一阶段自定义内容和样式

属性配置函数

在VTable最初的版本，我们给用户提供了内容和样式的回调函数式的配置方式：

文字内容：在列或指标配置中，fieldFormat配置可以对单元格内容显示进行自定义处理，常用于文字内容的格式化


        
          
type FieldFormat = (record: any, col?: number, row?: number, table?: BaseTableAPI) => any;

图标：在列或指标配置中，icon配置除了支持固定的图标之外，也支持函数配置，不同单元格显示不同图标


        
          
type Icons = (string | ColumnIconOption)[] | ((args: CellInfo) => (string | ColumnIconOption)[]);

单元格样式（文字样式，单元格样式）：与图标相同，单元格相关的样式都支持函数式配置


        
          
{  
    // 斑马线效果  
    bgColor: (args: StylePropertyFunctionArg): string {  
      const { row, table } = args;  
      const index = row - table.frozenRowCount; // 计算该单元格在body区域的行index  
      if (!(index & 1)) {  
        return '#FAF9FB';  
      }  
      return '#FDFDFD';  
    }  
    // ......  
}

......

生成单元格节点时，会依据函数的不同返回结果，分别设置各个单元格内的内容和样式。

图形配置

在全局option、列或指标配置中，可以配置customRender属性，来自由定义单元格内的图形


        
          
type ICustomRenderObj = {  
  /** 配置出来的类型集合 */  
  elements: ICustomRenderElements;  
  /** 期望单元格的高度 */  
  expectedHeight: number;  
  /** 期望单元格的宽度 */  
  expectedWidth: number;  
  /** 是否还需要默认渲染内容 只有配置true才绘制 默认 不绘制 */  
  renderDefault?: boolean;  
};

elements为图元配置组成的数组，支持下列类型：

Text
Rect
Circle
Icon
Image
Arc
Line

详细配置可以参考 https://www.visactor.com/vtable/option/ListTable-columns-text#customRender.elements。

为了方便用户设置位置和尺寸，x y width height等属性支持配置百分比，基于单元格的宽度或高度设置；也可以在属性中使用函数，接收单元格数据，计算相应的属性值。

下面是一个气泡效果的配置：


        
          
{  
  customRender: {  
    elements: [  
      {  
        type: 'circle',  
        x: '50%', // 定位在单元格中心  
        y: '50%',  
        // 依据数据计算圆半径  
        radius: value => {  
          const percent = Math.max(5, (Number(value) / 59645 / 2) * 100);  
          return `${percent}%`;  
        },  
        // 依据数据计算渐变色  
        fill: value => {  
          const color = getColor(80, 59645, value, 0.5);  
          const color1 = getColor(80, 59645, value, 1);  
          return {  
            gradient: 'linear',  
            x0: 0,  
            y0: 1,  
            x1: 0,  
            y1: 0,  
            stops: [  
              {  
                offset: 0,  
                color: color  
              },  
              {  
                offset: 1,  
                color: color1  
              }  
            ]  
          };  
        }  
      }  
    ],  
    renderDefault: false  
  }  
  // ......  
 }

picture.image https://www.visactor.com/vtable/demo/business/sales-bubble

自定义场景树节点

针对各类新的复杂功能需求，我们希望提供较为底层的接口，支持用户自行组织VRender场景树节点，来实现单元格内复杂的内容；基于VRender提供的类flex布局能力，用户可以在单元格中进行自适应布局；针对表格中比较常用的一些功能组件（Tag, Chenkbox, Radio），我们也进行了封装，可以很方便的调用。

以一个简单的上下布局的标题标签为例：

picture.image


        
          
import { Group, Text, Tag } from '@visactor/vtable/es/vrender';  
// ......  
  
const options = {  
  columns: [  
    {  
      field: 'custom',  
      title: 'custom-layout',  
      customLayout: (args) => {  
        const { table, row, col, rect } = args;  
        const { height, width } = rect ?? table.getCellRect(col, row);  
  
        // 单元格容器  
        const container = new Group({  
          height,  
          width,  
          display: 'flex',  
          flexDirection: 'column',  
          flexWrap: 'nowrap'  
        });  
  
        // 上部group  
        const containerTop = new Group({  
          height: height / 2,  
          width: width,  
          display: 'flex',  
          flexDirection: 'row',  
          alignItems: 'center',  
          fill: 'yellow',  
          opacity: 0.1,  
        });  
  
        // 上部文字Title  
        const title = new Text({  
          text: 'custom-layout-title',  
          fontSize: 14,  
          color: '#333',  
          fontWeight: 600,  
          boundsPadding: [0, 0, 0, 20]  
        });  
  
        containerTop.add(title);  
  
        // 下部group  
        const containerBottom = new Group({  
          height: height / 2,  
          width: width,  
          display: 'flex',  
          flexDirection: 'row',  
          alignItems: 'center',  
          fill: 'green',  
          opacity: 0.1  
        });  
  
        // 下部tags  
        const tag1 = new Tag({  
          text: 'tag1',  
          textStyle: {  
            fontSize: 10,  
            fill: 'rgb(51, 101, 238)'  
          },  
          panel: {  
            visible: true,  
            fill: '#f4f4f2',  
            cornerRadius: 5  
          },  
          space: 5,  
          boundsPadding: [0, 0, 0, 20]  
        });  
  
        const tag2 = new Tag({  
          text: 'tag2',  
          textStyle: {  
            fontSize: 10,  
            fill: 'rgb(51, 101, 238)'  
          },  
          panel: {  
            visible: true,  
            fill: '#f4f4f2',  
            cornerRadius: 5  
          },  
          space: 5,  
          boundsPadding: [0, 0, 0, 20]  
        });  
  
        containerBottom.add(tag1);  
        containerBottom.add(tag2);  
  
        container.add(containerTop);  
        container.add(containerBottom);  
  
        return {  
          rootContainer: container,  
          renderDefault: false  
        };  
      }  
    },  
    // ......  
  ],  
  // ......  
}

为了方便定义节点，我们除了实例化后组装的方式外，也支持直接写jsx标签（需要用户的打包环境支持编译jsx），上面的节点也可以写为


        
          
const container = (  
  <VGroup  
    attribute={{  
      // ......  
    }}  
  >  
    <VGroup  
      attribute={{  
        // ......  
      }}  
    >  
      <VText  
        attribute={{  
          // ......  
        }}  
      ></VText>  
    </VGroup>  
    <VGroup  
      attribute={{  
        // ......  
      }}  
    >  
      <VTag  
        attribute={{  
          // ......  
        }}  
      ></VTag>  
      <VTag  
        attribute={{  
          // ......  
        }}  
      ></VTag>  
    </VGroup>  
  </VGroup>  
)

交互更新

直接操作VRender场景节点后，交互功能就可以使用相应的事件回调很方便的实现


        
          
// hover显示icon背景  
<VImage  
  attribute={{  
    id: 'location-icon',  
    width: 15,  
    height: 15,  
    image,  
    boundsPadding: [0, 0, 0, 10],  
    cursor: 'pointer'  
  }}  
  stateProxy={stateName => {  
    if (stateName === 'hover') {  
      // hover状态更新attribute  
      return {  
        background: {  
          fill: '#ccc',  
          cornerRadius: 5,  
          expandX: 1,  
          expandY: 1  
        }  
      };  
    }  
  }}  
  onMouseEnter={event => {  
    event.currentTarget.addState('hover', true, false);  
    event.currentTarget.stage.renderNextFrame();  
  }}  
  onMouseLeave={event => {  
    event.currentTarget.removeState('hover', false);  
    event.currentTarget.stage.renderNextFrame();  
  }}  
></VImage>

表格上浮层组件

针对在表格上层实现一个自定义浮层组件（例如tooltip、菜单等），不改变单元格内容的需求，我们提供了全局的CustomComponent组件，方便快速定位上层组件。

以一个简单的自定义tooltip为例：


        
          
function Tooltip(props) {  
  return (  
    <div style={{ width: '100%', height: '100%', border: '1px solid #333', backgroundColor: '#ccc', fontSize: 10 }}>  
      {`${props.value}`}  
    </div>  
  );  
}  
  
function App() {  
  const [hoverCol, setHoverCol] = useState(-1);  
  const [hoverRow, setHoverRow] = useState(-1);  
  const [value, setValue] = useState('');  
  const visible = useRef(false);  
  const tableInstance = useRef(null);  
  
  const updateHoverPos = useCallback(args => {  
    if (visible.current) {  
      return;  
    }  
    setHoverCol(args.col);  
    setHoverRow(args.row);  
    const cellValue = tableInstance.current.getCellValue(args.col, args.row);  
    setValue(cellValue);  
  }, []);  
  
  return (  
    <ListTable  
      ref = {tableInstance}  
      option={option}  
      onMouseEnterCell={updateHoverPos}  
    >  
      <CustomComponent  
        width="80%"  
        height="100%"  
        displayMode="cell"  
        col={hoverCol}  
        row={hoverRow}  
        anchor="bottom-right"  
        dx="-80%"  
      >  
        <Tooltip value={value} />  
      </CustomComponent>  
    </ListTable>  
  );

picture.image CustomComponent组件中，可以依据锚定的单元格的尺寸和位置，自动设置相关样式

可以设置相对于单元格的展示位置（anchor）
可以依据单元格的尺寸进行百分比设置自身的尺寸
可以使用dx dy进行位置微调

详细说明可以参考 https://www.visactor.com/vtable/guide/custom\_define/react-custom-component#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%A4%96%E9%83%A8%E7%BB%84%E4%BB%B6

表格单元格自定义组件

在jsx标签的基础上，基于react-reconciler我们对自定义渲染进行了完全的组件封装，用户可以使用提供的图元组件，封装一个真正的react组件。

以一个单元格展示两个Tag的简单组件为例：


        
          
function Cell(props) {  
  const { table, row, col, rect, prefix } = props;  
  if (!table || row === undefined || col === undefined) {  
    return null;  
  }  
  const { height, width } = rect || table.getCellRect(col, row);  
  const record = table.getRecordByRowCol(col, row);  
  
  return (  
    <Group  
      attribute={{  
        width,  
        height,  
        display: 'flex',  
        flexWrap: 'wrap',  
        flexDirection: 'row',  
        alignItems: 'center',  
        alignContent: 'center',  
        justifyContent: 'space-around'  
      }}  
    >  
      <Tag   
        textStyle={{  
          fontSize: 14,  
          fontFamily: 'sans-serif',  
          fill: 'rgb(51, 101, 238)'  
        }}  
        padding={[8, 10]}  
        panelStyle={{  
          visible: true,  
          fill: '#e6fffb',  
          lineWidth: 1,  
          cornerRadius: 4  
        }}  
      >{`${prefix}-${record.name}-1`}</Tag>  
      <Tag   
        textStyle={{  
          fontSize: 14,  
          fontFamily: 'sans-serif',  
          fill: 'rgb(51, 141, 38)'  
        }}  
        padding={[8, 10]}  
        panelStyle={{  
          visible: true,  
          fill: '#e6fffb',  
          lineWidth: 1,  
          cornerRadius: 4  
        }}  
      >{`${prefix}-${record.name}-2`}</Tag>  
    </Group>  
  );  
}  
  
function App() {  
  const tableInstance = useRef(null);  
  
  const [prefix, setPrefix] = useState('cus');  
  
  return (  
    <ListTable  
      ref={tableInstance}  
      records={[{name: 'tag'}]}  
    >  
      <ListColumn field={'name'} title={'Tag Component'} width={200}>  
        <Cell role={'custom-layout'} prefix={prefix}/>  
      </ListColumn>  
    </ListTable>  
  );  
}

picture.image 这里我们自定义了组件Cell，用来展示两个标签，内容由上层组件传递的props中的prefix和单元格数据决定。这里的组件和传统的组件会有一些区别：

组件中使用的标签，必须是react-vtable提供的图元和组件
每个列或指标只需要设置一个组件，这个组件会被应用在该列的所有单元格上
与customLayout的回调函数类似，组件会自带table, row, col, rect这些props供使用

除了基础的图元组件和Tag Checkbox Radio组件外，react-vtable也内置了Bottom, Link, Avatar和Poptip这些表格中的常用组件

picture.image 详细说明可以参考 https://www.visactor.com/vtable/guide/custom\_define/react-custom-component，自定义组件目前推荐在react环境，需要对单元格内自定义内容进行组件化封装的场景

表格单元格中使用react dom组件

如果需要在组件中使用DOM react组件，VRender支持在图元组件的attribute属性中，指定react属性，并将react组件作为element属性传入：


        
          
<Group  
  attribute={{  
    // ......  
    react: {  
      pointerEvents: true,  
      container: table.bodyDomContainer, // table.headerDomContainer  
      anchorType: 'bottom-right',  
      element: <CardInfo record={record} hover={hover} row={row} />  
    }  
  }}  
>  
// ...  
</Group>