S2

简介

通过表格交互透出表格信息以及部分分析功能

注意事项

WARNING

基础版本 (@antv/s2) 中只保留了 tooltip 的核心显隐逻辑，提供相应数据，和排序 API, 不渲染内容.

React (@antv/s2-react) 版本和 Vue3 (@antv/s2-vue) 版本中通过自定义 Tooltip 类的方式渲染 tooltip 的内容，包括 排序下拉菜单, 单元格选中信息汇总, 列头隐藏操作项按钮 等。

查看 React 版本的具体实现和 Vue3 版本的具体实现

如果您有 tooltip 的需求，您可以直接使用开箱即用的 @antv/s2-react @antv/s2-vue, 免去你二次封装，使用更加方便。
如果您不希望依赖框架，或者希望在 Vue, Angular 框架中使用 tooltip, 请参考自定义 Tooltip 类章节和以下示例。
别忘了引入样式。

// @antv/s2
import "@antv/s2/dist/s2.min.css";
// @antv/s2-react
import "@antv/s2-react/dist/s2-react.min.css";
// @antv/s2-vue
import "@antv/s2-vue/dist/s2-vue.min.css";

使用

在 s2Options 中配置 tooltip 字段，默认作用于所有单元格。

const s2Options = {
  tooltip: {}
};

还可以对不同类型的单元格单独配置：

cornerCell: 角头单元格
rowCell: 行头单元格
colCell: 列头单元格
dataCell: 数值单元格

const s2Options = {
  tooltip: {
    cornerCell: {},
    rowCell: {},
    colCell: {},
    dataCell: {},
  }
};

显示配置项

通过配置 showTooltip 字段控制 Tooltip 的显示，默认为 false.

const s2Options = {
  tooltip: {
    enable: true,
    rowCell: {
      // 单独设置行头不显示
      enable: false,
    }
  }
};

操作配置项 @antv/s2-react @antv/s2-vue

通过配置 operation 字段在 Tooltip 上增加操作项, 支持自定义。

const s2Options = {
  tooltip: {
    operation: {
      hiddenColumns: true, //开启隐藏列（叶子节点有效）
    },
  }
};

超出指定区域自动调整位置

通过配置 autoAdjustBoundary 字段开启：

container : tooltip 超出表格容器范围时，自动调整位置，始终在表格内显示
body : tooltip 超出浏览器窗口可视范围时，自动调整位置，始终在可视范围内显示
null : 关闭自动调整

const s2Options = {
  tooltip: {
    autoAdjustBoundary: "container" // 默认 "body"
  }
};

自定义

在基础类中使用 @antv/s2

对于 @antv/s2 类的使用方式：tooltip 内容可以是任意 dom 节点或者 字符串 (innerHTML).

WARNING

请注意 XSS 过滤！

const content = document.createElement('div')
content.innerHTML = '我是自定义内容'

const s2Options = {
  tooltip: {
    content,
    // content: '<div>我是字符串</div>'
  },
};

const s2Options = {
  tooltip: {
    content: `
      <div>
        <div>我是自定义内容</div>
        <p>我也是是自定义内容</p>
      </div>
    `
  },
};

或者是手动调用：

const content = document.createElement('div')
content.innerHTML = '我是自定义内容'

s2.showTooltip({
  position: {},
  content
})

s2.showTooltip({
  position: {},
  content: `
    <div>
      <div>我是自定义内容</div>
      <p>我也是是自定义内容</p>
    </div>
  `
})

在 React 中使用 @antv/s2-react

对于 @antv/s2-react 组件的使用方式：tooltip 内容可以是任意的 jsx 元素

const content = (
  <div>
    <span>我是自定义内容</span>
  </div>
)

const s2Options = {
  tooltip: {
    content,
  },
};

同时 content 还支持回调的方式，可以根据当前单元格信息和默认 tooltip 的详细信息，灵活的自定义内容

const TooltipContent = (props) => <div>...</div>

const s2Options = {
  tooltip: {
    content: (cell, defaultTooltipShowOptions) => {
      console.log('当前单元格：', cell)
      console.log('默认 tooltip 详细信息：', defaultTooltipShowOptions)
      return <TooltipContent cell={ cell } detail={ detail } />
    },
  },
};

如果需要使用默认 Tooltip, 返回 null 即可

