${title}
${items.map(({ name, value, color }) => `
${name}：
${value}
`).join('')}
`;
},
},
});
```
## 多系列共享 tooltip（groupKey）
```javascript
// 多折线图，鼠标悬停时同时显示所有系列的值
chart.options({
type: 'view',
data,
children: [
{
type: 'line',
encode: { x: 'month', y: 'value', color: 'type' },
tooltip: {
// groupKey：按哪个字段合并多系列的 tooltip
// 默认按 x 值合并，所有系列在同一 x 处的点显示在一个 tooltip 中
title: 'month',
},
},
],
interaction: [{ type: 'tooltip', shared: true }], // shared: true 显示共享 tooltip
});
```
## 完整配置项
```javascript
chart.options({
type: 'line',
data,
encode: { x: 'month', y: 'value' },
tooltip: {
// 标题
title: 'month', // 字段名 或 函数 (d) => string
// 显示项
items: [
{
field: 'value', // 数据字段名
channel: 'y', // 或者用通道名（'x' | 'y' | 'color' 等）
name: '销售额', // 显示名称（覆盖默认）
color: '#1890ff', // 色块颜色
// valueFormatter 接受：
// 函数 (value) => string ← 需要拼接单位时必须用这种形式
// d3-format 字符串 '.2f' ← 只格式化数字本身，不支持追加文字
valueFormatter: (v) => `${v} 万元`, // ✅ 函数形式，可拼接单位
// valueFormatter: '.2f', // ✅ d3-format，仅格式化数字
// valueFormatter: '.0f 米', // ❌ 错误！d3-format 后不能追加文字
},
],
// 渲染
render: (event, { title, items }) => `...
`, // 完全自定义 HTML
// 触发方式
// 在 interaction 中配置
},
// tooltip 交互（可补充配置）
interaction: [
{
type: 'tooltip',
shared: true, // 多 Mark 共享 tooltip
crosshairs: true, // 显示十字准线
},
],
});
```
## 十字准线（crosshairs）
十字准线通过 `interaction` 中的 `tooltip` 交互项配置：
```javascript
chart.options({
type: 'line',
data,
encode: { x: 'month', y: 'value' },
interaction: [
{
type: 'tooltip',
crosshairs: true, // 显示十字准线（默认开启）
crosshairsStroke: '#aaa', // 准线颜色
crosshairsLineWidth: 1, // 准线宽度
crosshairsLineDash: [4, 4], // 虚线样式
},
],
});
```
## 通过 CSS 自定义 tooltip 样式
当 `render` 函数的定制化程度不够时，可以通过 CSS 直接覆盖默认样式：
```javascript
// 方式 1：在页面全局 CSS 中覆盖
// .g2-tooltip { background: #1a1a1a; color: #fff; border-radius: 8px; }
// .g2-tooltip-title { font-size: 14px; font-weight: bold; }
// .g2-tooltip-list-item-value { color: #fadb14; }
// 方式 2：通过 interaction 的 css 参数（局部覆盖）
chart.options({
interaction: [
{
type: 'tooltip',
css: {
'.g2-tooltip': {
background: '#1a1a1a',
color: '#fff',
borderRadius: '8px',
padding: '8px 12px',
},
'.g2-tooltip-title': {
fontSize: '14px',
fontWeight: 'bold',
marginBottom: '6px',
},
'.g2-tooltip-list-item-value': {
color: '#fadb14',
},
},
},
],
});
```
**内置 CSS 类名：**
- `.g2-tooltip` — tooltip 容器
- `.g2-tooltip-title` — 标题
- `.g2-tooltip-list-item` — 单条数据项
- `.g2-tooltip-list-item-name-label` — 数据项名称
- `.g2-tooltip-list-item-value` — 数据项值
- `.g2-tooltip-list-item-marker` — 数据项颜色标记点
---
## 常见错误与修正
### 错误 1：tooltip.items 字段名与数据不匹配
```javascript
// ❌ 错误：数据字段是 'revenue' 但 items 写的是 'value'
const data = [{ month: '1月', revenue: 1200 }];
chart.options({
tooltip: {
items: [{ field: 'value' }], // ❌ 数据中没有 'value' 字段
},
});
// ✅ 正确：field 与数据字段名对应
chart.options({
tooltip: {
items: [{ field: 'revenue', name: '收入' }], // ✅
},
});
```
### 错误 2：render 函数忘记返回字符串
```javascript
// ❌ 错误：render 函数没有 return 语句
chart.options({
tooltip: {
render: (event, { title, items }) => {
const html = `