S2

@antv/s2-react

为了满足更多的分析场景，S2 提供开箱即用的场景表组件 —— 趋势分析表。借助它，你可以非常方便的实现单元格内展示多指标的场景表格。

如图所示，该类表格的表形态特点在于可以在同一个数据单元格和列头单元格内展示多个指标数据，用于需要关注时间趋势下的数据指标，查看同环比等场景。行头可以自定义层级结构。因此有此类分析需求时，可以直接使用该组件。

注意

趋势分析表组件使用了 S2 提供的各种能力进行融合，所以建议在阅读本章前，请确保你已经阅读过以下章节：

快速上手

s2DataConfig

查看详情

s2Options

查看详情

const s2Options = {
  width: 600,
  height: 480,
  // 角头文本
  cornerText: '指标层级',
  // 条件格式
  conditions: {
    // 同环比数值映射规则
    text: [
      {
        field: 'number',
        mapping: (value, cellInfo) => {
          const { meta, colIndex } = cellInfo;
          if (
            colIndex === 0 ||
            !value ||
            !meta?.fieldValue
          ) {
            return {
              fill: '#000',
            };
          }
          return {
            fill: value > 0 ? '#FF4D4F' : '#29A294',
          };
        },
      },
    ],
  },
  style: {
    dataCell: {
      valuesCfg: {
        // 原始数据字段，用于原始数据导出和 tooltip 展示
        originalValueField: 'originalValues',
      },
    },
  },
};

import React from "react";
import { SheetComponent } from "@antv/s2-react";
import '@antv/s2-react/dist/s2-react.min.css';

const App = () => {
  return (
    <SheetComponent
      sheetType="strategy"
      dataCfg={s2DataConfig}
      options={s2Options}
    />
  )
}

配置解释

S2DataConfig 配置

1. 数据源：MultiData 配置项，一个单元格对应多条数据，分为原始数据和格式化数据

const data = {
  "measure-a": {
    values: ["1", "2"],
    originalValues: [1, 2]
  }
}

2. 行头层级结构：自定义层级结构

const fields = {
  rows: [
    {
      key: 'a-1',
      title: '节点 1',
      children: []
    }
  ]
}

3. 虚拟列：趋势分析表存在同环比指标时，会通过虚拟列来显示对应的同环比指标名称，此时，表格会显示两级列头

import { EXTRA_COLUMN_FIELD } from '@antv/s2'

const fields = {
  columns: ['date', EXTRA_COLUMN_FIELD]
}

提示

虚拟例和普通字段一样，可以自定义格式化

const s2DataConfig = {
  meta: [
    // 日期列头 格式化
    {
      field: 'date',
      name: '时间',
      formatter: (value) => `${value}年`,
    },
    // 同环比名称（虚拟列头） 格式化
    {
      field: EXTRA_COLUMN_FIELD,
      formatter: (value, data, meta) => {
        console.log(data, meta);
        return meta?.colIndex === 0 ? '自定义标题' : value;
      },
    },
  ],
};

注意

如果不涉及到原始数据复制导出类需求，可不声明 originalValues
当只有单指标，（即没有同环比）时，可不配置虚拟列 (EXTRA_COLUMN_FIELD)
列头指标顺序和单元格指标展示顺序一一对应

S2Options 配置

提示

趋势分析表会将行头布局强制置为树状模式，并且数值置于行头，即 hierarchyType: 'tree'.
可通过 s2Options.cornerText 自定义角头文本。
染色逻辑配置可以在 options.conditions 中配置，不需要指定 field 参数，用法参考字段标记目前暂时只支持文本颜色通道

CustomTreeNode

功能描述：自定义树状结构的配置，适用于透视表和明细表的自定义行列头。查看文档和示例

参数	说明	类型	默认值	必选
field	当前节点唯一标识	`string`		✓
title	当前节点展示名	`string`		✓
collapsed	节点是否收起（树状模式下，行头非叶子节点有效）	`boolean`	`false`
description	节点的额外描述信息，在对应行头的 tooltip 中展示	`string`
children	子节点	CustomTreeNode[]

CustomHeaderField

type CustomHeaderField = CustomTreeNode | string;

提示

趋势分析表的 Tooltip, 使用 S2 提供的自定义能力分别对 行头 (rowCell), 列头 (colCell), 数值 (dataCell) 进行了定制.

配置项名称	说明	类型	默认值
cell	当前单元格	`S2CellType`	✓
defaultTooltipShowOptions	默认 tooltip 展示配置	`TooltipShowOptions<ReactNode>`
label	标题	`ReactNode \| (cell: S2CellType, defaultLabel: ReactNode) => ReactNode`
showOriginalValue	是否显示原始数值（如有）	`boolean`	`false`

也可以从 @antv/s2-react 包中引入单独使用，可以根据你自己的业务进行二次封装。