const s2Options = {
  tooltip: {
    content: () => {
      return null
    },
  },
};

1. 配置级

对不同的单元格进行配置时，tooltip.content 的优先级小于 rowCell.content, colCell.content, dataCell.content, cornerCell.content

const TooltipContent = (
  <div>content</div>
);

const RowCellTooltipContent = (
  <div>rowCellTooltip</div>
);

const ColCellTooltipContent = (
  <div>colCellTooltip</div>
);

const DataCellTooltipContent = (
  <div>dataTooltip</div>
);

const s2Options = {
  tooltip: {
    content: TooltipContent,
    rowCell: {
      content: RowCellTooltipContent,
    },
    colCell: {
      content: ColCellTooltipContent
    },
    dataCell: {
      content: DataCellTooltipContent
    }
  },
};

2. 方法级

通过表格实例可以手动显示 tooltip

const TooltipContent = () => (
  <div>content</div>
);

s2.showTooltip({
  content: <TooltipContent />
})

// 或者 s2.tooltip.show({ content: <TooltipContent/> })

3. 内容显示优先级

方法调用 > 单元格配置 > 基本配置

除了默认提供的操作项，还可以配置 operation.menu 自定义操作项，支持嵌套，也可以监听各自的 onClick 点击事件，可以拿到当前 tooltip 对应的菜单项信息以及单元格信息.

注意

在 @antv/s2-react 中，默认提供菜单配置 (props), 需要通过 render 显示的指定操作项菜单组件，如：Ant Design Menu 组件, 可以根据项目中实际使用的 antd@v4 或 antd@v5 不同版本，对使用方式进行调整。

import { Menu } from 'antd';

const s2Options = {
  tooltip: {
    operation: {
      menu: {
        render: (props) => <Menu {...props} />
      }
    }
  }
}

菜单配置如下：

import { Menu } from 'antd';
import { PlusCircleFilled } from '@ant-design/icons';

const s2Options = {
  tooltip: {
    operation: {
      menu: {
        render: (props) => <Menu {...props} />,
        onClick: (info, cell) => {
          console.log('菜单项点击：', info, cell);
        },
        items: [
          {
            key: 'custom-a',
            label: '操作 1',
            // 图标可以是内置的 icon
            icon: 'Trend',
            onClick: (info, cell) => {
              console.log('操作 1 点击');
              console.log('tooltip 对应的单元格：', info, cell)
            },
            children: [{
              key: 'custom-a-a',
              label: '操作 1-1',
              // 也可以是 ReactNode
              icon: <PlusCircleFilled />,
              onClick: (info, cell) => {
                console.log('操作 1-1 点击', info, cell);
              },
            }]
          },
          {
            key: 'custom-b',
            label: '操作 2',
            icon: 'EyeOutlined',
            onClick: (info, cell) => {
              console.log('操作 2 点击', info, cell);
            },
          },
        ],
      }
    },
  },
};

还可以通过 visible 参数控制当前操作项是否显示，支持传入一个回调，可以根据当前单元格信息动态显示

const s2Options = {
  tooltip: {
    operation: {
      menu: {
        items: [
          {
            key: 'custom-a',
            label: '操作 1',
            icon: 'Trend',
            visible: false,
          },
          {
            key: 'custom-b',
            label: '操作 2',
            icon: 'EyeOutlined',
            visible: (cell) => {
              // 根据单元格信息动态显示，如：叶子节点不显示
              const meta = cell.getMeta()
              return meta.isLeaf
            },
          },
        ],
      }
    },
  },
};

通过实例方法调用同理，查看更多配置

s2.showTooltip({
  options: {
    operator: {
      menu: {
        items: [
          {
            key: 'custom-a',
            label: '操作 1',
            icon: 'Trend',
            onClick: (info, cell) => {
              console.log('操作 1 点击：', info, cell);
            },
          }
        ],
      }
    },
  }
})

如果使用的是 @antv/s2-react, 那么 label 和 icon 还支持任意 ReactNode

import { StarOutlined } from '@ant-design/icons';

const s2Options = {
  tooltip: {
    operation: {
      menu: {
        items: [
          {
            key: 'custom-a',
            label: <div>操作 1</div>,
            icon: <StarOutlined />,
          }
        ]
      }
    },
  },
};

