React-VTable custom components

Custom cell components

To help react developers quickly implement custom cell content, React-VTable provides the ability to encapsulate components and use them in cells.

Component usage

To use custom cell component, need to use react 18 version

Custom cell components are encapsulated based on custom layout, and their usage is similar to custom layout. To use components in ListColumn, custom components need to pass in the role attribute to identify the component as a custom cell component; the custom-layout component will take effect in the table content part, and the header-custom-layout component will take effect in the table header part. There can be at most one custom-layout component in each column, and at most one header-custom-layout component.

  <ListTable records={records}>
    <ListColumn field={'bloggerName'} title={'bloggerName'} width={330} disableHover={true}>
      <CustomLayoutComponent role={'custom-layout'} info={bodyInfo}/>
      <HeaderCustomLayoutComponent role={'header-custom-layout'} info={headerInfo}/>
    </ListColumn>
    // ......
  </ListTable>

Component encapsulation

Default properties

In the component, in addition to user-defined properties, like custom layouts, react-vtable also provides some default properties for components to use

interface CustomLayoutProps {
  table: ListTable; // 表格实例
  row: number; // 行号
  col: number; // 列号
  value: FieldData; // 单元格展示数据
  dataValue: FieldData; // 单元格原始数据
  rect?: RectProps; // 单元格布局信息
}
const CustomLayoutComponent = (props: CustomLayoutProps & UserProps) => {
  const { table, row, col, rect, text } = props;
  // ......
}

Label

The label returned by the component must be based on the element label provided by react-vtable (HTML tags or DOM react components cannot be used directly. If you need to use them, please refer to the next section)

import { Group, Text } from '@visactor/react-vtable';

const CustomLayoutComponent = (props: CustomLayoutFunctionArg & { text: string }) => {
  const { table, row, col, rect, text } = props;
  if (!table || row === undefined || col === undefined) {
    return null;
  }
  const { height, width } = rect || table.getCellRect(col, row);
  const [hover, setHover] = useState(false);

  const fieldData = [
    {
      value: 'a',
      label: 'a'
    },
    {
      value: 'b',
      label: 'b'
    }
  ];

  const groupRef = useRef(null);

  return (
    <Group
      attribute={{
        width,
        height,
        display: 'flex',
        flexWrap: 'wrap',
        alignItems: 'center',
        alignContent: 'center'
      }}
      ref={groupRef}
    >
      {fieldData.map(item => {
        return (
          <Text
            key={item.value}
            attribute={{
              text: `${text}-${row}`,
              fill: hover ? 'red' : '#000'
            }}
            onMouseEnter={(event: any) => {
              // eslint-disable-next-line no-console, no-undef
              console.log('groupRef', groupRef.current);
              setHover(true);
              event.currentTarget.stage.renderNextFrame();
            }}
            onMouseLeave={(event: any) => {
              setHover(false);
              event.currentTarget.stage.renderNextFrame();
            }}
          />
        );
      })}
      {hover && (
        <Text
          attribute={{
            text: 'hover',
            fill: 'blue',
          }}
        />
      )}
    </Group>
  );
};

Basic graphic component

Basic graphics:

Text
Rect
Image
Line
Arc
Circle
Group

For specific configuration properties, please refer to VRender element configuration, and for specific usage and layout, please refer to custom layout, reference example.

React-VTable component

In order to facilitate users to quickly implement customized cell content, React-VTable provides some commonly used components in table scenarios:

Tag

API

Property	Type	Description
text	string	Text content
textStyle	TextStyleOption	Text style
panelStyle	RectStyleOption	Label background style
padding	number \| number[]	Padding
minWidth	number	Maximum width of label
maxWidth	number	Minimum width of label

Radio

API

Property	Type	Description
text	string	Text content
textStyle	TextStyleOption & {disableFill?: string}	Text style
circleStyle	ArcStyleOption & {disableFill?: string;checkedFill?: string;checkedStroke?: string;disableCheckedFill?: string;disableCheckedStroke?: string;}	Circular check icon style
interactive	boolean	Interactive
disabled	boolean	Disable radio button
checked	boolean	Checked
cursor	Cursor	cursor style
disableCursor	Cursor	Disable cursor style
spaceBetweenTextAndIcon	number	Icon text spacing
onChange	(checked: boolean) => void	Checked state change callback

Checkbox

API

| Attributes | Type | Description | --- | --- | --- | | text | string | Text content | | textStyle | TextStyleOption & {disableFill?: string} | text style | | boxStyle | RectStyleOption & {disableFill?: string;checkedFill?: string;checkedStroke?: string;disableCheckedFill?: string;disableCheckedStroke?: string;} | Check icon style | | iconStyle | ImageStyleOption & {{checkIconImage?: string | HTMLImageElement | HTMLCanvasElement;indeterminateIconImage?: string | HTMLImageElement | HTMLCanvasElement;}} | Check icon background style| | interactive | boolean | Is it interactive?| | disabled | boolean | Is the radio button disabled?| | checked | boolean | Is it checked?| | indeterminate | boolean | Is the indeterminate state displayed? | | cursor | Cursor | cursor style| | disableCursor | Cursor | Cursor style when disabled| | spaceBetweenTextAndIcon | number | Icon text spacing| | onChange | (checked: boolean) => void | Selected state change callback |

Button

API

Property	Type	Description
textStyle	TextStyleOption	Text style
panelStyle	RectStyleOption	Background style
padding	number \| number[]	Padding
disabled	boolean	Disabled
cursor	Cursor	cursor style
minWidth	number	Minimum button width
maxWidth	number	Maximum button width
onClick	(event: MouseEvent) => void	Click event callback
state	{textStyle?: {hover?: TextStyleOption; disabled?: TextStyleOption;};panelStyle?: {hover?: RectStyleOption;disabled?: RectStyleOption;};}	State Style

