Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: 完善交互主题配置 #2344

Merged
merged 1 commit into from
Sep 9, 2023
Merged

docs: 完善交互主题配置 #2344

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions s2-site/docs/api/components/sheet-component.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,9 +96,9 @@ order: 0
| onMouseUp | 表格鼠标松开事件 | (event: CanvasEvent) => void | | |
| onSelected | 单元格选中事件 | (cells: ( [Cell](/docs/api/basic-class/base-cell)[] ) => void | | |
| onReset | 交互状态重置事件 | (event: KeyboardEvent) => void | | |
| onLinkFieldJump | 链接字段跳转事件 (cellData: @antv/s2 1.37.0 新增) | (data: { key: string; cellData: [Node](/docs/api/basic-class/node); record: [Data](/docs/api/general/S2DataConfig#data) }) => void | | |
| onLinkFieldJump | 链接字段跳转事件 (cellData: @antv/s2 1.37.0 新增） | (data: { key: string; cellData: [Node](/docs/api/basic-class/node); record: [Data](/docs/api/general/S2DataConfig#data) }) => void | | |
| onScroll | 单元格滚动事件 （含行头和数值单元格） | ({position: [CellScrollPosition](#cellscrollposition)} ) => void; | | |
| onColCellBrushSelection | 批量选中刷选范围内的列头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息（仅支持透视表） | (cells: [ColCell](/docs/api/basic-class/base-cell)[]) => void; | | |
| onColCellBrushSelection | 批量选中刷选范围内的列头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息 | (cells: [ColCell](/docs/api/basic-class/base-cell)[]) => void; | | |
| onRowCellBrushSelection | 批量选中刷选范围内的行头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息（仅支持透视表） | (cells: [RowCell](/docs/api/basic-class/base-cell)[]) => void; | | |

## SheetComponentOptions
Expand Down Expand Up @@ -218,9 +218,9 @@ type SheetComponentOptions = S2Options<
| mouseUp | 表格鼠标松开事件 | (event: CanvasEvent) => void | | |
| selected | 单元格选中事件 | ( cells: ([Cell](/docs/api/basic-class/base-cell)[] ) => void | | |
| reset | 交互状态重置事件 | (event: KeyboardEvent) => void | | |
| linkFieldJump | 链接字段跳转事件 (cellData: @antv/s2 1.37.0 新增) | (data: { key: string; cellData: [Node](/docs/api/basic-class/node); record: [Data](/docs/api/general/S2DataConfig#data) }) => void | | |
| linkFieldJump | 链接字段跳转事件 (cellData: @antv/s2 1.37.0 新增） | (data: { key: string; cellData: [Node](/docs/api/basic-class/node); record: [Data](/docs/api/general/S2DataConfig#data) }) => void | | |
| scroll | 单元格滚动事件 （含行头和数值单元格） | ({position: [CellScrollPosition](#cellscrollposition)} ) => void; | | |
| colCellBrushSelection | 批量选中刷选范围内的列头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息（仅支持透视表） | (cells: ColCell[]) => void; | | |
| colCellBrushSelection | 批量选中刷选范围内的列头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息 | (cells: ColCell[]) => void; | | |
| rowCellBrushSelection | 批量选中刷选范围内的行头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息（仅支持透视表） | (cells: RowCell[]) => void; | | |

## SheetComponentOptions
Expand Down
2 changes: 1 addition & 1 deletion s2-site/docs/api/general/S2Event.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ s2.on(S2Event.ROW_CELL_CLICK, (event) => {
| 鼠标按下 | `S2Event.COL_CELL_MOUSE_DOWN` | 列头单元格鼠标按下 |
| 鼠标移动 | `S2Event.COL_CELL_MOUSE_MOVE` | 列头单元格鼠标移动 |
| 鼠标松开 | `S2Event.COL_CELL_MOUSE_UP` | 列头单元格鼠标松开 |
| 列头刷选 | `S2Event.COL_CELL_BRUSH_SELECTION` | 批量选中刷选范围内的列头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息（仅支持透视表） |
| 列头刷选 | `S2Event.COL_CELL_BRUSH_SELECTION` | 批量选中刷选范围内的列头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息 |

### 数值单元格

Expand Down
36 changes: 35 additions & 1 deletion s2-site/docs/api/general/S2Theme.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ s2.setTheme({
| verticalBorderColorOpacity | 单元格垂直边线颜色透明度 | `number` | 1 | |
| verticalBorderWidth | 单元格垂直边线宽度 | `number` | - | |
| padding | 单元格内边距 | [Padding](#margin--padding) | - | |
| interactionState | 单元格交互态 | [InteractionStateTheme](#interactionstatetheme) | - | |
| interactionState | 单元格交互态 ([查看默认配置](https://github.com/antvis/S2/blob/master/packages/s2-core/src/theme/index.ts#L66-L107)) ([示例](/zh/examples/interaction/basic#state-theme)) | Record<[InteractionStateName](#interactionstatename), [InteractionStateTheme](#interactionstatetheme)> | - | |
| miniBarChartHeight | 单元格内条件格式-迷你条形图高度 | `number` | 12 | |
| miniBarChartFillColor | 单元格内条件格式-迷你条形图默认填充颜色 | `string` | - | |

Expand All @@ -188,12 +188,46 @@ s2.setTheme({
| size | icon 大小 | `number` | - | |
| margin | 单元格外边距 | [Margin](#margin--padding) | - | |

#### InteractionStateName

> 示例

```ts
s2.setTheme({
dataCell: {
cell: {
interactionState: {
hoverFocus: {},
selected: {},
prepareSelect: {}
}
}
}
})
```

| 状态名 | 说明 | 类型 | 默认值 | 必选 |
| ----------------- | ---------- | -------- | ------ | ---- |
| hover | 悬停 | [InteractionStateTheme](#interactionstatetheme) | | |
| hoverFocus | 悬停聚焦 | [InteractionStateTheme](#interactionstatetheme) | | |
| selected | 选中 | [InteractionStateTheme](#interactionstatetheme)| | |
| unselected | 未选中 | [InteractionStateTheme](#interactionstatetheme) | | |
| searchResult | 搜索结果 | [InteractionStateTheme](#interactionstatetheme) | | |
| highlight | 高亮 | [InteractionStateTheme](#interactionstatetheme) | | |
| prepareSelect | 预选中 | [InteractionStateTheme](#interactionstatetheme) | | |

#### InteractionStateTheme

<description> **optional** _object_ </description>

功能描述：交互通用主题

```ts
type InteractionState = {
[K in InteractionStateName]?: InteractionStateTheme;
};
```

| 参数 | 说明 | 类型 | 默认值 | 必选 |
| ----------------- | ---------- | -------- | ------ | ---- |
| backgroundColor | 背景填充色 | `string` | | |
Expand Down
4 changes: 2 additions & 2 deletions s2-site/docs/common/interaction.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ order: 5
| scrollSpeedRatio | 用于控制滚动速率，分水平和垂直两个方向，默认为 1 | [ScrollSpeedRatio](#scrollspeedratio) | | |
| autoResetSheetStyle | 用于控制点击表格外区域和按下 esc 键时是否重置交互状态 | `boolean` | `true` | |
| resize | 用于控制 resize 热区是否显示 | `boolean` \| [ResizeInteractionOptions](#resizeinteractionoptions) | `true` | |
| brushSelection | 是否允许单元格（包含行头，列头，数值单元格）刷选。行头，列头刷选只支持透视表 | `boolean` \| [BrushSelection](#brushSelection) | `true` | | 1.29.0 后支持 [BrushSelection](#brushSelection) |
| brushSelection | 是否允许单元格（包含行头，列头，数值单元格）刷选。 | `boolean` \| [BrushSelection](#brushSelection) | `true` | | 1.29.0 后支持 [BrushSelection](#brushSelection) |
| multiSelection | 是否允许多选 （包含行头，列头，数值单元格） | `boolean` | `true` | |
| rangeSelection | 是否允许区间快捷多选 | `boolean` | `true` | |
| scrollbarPosition | 用于控制滚动条展示在内容区边缘还是画布边缘 | `content \| canvas` | `content` | |
Expand Down Expand Up @@ -64,4 +64,4 @@ interface ScrollSpeedRatio {
| ----------------- | --------------------- | ----------------- | ------- | --- |
| data | 是否允许数值单元格刷选 | `boolean` | true | |
| row | 是否允许行头单元格刷选（仅支持透视表） | `boolean` | false | |
| col | 是否允许列头单元格刷选（仅支持透视表） | `boolean` | false | |
| col | 是否允许列头单元格刷选 | `boolean` | false | |
28 changes: 7 additions & 21 deletions s2-site/docs/manual/advanced/interaction/basic.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ order: 0
| 行/列头手动调整宽高 | `S2Event.LAYOUT_RESIZE` | 鼠标悬浮在行/列头单元格边缘，出现指示条和光标，按住鼠标左键拖动，调整宽高 |
| 刷选 | `S2Event.DATA_CELL_BRUSH_SELECTION` `S2Event.GLOBAL_SELECTED` | 批量选中刷选范围内的数值单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息和数量 |
| 行头刷选 | `S2Event.ROW_CELL_BRUSH_SELECTION` `S2Event.GLOBAL_SELECTED` | 批量选中刷选范围内的行头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息（仅支持透视表） |
| 列头刷选 | `S2Event.COL_CELL_BRUSH_SELECTION` `S2Event.GLOBAL_SELECTED` | 批量选中刷选范围内的列头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息（仅支持透视表） |
| 列头刷选 | `S2Event.COL_CELL_BRUSH_SELECTION` `S2Event.GLOBAL_SELECTED` | 批量选中刷选范围内的列头单元格，刷选过程中，显示刷选范围提示蒙层，刷选完成后，弹出 tooltip, 展示被刷选单元格信息 |
| 区间快捷多选 | `S2Event.GLOBAL_SELECTED` | 单选单元格 (start), 然后按住 `Shift` 再次选中一个单元格 (end), 选中两个单元格区间所有单元格 |
| 悬停 | `S2Event.GLOBAL_HOVER` | 鼠标悬停时，对应单元格高亮展示，如果是数值单元格，则默认 [十字高亮](/docs/manual/advanced/interaction/basic#行列联动高亮)，可设置 `hoverHighlight: false` 关闭 |
| 复制 | `S2Event.GLOBAL_COPIED` | 复制选中的单元格数据 |
Expand Down Expand Up @@ -229,26 +229,6 @@ const s2Options = {
};
```

:::warning{title='如何关闭悬停时出现的单元格黑色边框？'}
:::

```ts
s2.setTheme({
dataCell: {
cell: {
interactionState: {
hoverFocus: {
// 边框设置为透明
borderColor: 'transparent'
// 或者边框透明度设置为 0
// borderOpacity: 0
}
}
}
}
})
```

### 圈选

圈选又叫刷选，刷选过程中，会提示预选中的单元格，并且显示半透明的刷选蒙层，支持对 `数据单元格 (dataCell)`, `行头单元格 (rowCell)`, `列头单元格 (colCell)` 进行圈选，同时支持 `滚动圈选`, 可以用来做 `统计数据总和`, `单元格个数`, `复制选定数据` 等操作，默认开启 `数据单元格`，可配置 `brushSelection` 关闭：
Expand Down Expand Up @@ -478,6 +458,12 @@ const s2Options = {
};
```

## 调整交互主题

<Playground path='interaction/basic/demo/state-theme.ts' rid='container' height='300'></playground>

可以通过 [主题配置](https://s2.antv.antgroup.com/api/general/s2-theme#interactionstatename) 对应的 [交互主题](https://s2.antv.antgroup.com/api/general/s2-theme#interactionstatename), 调整选中/悬停/圈选等交互主题。

## 调用 API

`S2` 内置了一些交互相关的 `API`，统一挂载在 `s2.interaction` 命名空间下，你可以在拿到 [SpreadSheet 实例](/docs/api/basic-class/spreadsheet) 后调用它们来实现你的效果，比如 `选中所有单元格`, `获取列头单元格` 等常用方法，具体请查看 [Interaction 实例类](/docs/api/basic-class/interaction)
Expand Down
12 changes: 11 additions & 1 deletion s2-site/docs/manual/basic/theme.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ S2 内置 3 套主题效果：

​📊 查看更多 [主题示例](/examples/theme/default#default)。

### 自定义 schema
### 自定义 Schema

如果内置的主题不满意你的要求，那么你可以通过自定义 `schema` 的方式重写特定的配置。

Expand All @@ -128,6 +128,8 @@ s2.render(false);

<Playground path="theme/custom/demo/custom-schema.ts" rid='custom-schema'></playground>

<br/>

#### 自定义单元格对齐方式

[查看详情](https://s2.antv.antgroup.com/manual/advanced/custom/cell-align) 和 [完整 API](/api/general/s2theme#s2theme)
Expand Down Expand Up @@ -173,6 +175,14 @@ s2.setTheme({
});
```

#### 自定义交互样式

[查看文档](/manual/advanced/interaction/basic#%E8%B0%83%E6%95%B4%E4%BA%A4%E4%BA%92%E4%B8%BB%E9%A2%98) [查看示例](/zh/examples/interaction/basic#state-theme)

<Playground path='interaction/basic/demo/state-theme.ts' rid='state-theme' height='300'></playground>

<br/>

### 自定义色板

自定义 `schema` 虽然灵活，但是心智负担比较重，需要对 `schema` 的结构有比较详细的了解。因此我们还提供了自定义色板功能，此时你需要为 `setThemeCfg` 配置`palette`对象。[查看完整色板配置](/docs/api/general/S2Theme#palette)：
Expand Down
6 changes: 5 additions & 1 deletion s2-site/docs/manual/faq.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ s2.showTooltip({ ... })

![preview](https://gw.alipayobjects.com/zos/antfincdn/nDIO0OG8fv/4ff6613f-fad3-4ea6-9473-0161509f692c.png)

边框属于 `聚焦 (hoverFocus)` 交互状态的一种，可通过 [主题配置](https://s2.antv.antgroup.com/api/general/s2-theme#interactionstatetheme) 关闭
边框属于 `聚焦 (hoverFocus)` 交互状态的一种，可通过 [主题配置 - 交互通用主题](https://s2.antv.antgroup.com/api/general/s2-theme#interactionstatename) 关闭。

```ts
s2.setTheme({
Expand All @@ -244,6 +244,10 @@ s2.setTheme({
})
```

### 如何修改选中，悬停，刷选等单元格交互主题配置？

请 [查看文档](/manual/advanced/interaction/basic#%E8%B0%83%E6%95%B4%E4%BA%A4%E4%BA%92%E4%B8%BB%E9%A2%98) 和 [示例](/zh/examples/interaction/basic#state-theme)

### S2 支持对表格进行编辑吗？

请查看 [编辑模式示例](/examples/case/data-preview#excel) 和 [编辑表示例](https://s2.antv.antgroup.com/examples/react-component/sheet/#editable)
Expand Down
16 changes: 0 additions & 16 deletions s2-site/examples/interaction/basic/demo/hover.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,21 +27,5 @@ fetch(
};
const s2 = new PivotSheet(container, dataCfg, s2Options);

// 关闭悬停单元格时出现的 "黑色边框"
// s2.setTheme({
// dataCell: {
// cell: {
// interactionState: {
// hoverFocus: {
// // 边框设置为透明
// borderColor: 'transparent'
// // 或者边框透明度设置为 0
// // borderOpacity: 0
// }
// }
// }
// }
// })

s2.render();
});
8 changes: 8 additions & 0 deletions s2-site/examples/interaction/basic/demo/meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,14 @@
"en": "Trigger hover after scroll"
},
"screenshot": "https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*NbG7SakRzXUAAAAAAAAAAAAADmJ7AQ/original.gif"
},
{
"filename": "state-theme.ts",
"title": {
"zh": "交互主题配置",
"en": "Interaction state theme"
},
"screenshot": "https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*6zM5TpfV7qIAAAAAAAAAAAAADmJ7AQ/original"
}
]
}
62 changes: 62 additions & 0 deletions s2-site/examples/interaction/basic/demo/state-theme.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
import { PivotSheet, S2Options } from '@antv/s2';

fetch(
'https://gw.alipayobjects.com/os/bmw-prod/2a5dbbc8-d0a7-4d02-b7c9-34f6ca63cff6.json',
)
.then((res) => res.json())
.then((dataCfg) => {
const container = document.getElementById('container');

const s2Options: S2Options = {
width: 600,
height: 480,
interaction: {
hoverHighlight: true,
selectedCellHighlight: true,
selectedCellsSpotlight: true,
},
tooltip: {
showTooltip: true,
},
};
const s2 = new PivotSheet(container, dataCfg, s2Options);

s2.setTheme({
prepareSelectMask: {
backgroundColor: '#ccc',
},
dataCell: {
cell: {
interactionState: {
// 悬停聚焦: 关闭悬停单元格时出现的 "黑色边框"
hoverFocus: {
// 边框设置为透明
borderColor: 'transparent',
// 或者边框透明度设置为 0
// borderOpacity: 0
},
// 悬停
hover: {
backgroundOpacity: 0.2,
},
// 选中背景色/边框
selected: {
backgroundColor: 'pink',
borderWidth: 3,
},
// 高亮效果
highlight: {
textOpacity: 0.2,
backgroundColor: '#f63',
},
// 预选 (刷选)
prepareSelect: {
borderColor: '#396',
},
},
},
},
});

s2.render();
});