默认挂载在 body 上，可自定义挂载位置

<div class="container"/>

const s2Options = {
  tooltip: {
    getContainer: () => document.querySelector('.container')
  }
}

在 tooltip 容器中添加额外的 style 样式和 class 类名，可以更方便的覆盖样式

const s2Options = {
  tooltip: {
    style: {
      fontSize: '20px'
    },
    className: 'test'
  }
};

preview

除了上面讲到的 自定义 Tooltip 内容 外，你还可以 自定义 Tooltip 类 与任意框架 (Vue, Angular, React) 结合

继承 BaseTooltip 基类，可重写 显示 (show), 隐藏 (hide), 销毁 (destroy) 等方法，结合 this.spreadsheet 实例，来实现满足你业务的 tooltip, 也可以重写 renderContent 方法，渲染你封装的任意组件

import { BaseTooltip, SpreadSheet } from '@antv/s2';
// 引入 `tooltip` 样式文件
import "@antv/s2/dist/s2.min.css";

export class CustomTooltip extends BaseTooltip {
  constructor(spreadsheet: SpreadSheet) {
    super(spreadsheet);
  }

  renderContent() {
  }

  clearContent() {
  }

  show(showOptions) {
    console.log(this.spreadsheet)
  }

  hide() {
  }

  destroy() {
  }
}

覆盖默认，使用你自定义的 Tooltip

const s2Options = {
  tooltip: {
    enable: true,
    render: (spreadsheet: SpreadSheet) => new CustomTooltip(spreadsheet),
  },
}

在 tooltip 开启前提下的默认情况：

行列头点击时显示 tooltip, 单元格文字被省略时悬停显示 tooltip
数值单元格悬停超过 800ms 显示 tooltip

比如想自定义成鼠标悬停行头时显示 tooltip, 可通过自定义交互详情, 监听行头单元格的交互事件 S2Event.ROW_CELL_HOVER . 示例

import { BaseEvent, S2Event } from '@antv/s2';

class RowHoverInteraction extends BaseEvent {
  bindEvents() {
    this.spreadsheet.on(S2Event.ROW_CELL_HOVER, (event) => {
      this.spreadsheet.tooltip.show({
        position: { x: 0, y: 0 },
        content: "..."
      })
    })
  }
}

const s2Options = {
  tooltip: {
    enable: true,
  },
  interaction: {
    customInteractions: [
      {
        key: 'RowHoverInteraction',
        interaction: RowHoverInteraction,
      },
    ],
  }
};

如果使用的是 React 组件，也可以使用单元格回调函数来进行自定义。示例

const CustomColCellTooltip = () => <div>col cell tooltip</div>;

const onRowCellHover = ({ event, viewMeta }) => {
  viewMeta.spreadsheet.tooltip.show({
    position: {
      x: event.clientX,
      y: event.clientY,
    },
    content: <CustomRowCellTooltip/>,
  });
};

<SheetComponent onRowCellHover={ onRowCellHover }/>

在 Vue3 中自定义

在 Vue3 中可以通过两种方式自定义内容。

`createVNode` 自定义类的方式（推荐）

// TooltipContent.vue

<template>
  <div>我是自定义 tooltip 内容</div>
  <p>当前值：{{ meta?.label ?? meta?.fieldValue}} </p>
</template>

<script lang="ts">
  import { defineComponent } from 'vue';

  export default defineComponent({
    name: 'TooltipContent',
    props: [ 'meta' ]
  });
</script>

import { defineCustomElement, render, createVNode } from "vue";
import { BaseTooltip, PivotSheet } from "@antv/s2";
import TooltipContent from "./TooltipContent.vue";
import "@antv/s2/dist/s2.min.css";

class CustomTooltip extends BaseTooltip {
  constructor(spreadsheet) {
    super(spreadsheet);
  }

  renderContent() {
    const cell = this.spreadsheet.getCell(this.options.event?.target);
    const meta = cell?.getMeta();

    // 使用 Vue 提供的 `createVNode` 方法将组件渲染成虚拟 DOM
    const tooltipVNode = createVNode(TooltipContent, { meta });
    // 使用  `render` 函数将其挂载在 tooltip 容器上
    render(tooltipVNode, this.container);
  }
}

`defineCustomElement` 自定义内容的方式不推荐

