repository·next·Indexed 23 days ago
https://github.com/antvis/s2S2 is a data-driven multi-dimensional cross-analysis table visualization library designed for high-performance rendering of large datasets. It provides official support for React and Vue 3, as well as server-side rendering (SSR) capabilities via @antv/s2-ssr for exporting sheets to PNG, JPEG, SVG, or PDF. The library includes components like SheetComponent and configuration panels such as ThemePanel, TextAlignPanel, and FrozenPanel.
S2 employs several optimization techniques to maintain smooth performance:
getFieldMeta (caching field information) and caching font width calculations.web worker to prevent blocking the main thread.Hook is a powerful extension mechanism that allows developers to rewrite or customize almost every element of an S2 pivot table. It provides hooks into the layout engine, cell rendering, and structural hierarchy. You can use it to customize corner headers, column/row headers, cell positioning, icon sets, and even the overall table framework (dividing lines, shadows, etc.). This allows for complete control over the table's visual and structural representation to meet specific product requirements.By default, S2 generates hierarchy structures from grouped data. You can override this by providing a custom tree structure to the rows or columns fields in s2DataConfig. This allows you to define a custom directory structure that works with both grid (flat) and tree layouts.
A custom tree node should follow this structure:
field: Unique identifier for the node.title: Display name for the node.description: Optional description.children: An array of child nodes (empty array if leaf node).showDefaultHeaderActionIcon) is disabled when using custom headers.The adjustTotalNodesCoordinate function uses the multipleMap to apply cell merging to summary nodes.
If a subtotal node's calculated multiple is 0, it is adjusted to the nearest non-zero parent's multiple minus the level difference. This ensures the subtotal node correctly spans the appropriate number of cells relative to its hierarchy.
// Subtotal root node if 0, change to nearest upper level multiple - level difference
if (!multiple && isSubTotal) {
let lowerLevelIndex = 1;
while (multiple < 1) {
multiple =
multipleMap[node.level - lowerLevelIndex] - lowerLevelIndex;
lowerLevelIndex++;
}
}If multipleMap = [3, 0, 0, 1] and a subtotal node appears at the second dimension:
3 at index 0).3 - 1 = 2.multipleMap for that node becomes [1, 2, 0, 1].// 小计根节点若为 0，则改为最近上级倍数 - level 差
if (!multiple && isSubTotal) {
let lowerLevelIndex = 1;
while (multiple < 1) {
multiple =
multipleMap[node.level - lowerLevelIndex] - lowerLevelIndex;
lowerLevelIndex++;
}
}A Single Audience Proportion Table (also referred to as an Audience Proportion Heatmap) is a pivot table showing the proportion of a single audience across different dimensions.
When to use: Use this to compare how a specific group is distributed across the same dimensions. For example, analyzing the scale and distribution of an audience across different age groups and job titles to identify factors that influence large or small audience sizes.
Core Concept: It focuses on the distribution of a single target group across multiple attributes to find influencing factors for audience scale.
The options prop for the Vue SheetComponent is based on S2Options, but with a specific modification for pagination. The paging configuration is designed to be compatible with ant-design-vue's paging component, allowing for transparent API transmission.
import type { Pagination, S2Options } from '@antv/s2';
import type { PaginationProps } from 'ant-design-vue';
type SheetComponentOptions = S2Options<
Element | string,
Pagination & PaginationProps
>;Dimension drill-down allows users to explore hierarchical data by digging into more detailed information across different dimensions. It is primarily used with data sources that have hierarchical relationships (e.g., moving from a Region view to a Province view, or from a Province view to a City view).
Key concepts:
Currently, S2 supports dimension drill-down in the perspective mode tree structure and row header dimension drill-down.
Use sortByMeasure to sort row or column headers based on numeric values in the intersection cells.
To sort by specific cell values, set sortFieldId to the last field of the dimension (e.g., city) and use query to specify the exact column dimensions (e.g., type and sub_type). Use a specific measure name for sortByMeasure.
To sort by subtotals or totals:
sortByMeasure to TOTAL_VALUE.province), use query to define which column dimensions are included in the calculation.city), use query to define which row dimensions are included.// Example: Sorting by detail data
{
sortFieldId: 'city',
sortByMeasure: 'number',
sortMethod: 'asc',
query: {
type: '办公用品',
sub_type: '纸张',
[EXTRA_FIELD]: 'number'
}
}
// Example: Sorting by subtotal (TOTAL_VALUE)
{
sortFieldId: 'province',
sortByMeasure: 'TOTAL_VALUE',
sortMethod: 'asc',
query: {
type: '家具',
[EXTRA_FIELD]: 'number'
}
}When working with the low-level rendering and data model, distinguish between these three terms:
Cells (including those in the Corner, Row, and Column headers) can be customized using S2's customization hooks.
defaultHide: If set, the icon is hidden by default and only appears when hovering over the corresponding cell.displayCondition: Allows for dynamic logic to determine if an icon should be rendered.Icons follow the theme's text color by default. You can override this using the fill property. To use the original colors of a multi-colored SVG (especially for online links), set fill: null.
const s2Options = {
headerActionIcons: [
{
// Set position to left and color to red
icons: [{ name: 'SortDown', position: 'left', fill: 'red' }],
belongsCell: 'colCell',
},
],
};