import { StrategySheetRowTooltip, StrategySheetColTooltip, StrategySheetDataTooltip } from '@antv/s2-react'

const s2Options = {
  tooltip: {
    content: (cell) => <StrategySheetDataTooltip cell={cell} label={label} />
  }
}

1. 自定义标题

默认使用行头节点名字作为 Tooltip 标题，可通过 label 自定义内容的方式

// 字符串
<StrategySheetDataTooltip cell={cell} label={"自定义标题"}/>

// 自定义组件
<StrategySheetDataTooltip cell={cell} label={(cell, defaultLabel) => `${defaultLabel}（自定义标题`} />

2. 显示原始数据

开启 showOriginalValue 后，会读取当前 Tooltip 对应的 originalValues 数据（如有）, 将原始数据一同展示，即 展示值（原始值）

<StrategySheetDataTooltip cell={cell} showOriginalValue />

3. 渲染同环比额外节点

可以通过 renderDerivedValue 在自定义同环比数值，比如替换成原始值

currentValue: 当前值
originalValue: 原始值
cell: 当前 Tooltip 对应的单元格信息

<StrategySheetDataTooltip
  cell={cell}
  renderDerivedValue={(currentValue, originalValue, cell) => <span>({originalValue})</span> }
/>

配置 mini 图

在指标趋势分析场景下，通常我们希望看到数据的全局走势。走势分析不仅需要包含具体的涨跌，最好还能展示出固定时间段内的趋势图，或者指标的完成情况（进度），所以我们在表格里提供了 mini 图的绘制。为了减少对外部组件库的依赖，我们内置了一个十分轻量的，基于 @antv/g 绘制的 mini 图库，以极小的性能开销在单元格内绘制出子弹图、折线图以及柱状图, 具体请查看单元格内绘制图表章节。

如果想要更换 mini 图样式配置，可以参考主题配置

在普通透视表中使用

如果不依赖 React, 想在 @antv/s2 普通的透视表中使用 mini 图，可以参考这个示例

API

功能描述：在单元格内绘制 mini 图（支持折线图、子弹图、柱状图）. 查看文档和示例

BaseChartData

功能描述：内置折线图、柱状图数据配置项，数据格式参考 G2

参数	说明	类型	必选
type	mini 图类型	`line \| bar`	✓
encode	编码方式，声明 x 位置通道或 y 位置通道绑定的对应的列数据	`{x: string; y: string}`	✓
data	原始数据	Data[]	✓
[key: string]	其他透传字段，用于自定义单元格的定制化展示	`unknown`

BulletValue

功能描述：内置子弹图数据配置项

参数	说明	类型	必选	默认值
type	mini 图类型	`bullet`	✓	`bullet`
measure	当前指标	`number \| string`	✓
target	目标值	`number \| string`	✓
[key: string]	其他透传字段，用于自定义单元格的定制化展示	`unknown`

数据导出

查看文档和示例

@antv/s2-react

为了满足更多的分析场景，S2 提供开箱即用的场景表组件 —— 趋势分析表。借助它，你可以非常方便的实现单元格内展示多指标的场景表格。

注意

趋势分析表组件使用了 S2 提供的各种能力进行融合，所以建议在阅读本章前，请确保你已经阅读过以下章节：

快速上手

s2DataConfig

查看详情

s2Options

查看详情

const s2Options = {
  width: 600,
  height: 480,
  // 角头文本
  cornerText: '指标层级',
  // 条件格式
  conditions: {
    // 同环比数值映射规则
    text: [
      {
        field: 'number',
        mapping: (value, cellInfo) => {
          const { meta, colIndex } = cellInfo;
          if (
            colIndex === 0 ||
            !value ||
            !meta?.fieldValue
          ) {
            return {
              fill: '#000',
            };
          }
          return {
            fill: value > 0 ? '#FF4D4F' : '#29A294',
          };
        },
      },
    ],
  },
  style: {
    dataCell: {
      valuesCfg: {
        // 原始数据字段，用于原始数据导出和 tooltip 展示
        originalValueField: 'originalValues',
      },
    },
  },
};

import React from "react";
import { SheetComponent } from "@antv/s2-react";
import '@antv/s2-react/dist/s2-react.min.css';

const App = () => {
  return (
    <SheetComponent
      sheetType="strategy"
      dataCfg={s2DataConfig}
      options={s2Options}
    />
  )
}

配置解释

S2DataConfig 配置

1. 数据源：MultiData 配置项，一个单元格对应多条数据，分为原始数据和格式化数据

const data = {
  "measure-a": {
    values: ["1", "2"],
    originalValues: [1, 2]
  }
}

2. 行头层级结构：自定义层级结构

const fields = {
  rows: [
    {
      key: 'a-1',
      title: '节点 1',
      children: []
    }
  ]
}

3. 虚拟列：趋势分析表存在同环比指标时，会通过虚拟列来显示对应的同环比指标名称，此时，表格会显示两级列头