注意，customElements 不能重复注册，否则浏览器会报错

import { defineCustomElement } from "vue";

// 将 Vue 组件解析成 Web Component
const VueTooltipContent = defineCustomElement({
  props: [ "meta" ],
  template: `
    <div>我是自定义 Tooltip 内容</div>
    <p>当前值：{{ meta?.label ?? meta?.fieldValue }}</p>
  `
});

// 注册一个 Web Component
customElements.define("vue-tooltip-content", VueTooltipContent);

const s2Options = {
  tooltip: {
    content: (cell, defaultTooltipShowOptions) => {
      const meta = cell.getMeta();
      // 替换 Tooltip 内容
      return new VueTooltipContent({ meta });
    },
  },
};

重写展示方法

除了上面说到的 自定义 Tooltip 类 自定义展示方法外，也可以修改表格实例上 Tooltip 的方法 spreadsheet.showTooltip() 。了解如何获取表格实例？

// options 配置 tooltip 显示
tooltip: {
  enable: true,
}

<SheetComponent
  onMounted={ (instance) => {
    instance.showTooltip = (tooltipOptions) => {
      // 可自定义这里的 tooltipOptions
      instance.tooltip.show(tooltipOptions);
    };
  } }
  ...
/>;

可自定义显示内容

以下所有显示内容都可覆盖所有单元格和事件，自定义数据具体细节可查看 TooltipShowOptions

显示位置 (position)

instance.showTooltip = (tooltipOptions) => {
    const { position } = tooltipOptions;
    instance.tooltip.show({ ...tooltipOptions, position: { x: position.x + 1, y: position.y + 1 } });
  };

展示层数据 (data)

名称

当前单元格名称，一般只有单元格中文案被省略才会显示

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const name = `${data.name} - 测试`;
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, name: data.name ? name : '' } });
};

提示

当前单元格提示信息

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const tips = '说明：这是个说明';
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, tips } });
};

所选项统计列表（ summaries ）

所选项统计列表，主要按度量值区分，具体详情可查看 TooltipSummaryOptions

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const customSummaries = (data.summaries || []).map((item) => {
    return { ...item, name: `${item.name} - 测试` };
  });
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, summaries: customSummaries } });
};

轴列表（ headInfo ）

轴列表，在数据单元格中显示 行/列头 名称，具体详情可查看 TooltipHeadInfo

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const { cols = [], rows = [] } = data.headInfo || {};
  const customCols = cols.map(item=> {
    return {...item, value: `${item.value} - 测试`}
  });
  instance.tooltip.show({
    ...tooltipOptions,
    data: {
      ...data,
      headInfo: { rows, cols: customCols }
    }
  });
};

数据点明细信息（ details ）

数据点明细信息，即当前单元格的数据信息，具体详情可查看 ListItem

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const customDetails = (data.details || []).map((item) => {
    return { name: `${item.name} - 测试`, value: `${item.value} - w` };
  });
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, details: customDetails } });
};

底部提示信息（ infos ）

底部提示信息，一般可用于快捷键操作提示

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const infos = '按住 Cmd/Ctrl 或框选，查看多个数据点';
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, infos } });
};

部分配置 ( options )

tooltip 部分配置，具体细节可查看 TooltipOptions

操作栏（ operator ）

可操作配置，具体细节参考 TooltipOperatorOptions

instance.showTooltip = (tooltipOptions) => {
  const { options } = tooltipOptions;
  const customOperator = {
    menu: {
      onClick: ({ key }) => {
        console.log('任意菜单项点击', key);
      },
      items: [
        {
          key: 'trend',
          icon: 'trend',
          label: '趋势',
          onClick: (info, cell) => {
            console.log('当前菜单项点击：', info, cell)
          }
        },
      ],
    }
  };
  instance.tooltip.show({ ...tooltipOptions, options: { ...options, operator: customOperator } });
};

简介

通过表格交互透出表格信息以及部分分析功能

注意事项

WARNING

基础版本 (@antv/s2) 中只保留了 tooltip 的核心显隐逻辑，提供相应数据，和排序 API, 不渲染内容.

查看 React 版本的具体实现和 Vue3 版本的具体实现