Link

API

Property	Type	Description
textStyle	TextStyleOption	Text style
panelStyle	RectStyleOption	Background style
disabled	boolean	Disabled
cursor	Cursor	cursor style
minWidth	number	Minimum link width
maxWidth	number	Maximum link width
onClick	(event: MouseEvent) => void	Click event callback
state	{textStyle?: {hover?: TextStyleOption; disabled?: TextStyleOption;};panelStyle?: {hover?: RectStyleOption;disabled?: RectStyleOption;};}	Status style
icon	boolean	Whether to display the left icon
space	number	Spacing between icon and text
href	string	Link address

Avatar

API

Property	Type	Description
textStyle	TextStyleOption	Text style
panelStyle	RectStyleOption	Background style
size	number	Size
shape	'circle' \| 'square'	Shape
autoFixFontSize	boolean	Whether to automatically adjust the font size
onClick	(event: MouseEvent) => void	Click event callback

It should be noted that the Popover component uses the DOM solution, and ReactDom needs to be passed in the ReactDOM attribute, otherwise it cannot be rendered normally; the ReactNode type received by the content attribute needs to be a DOM tag or component, otherwise it cannot be rendered normally.

API

Property	Type	Description
defaultPopupVisible	boolean	Whether to display the bubble card by default
popupVisible	boolean	Whether to display the bubble card
position	'top' \| 'tl' \| 'tr' \| 'bottom' \| 'bl' \| 'br' \| 'left' \| 'lt' \| 'lb' \| 'right' \| 'rt' \| 'rb'	Bubble card position
content	ReactNode	Bubble card content (DOM tag or component)

The React-VTable component library is being continuously enriched. Developers are welcome to encapsulate new components during use and build a component library ecosystem together.

Use DOM react components

If you need to use DOM react components in components, you can specify the react attribute in the attribute property of the element component and pass the react component as the element property:

<Group
  attribute={{
    // ......
    react: {
      pointerEvents: true,
      container: table.bodyDomContainer, // table.headerDomContainer
      anchorType: 'bottom-right',
      element: <CardInfo record={record} hover={hover} row={row} />
    }
  }}
  onMouseEnter={(event) => {
    setHover(true);
    event.currentTarget.stage.renderNextFrame();
  }}
  onMouseLeave={(event) => {
    setHover(false);
    event.currentTarget.stage.renderNextFrame();
  }}
>
// ...
</Group>

The following properties are also supported in react:

pointerEvents whether to respond to mouse events
penetrateEventList Mouse event penetration list, used to specify which mouse events need to be penetrated to the VTable (currently only supports wheel)
container Container, used to limit the component display area in the table when scrolling. If you need to limit the component display in the table content area, you need to specify it as table.bodyDomContainer; if you need to limit the component display in the table header area, you need to specify it as table.headerDomContainer; if it is a pop-up window or menu component, you do not need to configure this property
anchorType Anchor type, used to specify the anchor position of the upper left corner of the component relative to the cell
- 'top'
- 'bottom'
- 'left'
- 'right'
- 'top-right'
- 'top-left'
- 'bottom-right'
- 'bottom-left'
- 'center'

We recommend that users use the meta tags provided by react-vtable for the content displayed in the cell. For pop-ups, menus and other components triggered in the cell, you can use DOM react components. This is the best performance solution. Reference example.

If you need to display content in a cell, use DOM react components. You need to specify react.container according to the restrictions on components displayed in the table content area. It should be noted that this method requires frequent updates of component-related DOM, which will have a certain impact on performance. You can refer to custom layout. We strongly recommend that the content components in the cell use the meta tags provided by react-vtable, which is the best solution for performance.

Custom external components

In order to facilitate the overlay of external components on the React-VTable component, React-VTable provides the CustomComponent tool component, which allows you to quickly locate external components in the table, and can be used to quickly implement functional components such as pop-ups and menus.

<ListTable option={option} onMouseEnterCell={updatePos} onMouseLeaveTable={hide} onReady={ready}>
  <CustomComponent width="50%" height="100%" displayMode="cell" col={col} row={row} anchor="bottom-right" dx="-50%">
    <UserComponent value={value} />
  </CustomComponent>
</ListTable>

Among them, CustomComponent is used as a container to position in the table and automatically match the size (based on the anchored cell). There are two specific ways to use it:

Absolute positioning

For absolute positioning, you need to specify displayMode as position, and you need to specify x and y attributes to position the container to the specified pixel position in the table (based on the upper left corner). The width and height attributes specify the pixel size of the container.

Relative positioning

For relative positioning, you need to specify displayMode as cell, the container is positioned relative to the cell, the col and row attributes are used to specify the anchored cell coordinates, the anchor attribute specifies the anchor position of the container relative to the cell, the dx and dy attributes specify the offset of the container relative to the anchored cell, and the width and height attributes specify the size of the container. The dx dy width and height attributes all support units of pixels or percentages. When the percentage is calculated relative to the size of the cell.

API

interface CustomComponentProps {
   children: React.ReactNode;
   displayMode: 'position' | 'cell'; // Positioning mode
   col?: number; // Anchored column coordinates
   row?: number; // Anchored row coordinates
   anchor?:
   | 'top-left'
   | 'top-center'
   | 'top-right'
   | 'middle-left'
   | 'middle-center'
   | 'middle-right'
   | 'bottom-left'
   | 'bottom-center'
   | 'bottom-right'; // Anchored position
   dx?: number | string; // x-direction offset
   dy?: number | string; // y-direction offset
   width?: number | string; // container width
   height?: number | string; // container height
}

Custom external component demo: custom component demo