import { EXTRA_COLUMN_FIELD } from '@antv/s2'

const fields = {
  columns: ['date', EXTRA_COLUMN_FIELD]
}

提示

虚拟例和普通字段一样，可以自定义格式化

const s2DataConfig = {
  meta: [
    // 日期列头 格式化
    {
      field: 'date',
      name: '时间',
      formatter: (value) => `${value}年`,
    },
    // 同环比名称（虚拟列头） 格式化
    {
      field: EXTRA_COLUMN_FIELD,
      formatter: (value, data, meta) => {
        console.log(data, meta);
        return meta?.colIndex === 0 ? '自定义标题' : value;
      },
    },
  ],
};

注意

如果不涉及到原始数据复制导出类需求，可不声明 originalValues
当只有单指标，（即没有同环比）时，可不配置虚拟列 (EXTRA_COLUMN_FIELD)
列头指标顺序和单元格指标展示顺序一一对应

S2Options 配置

提示

趋势分析表会将行头布局强制置为树状模式，并且数值置于行头，即 hierarchyType: 'tree'.
可通过 s2Options.cornerText 自定义角头文本。
染色逻辑配置可以在 options.conditions 中配置，不需要指定 field 参数，用法参考字段标记目前暂时只支持文本颜色通道

CustomTreeNode

功能描述：自定义树状结构的配置，适用于透视表和明细表的自定义行列头。查看文档和示例

参数	说明	类型	默认值	必选
field	当前节点唯一标识	`string`		✓
title	当前节点展示名	`string`		✓
collapsed	节点是否收起（树状模式下，行头非叶子节点有效）	`boolean`	`false`
description	节点的额外描述信息，在对应行头的 tooltip 中展示	`string`
children	子节点	CustomTreeNode[]

CustomHeaderField

type CustomHeaderField = CustomTreeNode | string;

提示

趋势分析表的 Tooltip, 使用 S2 提供的自定义能力分别对 行头 (rowCell), 列头 (colCell), 数值 (dataCell) 进行了定制.

配置项名称	说明	类型	默认值
cell	当前单元格	`S2CellType`	✓
defaultTooltipShowOptions	默认 tooltip 展示配置	`TooltipShowOptions<ReactNode>`
label	标题	`ReactNode \| (cell: S2CellType, defaultLabel: ReactNode) => ReactNode`
showOriginalValue	是否显示原始数值（如有）	`boolean`	`false`

也可以从 @antv/s2-react 包中引入单独使用，可以根据你自己的业务进行二次封装。

import { StrategySheetRowTooltip, StrategySheetColTooltip, StrategySheetDataTooltip } from '@antv/s2-react'

const s2Options = {
  tooltip: {
    content: (cell) => <StrategySheetDataTooltip cell={cell} label={label} />
  }
}

1. 自定义标题

默认使用行头节点名字作为 Tooltip 标题，可通过 label 自定义内容的方式

// 字符串
<StrategySheetDataTooltip cell={cell} label={"自定义标题"}/>

// 自定义组件
<StrategySheetDataTooltip cell={cell} label={(cell, defaultLabel) => `${defaultLabel}（自定义标题`} />

2. 显示原始数据

开启 showOriginalValue 后，会读取当前 Tooltip 对应的 originalValues 数据（如有）, 将原始数据一同展示，即 展示值（原始值）

<StrategySheetDataTooltip cell={cell} showOriginalValue />

3. 渲染同环比额外节点

可以通过 renderDerivedValue 在自定义同环比数值，比如替换成原始值

currentValue: 当前值
originalValue: 原始值
cell: 当前 Tooltip 对应的单元格信息

<StrategySheetDataTooltip
  cell={cell}
  renderDerivedValue={(currentValue, originalValue, cell) => <span>({originalValue})</span> }
/>

配置 mini 图

如果想要更换 mini 图样式配置，可以参考主题配置

在普通透视表中使用

如果不依赖 React, 想在 @antv/s2 普通的透视表中使用 mini 图，可以参考这个示例

API

功能描述：在单元格内绘制 mini 图（支持折线图、子弹图、柱状图）. 查看文档和示例

BaseChartData

功能描述：内置折线图、柱状图数据配置项，数据格式参考 G2

参数	说明	类型	必选
type	mini 图类型	`line \| bar`	✓
encode	编码方式，声明 x 位置通道或 y 位置通道绑定的对应的列数据	`{x: string; y: string}`	✓
data	原始数据	Data[]	✓
[key: string]	其他透传字段，用于自定义单元格的定制化展示	`unknown`

BulletValue

功能描述：内置子弹图数据配置项

参数	说明	类型	必选	默认值
type	mini 图类型	`bullet`	✓	`bullet`
measure	当前指标	`number \| string`	✓
target	目标值	`number \| string`	✓
[key: string]	其他透传字段，用于自定义单元格的定制化展示	`unknown`

数据导出

查看文档和示例