如果您有 tooltip 的需求，您可以直接使用开箱即用的 @antv/s2-react @antv/s2-vue, 免去你二次封装，使用更加方便。
如果您不希望依赖框架，或者希望在 Vue, Angular 框架中使用 tooltip, 请参考自定义 Tooltip 类章节和以下示例。
别忘了引入样式。

// @antv/s2
import "@antv/s2/dist/s2.min.css";
// @antv/s2-react
import "@antv/s2-react/dist/s2-react.min.css";
// @antv/s2-vue
import "@antv/s2-vue/dist/s2-vue.min.css";

使用

在 s2Options 中配置 tooltip 字段，默认作用于所有单元格。

const s2Options = {
  tooltip: {}
};

还可以对不同类型的单元格单独配置：

cornerCell: 角头单元格
rowCell: 行头单元格
colCell: 列头单元格
dataCell: 数值单元格

const s2Options = {
  tooltip: {
    cornerCell: {},
    rowCell: {},
    colCell: {},
    dataCell: {},
  }
};

显示配置项

通过配置 showTooltip 字段控制 Tooltip 的显示，默认为 false.

const s2Options = {
  tooltip: {
    enable: true,
    rowCell: {
      // 单独设置行头不显示
      enable: false,
    }
  }
};

操作配置项 @antv/s2-react @antv/s2-vue

通过配置 operation 字段在 Tooltip 上增加操作项, 支持自定义。

const s2Options = {
  tooltip: {
    operation: {
      hiddenColumns: true, //开启隐藏列（叶子节点有效）
    },
  }
};

超出指定区域自动调整位置

通过配置 autoAdjustBoundary 字段开启：

container : tooltip 超出表格容器范围时，自动调整位置，始终在表格内显示
body : tooltip 超出浏览器窗口可视范围时，自动调整位置，始终在可视范围内显示
null : 关闭自动调整

const s2Options = {
  tooltip: {
    autoAdjustBoundary: "container" // 默认 "body"
  }
};

自定义

在基础类中使用 @antv/s2

对于 @antv/s2 类的使用方式：tooltip 内容可以是任意 dom 节点或者 字符串 (innerHTML).

WARNING

请注意 XSS 过滤！

const content = document.createElement('div')
content.innerHTML = '我是自定义内容'

const s2Options = {
  tooltip: {
    content,
    // content: '<div>我是字符串</div>'
  },
};

const s2Options = {
  tooltip: {
    content: `
      <div>
        <div>我是自定义内容</div>
        <p>我也是是自定义内容</p>
      </div>
    `
  },
};

或者是手动调用：

const content = document.createElement('div')
content.innerHTML = '我是自定义内容'

s2.showTooltip({
  position: {},
  content
})

s2.showTooltip({
  position: {},
  content: `
    <div>
      <div>我是自定义内容</div>
      <p>我也是是自定义内容</p>
    </div>
  `
})

在 React 中使用 @antv/s2-react

对于 @antv/s2-react 组件的使用方式：tooltip 内容可以是任意的 jsx 元素

const content = (
  <div>
    <span>我是自定义内容</span>
  </div>
)

const s2Options = {
  tooltip: {
    content,
  },
};

同时 content 还支持回调的方式，可以根据当前单元格信息和默认 tooltip 的详细信息，灵活的自定义内容

const TooltipContent = (props) => <div>...</div>

const s2Options = {
  tooltip: {
    content: (cell, defaultTooltipShowOptions) => {
      console.log('当前单元格：', cell)
      console.log('默认 tooltip 详细信息：', defaultTooltipShowOptions)
      return <TooltipContent cell={ cell } detail={ detail } />
    },
  },
};

如果需要使用默认 Tooltip, 返回 null 即可

const s2Options = {
  tooltip: {
    content: () => {
      return null
    },
  },
};

1. 配置级

对不同的单元格进行配置时，tooltip.content 的优先级小于 rowCell.content, colCell.content, dataCell.content, cornerCell.content

const TooltipContent = (
  <div>content</div>
);

const RowCellTooltipContent = (
  <div>rowCellTooltip</div>
);

const ColCellTooltipContent = (
  <div>colCellTooltip</div>
);

const DataCellTooltipContent = (
  <div>dataTooltip</div>
);

const s2Options = {
  tooltip: {
    content: TooltipContent,
    rowCell: {
      content: RowCellTooltipContent,
    },
    colCell: {
      content: ColCellTooltipContent
    },
    dataCell: {
      content: DataCellTooltipContent
    }
  },
};

2. 方法级

通过表格实例可以手动显示 tooltip

const TooltipContent = () => (
  <div>content</div>
);

s2.showTooltip({
  content: <TooltipContent />
})

// 或者 s2.tooltip.show({ content: <TooltipContent/> })

3. 内容显示优先级

方法调用 > 单元格配置 > 基本配置

注意

import { Menu } from 'antd';

const s2Options = {
  tooltip: {
    operation: {
      menu: {
        render: (props) => <Menu {...props} />
      }
    }
  }
}

菜单配置如下：

import { Menu } from 'antd';
import { PlusCircleFilled } from '@ant-design/icons';

const s2Options = {
  tooltip: {
    operation: {
      menu: {
        render: (props) => <Menu {...props} />,
        onClick: (info, cell) => {
          console.log('菜单项点击：', info, cell);
        },
        items: [
          {
            key: 'custom-a',
            label: '操作 1',
            // 图标可以是内置的 icon
            icon: 'Trend',
            onClick: (info, cell) => {
              console.log('操作 1 点击');
              console.log('tooltip 对应的单元格：', info, cell)
            },
            children: [{
              key: 'custom-a-a',
              label: '操作 1-1',
              // 也可以是 ReactNode
              icon: <PlusCircleFilled />,
              onClick: (info, cell) => {
                console.log('操作 1-1 点击', info, cell);
              },
            }]
          },
          {
            key: 'custom-b',
            label: '操作 2',
            icon: 'EyeOutlined',
            onClick: (info, cell) => {
              console.log('操作 2 点击', info, cell);
            },
          },
        ],
      }
    },
  },
};

还可以通过 visible 参数控制当前操作项是否显示，支持传入一个回调，可以根据当前单元格信息动态显示

const s2Options = {
  tooltip: {
    operation: {
      menu: {
        items: [
          {
            key: 'custom-a',
            label: '操作 1',
            icon: 'Trend',
            visible: false,
          },
          {
            key: 'custom-b',
            label: '操作 2',
            icon: 'EyeOutlined',
            visible: (cell) => {
              // 根据单元格信息动态显示，如：叶子节点不显示
              const meta = cell.getMeta()
              return meta.isLeaf
            },
          },
        ],
      }
    },
  },
};

通过实例方法调用同理，查看更多配置

s2.showTooltip({
  options: {
    operator: {
      menu: {
        items: [
          {
            key: 'custom-a',
            label: '操作 1',
            icon: 'Trend',
            onClick: (info, cell) => {
              console.log('操作 1 点击：', info, cell);
            },
          }
        ],
      }
    },
  }
})

如果使用的是 @antv/s2-react, 那么 label 和 icon 还支持任意 ReactNode

import { StarOutlined } from '@ant-design/icons';

const s2Options = {
  tooltip: {
    operation: {
      menu: {
        items: [
          {
            key: 'custom-a',
            label: <div>操作 1</div>,
            icon: <StarOutlined />,
          }
        ]
      }
    },
  },
};

默认挂载在 body 上，可自定义挂载位置

<div class="container"/>

const s2Options = {
  tooltip: {
    getContainer: () => document.querySelector('.container')
  }
}

在 tooltip 容器中添加额外的 style 样式和 class 类名，可以更方便的覆盖样式

const s2Options = {
  tooltip: {
    style: {
      fontSize: '20px'
    },
    className: 'test'
  }
};

preview

除了上面讲到的 自定义 Tooltip 内容 外，你还可以 自定义 Tooltip 类 与任意框架 (Vue, Angular, React) 结合

import { BaseTooltip, SpreadSheet } from '@antv/s2';
// 引入 `tooltip` 样式文件
import "@antv/s2/dist/s2.min.css";

export class CustomTooltip extends BaseTooltip {
  constructor(spreadsheet: SpreadSheet) {
    super(spreadsheet);
  }

  renderContent() {
  }

  clearContent() {
  }

  show(showOptions) {
    console.log(this.spreadsheet)
  }

  hide() {
  }

  destroy() {
  }
}

覆盖默认，使用你自定义的 Tooltip

const s2Options = {
  tooltip: {
    enable: true,
    render: (spreadsheet: SpreadSheet) => new CustomTooltip(spreadsheet),
  },
}

在 tooltip 开启前提下的默认情况：

行列头点击时显示 tooltip, 单元格文字被省略时悬停显示 tooltip
数值单元格悬停超过 800ms 显示 tooltip

比如想自定义成鼠标悬停行头时显示 tooltip, 可通过自定义交互详情, 监听行头单元格的交互事件 S2Event.ROW_CELL_HOVER . 示例

import { BaseEvent, S2Event } from '@antv/s2';

class RowHoverInteraction extends BaseEvent {
  bindEvents() {
    this.spreadsheet.on(S2Event.ROW_CELL_HOVER, (event) => {
      this.spreadsheet.tooltip.show({
        position: { x: 0, y: 0 },
        content: "..."
      })
    })
  }
}

const s2Options = {
  tooltip: {
    enable: true,
  },
  interaction: {
    customInteractions: [
      {
        key: 'RowHoverInteraction',
        interaction: RowHoverInteraction,
      },
    ],
  }
};

如果使用的是 React 组件，也可以使用单元格回调函数来进行自定义。示例

const CustomColCellTooltip = () => <div>col cell tooltip</div>;

const onRowCellHover = ({ event, viewMeta }) => {
  viewMeta.spreadsheet.tooltip.show({
    position: {
      x: event.clientX,
      y: event.clientY,
    },
    content: <CustomRowCellTooltip/>,
  });
};

<SheetComponent onRowCellHover={ onRowCellHover }/>

在 Vue3 中自定义

在 Vue3 中可以通过两种方式自定义内容。

`createVNode` 自定义类的方式（推荐）

// TooltipContent.vue

<template>
  <div>我是自定义 tooltip 内容</div>
  <p>当前值：{{ meta?.label ?? meta?.fieldValue}} </p>
</template>

<script lang="ts">
  import { defineComponent } from 'vue';

  export default defineComponent({
    name: 'TooltipContent',
    props: [ 'meta' ]
  });
</script>

import { defineCustomElement, render, createVNode } from "vue";
import { BaseTooltip, PivotSheet } from "@antv/s2";
import TooltipContent from "./TooltipContent.vue";
import "@antv/s2/dist/s2.min.css";

class CustomTooltip extends BaseTooltip {
  constructor(spreadsheet) {
    super(spreadsheet);
  }

  renderContent() {
    const cell = this.spreadsheet.getCell(this.options.event?.target);
    const meta = cell?.getMeta();

    // 使用 Vue 提供的 `createVNode` 方法将组件渲染成虚拟 DOM
    const tooltipVNode = createVNode(TooltipContent, { meta });
    // 使用  `render` 函数将其挂载在 tooltip 容器上
    render(tooltipVNode, this.container);
  }
}

`defineCustomElement` 自定义内容的方式不推荐

注意，customElements 不能重复注册，否则浏览器会报错

import { defineCustomElement } from "vue";

// 将 Vue 组件解析成 Web Component
const VueTooltipContent = defineCustomElement({
  props: [ "meta" ],
  template: `
    <div>我是自定义 Tooltip 内容</div>
    <p>当前值：{{ meta?.label ?? meta?.fieldValue }}</p>
  `
});

// 注册一个 Web Component
customElements.define("vue-tooltip-content", VueTooltipContent);

const s2Options = {
  tooltip: {
    content: (cell, defaultTooltipShowOptions) => {
      const meta = cell.getMeta();
      // 替换 Tooltip 内容
      return new VueTooltipContent({ meta });
    },
  },
};

重写展示方法

除了上面说到的 自定义 Tooltip 类 自定义展示方法外，也可以修改表格实例上 Tooltip 的方法 spreadsheet.showTooltip() 。了解如何获取表格实例？

// options 配置 tooltip 显示
tooltip: {
  enable: true,
}

<SheetComponent
  onMounted={ (instance) => {
    instance.showTooltip = (tooltipOptions) => {
      // 可自定义这里的 tooltipOptions
      instance.tooltip.show(tooltipOptions);
    };
  } }
  ...
/>;

可自定义显示内容

以下所有显示内容都可覆盖所有单元格和事件，自定义数据具体细节可查看 TooltipShowOptions

显示位置 (position)

instance.showTooltip = (tooltipOptions) => {
    const { position } = tooltipOptions;
    instance.tooltip.show({ ...tooltipOptions, position: { x: position.x + 1, y: position.y + 1 } });
  };

展示层数据 (data)

名称

当前单元格名称，一般只有单元格中文案被省略才会显示

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const name = `${data.name} - 测试`;
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, name: data.name ? name : '' } });
};

提示

当前单元格提示信息

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const tips = '说明：这是个说明';
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, tips } });
};

所选项统计列表（ summaries ）

所选项统计列表，主要按度量值区分，具体详情可查看 TooltipSummaryOptions

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const customSummaries = (data.summaries || []).map((item) => {
    return { ...item, name: `${item.name} - 测试` };
  });
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, summaries: customSummaries } });
};

轴列表（ headInfo ）

轴列表，在数据单元格中显示 行/列头 名称，具体详情可查看 TooltipHeadInfo

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const { cols = [], rows = [] } = data.headInfo || {};
  const customCols = cols.map(item=> {
    return {...item, value: `${item.value} - 测试`}
  });
  instance.tooltip.show({
    ...tooltipOptions,
    data: {
      ...data,
      headInfo: { rows, cols: customCols }
    }
  });
};

数据点明细信息（ details ）

数据点明细信息，即当前单元格的数据信息，具体详情可查看 ListItem

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const customDetails = (data.details || []).map((item) => {
    return { name: `${item.name} - 测试`, value: `${item.value} - w` };
  });
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, details: customDetails } });
};

底部提示信息（ infos ）

底部提示信息，一般可用于快捷键操作提示

instance.showTooltip = (tooltipOptions) => {
  const { data } = tooltipOptions;
  const infos = '按住 Cmd/Ctrl 或框选，查看多个数据点';
  instance.tooltip.show({ ...tooltipOptions, data: { ...data, infos } });
};

部分配置 ( options )

tooltip 部分配置，具体细节可查看 TooltipOptions

操作栏（ operator ）

可操作配置，具体细节参考 TooltipOperatorOptions

instance.showTooltip = (tooltipOptions) => {
  const { options } = tooltipOptions;
  const customOperator = {
    menu: {
      onClick: ({ key }) => {
        console.log('任意菜单项点击', key);
      },
      items: [
        {
          key: 'trend',
          icon: 'trend',
          label: '趋势',
          onClick: (info, cell) => {
            console.log('当前菜单项点击：', info, cell)
          }
        },
      ],
    }
  };
  instance.tooltip.show({ ...tooltipOptions, options: { ...options, operator: customOperator } });
};

Tooltip

Tooltip

简介

注意事项

WARNING

使用

显示配置项

操作配置项 @antv/s2-react @antv/s2-vue

超出指定区域自动调整位置

自定义

自定义 Tooltip 内容

在基础类中使用 @antv/s2

WARNING

在 React 中使用 @antv/s2-react

1. 配置级

2. 方法级

3. 内容显示优先级

自定义 Tooltip 操作项 @antv/s2-react @antv/s2-vue

注意

自定义 Tooltip 挂载节点

自定义 Tooltip 容器样式

自定义 Tooltip 类

自定义 Tooltip 显示时机

在 Vue3 中自定义

createVNode 自定义类的方式（推荐）

defineCustomElement 自定义内容的方式 不推荐

重写展示方法

可自定义显示内容

简介

注意事项

WARNING

使用

显示配置项

操作配置项 @antv/s2-react @antv/s2-vue

超出指定区域自动调整位置

自定义

自定义 Tooltip 内容

在基础类中使用 @antv/s2

WARNING

在 React 中使用 @antv/s2-react

1. 配置级

2. 方法级

3. 内容显示优先级

自定义 Tooltip 操作项 @antv/s2-react @antv/s2-vue

注意

自定义 Tooltip 挂载节点

自定义 Tooltip 容器样式

自定义 Tooltip 类

自定义 Tooltip 显示时机

在 Vue3 中自定义

createVNode 自定义类的方式（推荐）

defineCustomElement 自定义内容的方式 不推荐

重写展示方法

可自定义显示内容

`createVNode` 自定义类的方式（推荐）

`defineCustomElement` 自定义内容的方式不推荐

`createVNode` 自定义类的方式（推荐）

`defineCustomElement` 自定义内容的方式不推荐