docs: 更新官网 S2 版本 & 优化文档

antvis · Nov 2, 2023 · 77d2bd8 · 77d2bd8
1 parent 3842c90
commit 77d2bd8
Show file tree

Hide file tree

Showing 20 changed files with 193 additions and 69 deletions.
diff --git a/README.en-US.md b/README.en-US.md
@@ -68,8 +68,9 @@ demo components and expansion capabilities, it allows developers to use it quick
 ## 📦 Installation
 
 ```bash
-$ npm install @antv/s2
-# yarn add @antv/s2
+$ npm install @antv/s2 --save
+# yarn add @antv/s2 --save
+# pnpm install @antv/s2 --save
 ```
 
 ## 🔨 Getting Started
@@ -227,9 +228,6 @@ yarn site:start
   <a>
     <img width="300" height="auto" alt="S2" src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*2VvTSZmI4vYAAAAAAAAAAAAADmJ7AQ/original">
   </a>
-  <a>
-    <img width="300" height="auto" alt="S2" src="https://gw.alipayobjects.com/zos/antfincdn/v4TlwgORE/qq_qr_code.JPG">
-  </a>
 </p>
 
 ## 👬 Contributors

diff --git a/README.md b/README.md
@@ -64,16 +64,17 @@ S2 是 AntV 在多维交叉分析表格领域的解决方案，完全基于数
 ## 📦 安装
 
 ```bash
-$ npm install @antv/s2
-# yarn add @antv/s2
+$ npm install @antv/s2 --save
+# yarn add @antv/s2 --save
+# pnpm install @antv/s2 --save
 ```
 
 ## 🔨 使用
 
 ### 1. 数据准备
 
 <details>
-  <summary> s2DataConfig</summary>
+  <summary>s2DataConfig</summary>
 
 ```ts
 const s2DataConfig = {
@@ -221,9 +222,6 @@ yarn site:start
   <a>
     <img width="300" height="auto" alt="DingTalk" src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*2VvTSZmI4vYAAAAAAAAAAAAADmJ7AQ/original">
   </a>
-  <a>
-    <img width="300" height="auto" alt="qq" src="https://gw.alipayobjects.com/zos/antfincdn/v4TlwgORE/qq_qr_code.JPG">
-  </a>
 </p>
 
 ## 👬 Contributors

diff --git a/packages/s2-react/playground/index.tsx b/packages/s2-react/playground/index.tsx
@@ -324,6 +324,57 @@ function MainLayout() {
     );
   }, [tableSheetColumnType]);
 
+  useUpdateEffect(() => {
+    switch (options.style.layoutWidthType) {
+      case 'compact':
+        updateOptions({
+          style: {
+            cellCfg: {
+              width: 200,
+            },
+          },
+        });
+        setDataCfg(
+          customMerge(pivotSheetDataCfg, {
+            data: [
+              ...pivotSheetDataCfg.data,
+              {
+                province: '浙江',
+                city: '杭州',
+                type: '笔',
+                price: '11111111',
+              },
+              {
+                province: '浙江',
+                city: '杭州',
+                type: '纸张',
+                price: '2',
+              },
+              {
+                province: '浙江',
+                city: '舟山',
+                type: '笔',
+                price: '2',
+              },
+              {
+                province: '浙江',
+                city: '舟山',
+                type: '纸张',
+                price: '133.333',
+              },
+            ],
+          }),
+        );
+        break;
+
+      default:
+        updateOptions({
+          style: DEFAULT_STYLE,
+        });
+        setDataCfg(pivotSheetDataCfg);
+    }
+  }, [options.style.layoutWidthType]);
+
   //  ================== Config ========================
 
   const mergedOptions: SheetComponentOptions = customMerge(
@@ -442,15 +493,18 @@ function MainLayout() {
                 <Tooltip title="布局类型">
                   <Radio.Group
                     onChange={onLayoutWidthTypeChange}
-                    defaultValue="adaptive"
+                    defaultValue={options.style.layoutWidthType}
                   >
                     <Radio.Button value="adaptive">行列等宽</Radio.Button>
                     <Radio.Button value="colAdaptive">列等宽</Radio.Button>
                     <Radio.Button value="compact">紧凑</Radio.Button>
                   </Radio.Group>
                 </Tooltip>
                 <Tooltip title="主题">
-                  <Radio.Group onChange={onThemeChange} defaultValue="default">
+                  <Radio.Group
+                    onChange={onThemeChange}
+                    defaultValue={themeCfg.name}
+                  >
                     <Radio.Button value="default">默认</Radio.Button>
                     <Radio.Button value="gray">简约灰</Radio.Button>
                     <Radio.Button value="colorful">多彩蓝</Radio.Button>

diff --git a/s2-site/docs/api/basic-class/spreadsheet.zh.md b/s2-site/docs/api/basic-class/spreadsheet.zh.md
@@ -58,7 +58,7 @@ s2.isPivotMode()
 | updatePagination | 更新分页                                                                                                                   | (pagination: [Pagination](/docs/api/general/S2Options#pagination)) => void |    |
 | getContentHeight | 获取当前表格实际内容高度                                                                                                           | `() => number` |    |
 | changeSheetSize （别名：changeSize) | 修改表格画布大小，不用重新加载数据                                                                                                      | `(width?: number, height?: number) => void` |    |
-| getLayoutWidthType | 获取单元格宽度布局类型（LayoutWidthType: `adaptive（自适应）` \| `colAdaptive（列自适应）` \| `compact（紧凑）`） | () => `LayoutWidthType`|    |
+| getLayoutWidthType | 获取单元格宽度布局类型。[详情](/api/general/s2-options#style) | () => `adaptive \| colAdaptive \| compact` |    |
 | getRowNodes | 获取行头节点                                                                                                                 | (level: number) => [Node[]](/docs/api/basic-class/node/) |    |
 | getRowLeafNodes | 获取行头叶子节点                                                                                                               | () => [Node[]](/docs/api/basic-class/node/) |    |
 | getColumnNodes | 获取列头节点                                                                                                                 | (level: number) => [Node[]](/docs/api/basic-class/node/) |    |

diff --git a/s2-site/docs/api/general/S2DataConfig.zh.md b/s2-site/docs/api/general/S2DataConfig.zh.md
@@ -68,7 +68,7 @@ object **必选**,_default：null_
 | columns        | 列维度列表         | [Columns[]](#columns) | `[]`   |      |
 | values         | 指标维度列表       | `string[]` | `[]`   |      |
 | valueInCols    | 指标维度是否在列头   | `boolean`  | `true` |      |
-| customValueOrder | 自定义指标维度在行列头中的层级顺序 （即 `values` 的 顺序，从 `0` 开始） [查看示例](/zh/examples/custom/custom-layout/#custom-value-order) | `number`  | - |      |
+| customValueOrder | 自定义指标维度在行列头中的层级顺序 （即 `values` 的 顺序，从 `0` 开始，**仅支持单指标**） [查看示例](/zh/examples/custom/custom-layout/#custom-value-order) | `number`  | - |      |
 
 ### Meta
 

diff --git a/s2-site/docs/common/contact-us.en.md b/s2-site/docs/common/contact-us.en.md
@@ -7,7 +7,4 @@ order: 5
   <a>
     <img width="300" height="auto" alt="DingTalk" src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*2VvTSZmI4vYAAAAAAAAAAAAADmJ7AQ/original">
   </a>
-  <a>
-    <img width="300" height="auto" alt="qq" src="https://gw.alipayobjects.com/zos/antfincdn/v4TlwgORE/qq_qr_code.JPG">
-  </a>
 </p>
diff --git a/s2-site/docs/common/contact-us.zh.md b/s2-site/docs/common/contact-us.zh.md
@@ -7,7 +7,4 @@ order: 5
   <a>
     <img width="300" height="auto" alt="DingTalk" src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*2VvTSZmI4vYAAAAAAAAAAAAADmJ7AQ/original">
   </a>
-  <a>
-    <img width="300" height="auto" alt="qq" src="https://gw.alipayobjects.com/zos/antfincdn/v4TlwgORE/qq_qr_code.JPG">
-  </a>
 </p>
diff --git a/s2-site/docs/common/development.zh.md b/s2-site/docs/common/development.zh.md
@@ -1,4 +1,12 @@
-跃跃欲试想贡献？[查看贡献指南](https://s2.antv.antgroup.com/manual/contribution)
+跃跃欲试想贡献？[查看贡献指南](https://s2.antv.antgroup.com/manual/contribution) , 欢迎 [Pull Request](https://github.com/antvis/S2/pulls)，或给我们 [报告 Bug](https://github.com/antvis/S2/issues/new?assignees=&labels=&projects=&template=bug-report.md&title=%F0%9F%90%9B).
+
+> 强烈建议花一点你的宝贵时间阅读：
+
+- [《提 Issue 前必读》](https://github.com/antvis/S2/issues/1904)
+- [《如何向开源项目提交无法解答的问题》](https://zhuanlan.zhihu.com/p/25795393)
+- [《如何有效地报告 Bug》](https://www.chiark.greenend.org.uk/~sgtatham/bugs-cn.html)
+- [《提问的智慧》](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way)
+- [《如何向开源社区提问题》](https://github.com/seajs/seajs/issues/545)
 
 ```bash
 git clone [email protected]:antvis/S2.git

diff --git a/s2-site/docs/common/packages.zh.md b/s2-site/docs/common/packages.zh.md
@@ -3,8 +3,23 @@ title: Packages
 order: 5
 ---
 
+- `@antv/s2`: 基于 `Canvas` 和 [AntV/G](https://g.antv.vision/zh/docs/guide/introduce) 开发，提供基本的表格展示/交互等能力。
+- `@antv/s2-react`: 基于 `React` 和 `@antv/s2` 封装，提供配套的分析组件，配置项和 `@antv/s2` 通用。
+- `@antv/s2-vue`: 基于 `Vue3` 和 `@antv/s2` 封装，配置项和 `@antv/s2` 通用，如果你想在 `Vue2` 中使用，请使用 `@antv/s2`。
+
+也就是说 `@antv/s2` 和**框架无关**，你也可以在 `Vue`, `Angular` 等框架中直接使用。
+
 | 版本号  | 稳定版    | 测试版   | 预览版  | 先行版 | 包大小  | 下载量    |
 | -------- | ------ | --------- | ---------- | ----------  | ----------  | ------ |
 | [@antv/s2](https://github.com/antvis/S2/tree/master/packages/s2-core)        | ![latest](https://img.shields.io/npm/v/@antv/s2/latest.svg)       | ![beta](https://img.shields.io/npm/v/@antv/s2/beta.svg)       | ![alpha](https://img.shields.io/npm/v/@antv/s2/alpha.svg)   |  ![next](https://img.shields.io/npm/v/@antv/s2/next.svg)  | ![size](https://img.badgesize.io/https:/unpkg.com/@antv/s2@latest/dist/index.min.js?label=gzip%20size&compression=gzip)       | ![download](https://img.shields.io/npm/dm/@antv/s2.svg)       |
 | [@antv/s2-react](https://github.com/antvis/S2/tree/master/packages/s2-react) | ![latest](https://img.shields.io/npm/v/@antv/s2-react/latest.svg) | ![beta](https://img.shields.io/npm/v/@antv/s2-react/beta.svg) | ![alpha](https://img.shields.io/npm/v/@antv/s2-react/alpha.svg) |  ![next](https://img.shields.io/npm/v/@antv/s2-react/next.svg)| ![size](https://img.badgesize.io/https:/unpkg.com/@antv/s2-react@latest/dist/index.min.js?label=gzip%20size&compression=gzip) | ![download](https://img.shields.io/npm/dm/@antv/s2-react.svg) |
 | [@antv/s2-vue](https://github.com/antvis/S2/tree/master/packages/s2-vue)     | ![latest](https://img.shields.io/npm/v/@antv/s2-vue/latest.svg)   | ![beta](https://img.shields.io/npm/v/@antv/s2-vue/beta.svg)   | ![alpha](https://img.shields.io/npm/v/@antv/s2-vue/alpha.svg)  |  ![next](https://img.shields.io/npm/v/@antv/s2-vue/next.svg) | ![size](https://img.badgesize.io/https:/unpkg.com/@antv/s2-vue@latest/dist/index.min.js?label=gzip%20size&compression=gzip)   | ![download](https://img.shields.io/npm/dm/@antv/s2-vue.svg)   |
+
+:::info{title='如何获取新版本发布通知？'}
+
+- 订阅：[https://github.com/antvis/S2/releases.atom](https://github.com/antvis/S2/releases.atom) 来获得新版本发布的通知。
+- 加入钉钉交流群，新版本发布后，会通过🤖 群机器人推送。
+- `Watch` [S2 代码仓库](https://github.com/antvis/S2), 选择 `Custom - Releases` 来获取消息推送。
+
+![preview](https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*NKYFSKFV_scAAAAAAAAAAAAADmJ7AQ/original)
+:::
diff --git a/s2-site/docs/common/style.zh.md b/s2-site/docs/common/style.zh.md
@@ -9,7 +9,7 @@ object **必选**,_default：null_ 功能描述：样式设置
 
 | 参数 | 类型 | 必选  | 默认值 | 功能描述 |
 | --- | --- | ---  | --- | --- |
-| layoutWidthType | `adaptive \| colAdaptive \| compact` |    |  | 单元格宽度布局类型<br> `adaptive` : 行列等宽，均分整个 `Canvas` 画布宽度 <br> `colAdaptive`：列等宽，行头紧凑布局，列等分画布宽度减去行头宽度的剩余宽度<br> `compact`：行列紧凑布局，列头宽度为内容实际宽度 （采样列前 50 个数值）, 指标维度少的时候无法布满整个画布 |
+| layoutWidthType | `adaptive \| colAdaptive \| compact` |    |  | 单元格宽度布局类型<br> `adaptive` : 行列等宽，均分整个表格 (`Canvas`) 画布宽度 <br> `colAdaptive`：列等宽，行头紧凑布局，列等分画布宽度减去行头宽度的剩余宽度<br> `compact`：行列紧凑布局，列头宽度为内容实际宽度 （采样列前 50 个数值）, 指标维度少的时候无法布满整个画布 |
 | showTreeLeafNodeAlignDot | `boolean` |  |  false  | 树状模式下叶子节点是否显示层级占位点 |
 | treeRowsWidth | `number` |  |  120  | 树状模式行单元格宽度 （优先级大于 `rowCfg.width` 和 `rowCfg.treeRowsWidth （已废弃）`) |
 | hierarchyCollapse | `boolean` |  |   `false` | 在树状结构模式下行头是否默认展开。 |

diff --git a/s2-site/docs/manual/faq.zh.md b/s2-site/docs/manual/faq.zh.md
@@ -4,7 +4,7 @@ order: 8
 ---
 
 :::warning{title="一些建议"}
-**在提出问题前，请确保你已经仔细阅读了一遍文档，查看了相关图表示例，并且已经查看了常见问题。**
+**在提出问题前，请确保你已经仔细阅读了一遍文档，查看了相关图表示例，并且已经查看了常见问题和 Issues。**
 :::
 
 ## 1. 使用问题
@@ -254,17 +254,7 @@ s2.setTheme({
 
 目前只有 React 版本 `@antv/s2-react` 支持编辑表格，其他版本暂不支持，需参考 [源码](https://github.com/antvis/S2/blob/2d85d5739f5a3a52e92df699a935df93aa2a6a73/packages/s2-react/src/components/sheets/editable-sheet/index.tsx#L10) 自行实现
 
-### S2 有对应的 `Vue` 或者 `Angular` 版本吗？
-
-目前，S2 由三个包构成
-
-- `@antv/s2`: 基于 `canvas` 和 [AntV/G](https://g.antv.vision/zh/docs/guide/introduce) 开发，提供基本的表格展示/交互等能力
-- `@antv/s2-react`: 基于 `@antv/s2` 封装，提供配套的分析组件
-- `@antv/s2-vue`: 基于 `Vue3` 和 `@antv/s2` 封装，提供配套的分析组件
-
-也就是说 `@antv/s2` 和**框架无关**，你可以在 `Vue`, `Angular` 等框架中使用。
-
-以下是版本概览：
+### S2 有对应的 `Vue` 或者 `Angular` 版本吗？如何获取新版本发布通知？
 
 <embed src="@/docs/common/packages.zh.md"></embed>
 
@@ -323,6 +313,8 @@ s2.setTheme({
 
 ### 有讨论群吗？
 
+交流群不提供任何答疑，有任何问题请直接提交 [Issue](https://github.com/antvis/S2/issues/new/choose) 或者 [Discussion](https://github.com/antvis/S2/discussions/new?category=q-a), 当然，也期待你的 [Pull request](https://github.com/antvis/S2/pulls).
+
 <embed src="@/docs/common/contact-us.zh.md"></embed>
 
 ## 2. 错误和警告
diff --git a/s2-site/docs/manual/getting-started.zh.md b/s2-site/docs/manual/getting-started.zh.md
@@ -2,26 +2,30 @@
 title: 快速上手
 order: 1
 ---
+
 ## 📦 安装
 
-### npm | yarn 安装
+### 使用 npm 或 yarn 或 pnpm 安装
 
 ```bash
 # npm
-$ npm install @antv/s2
+$ npm install @antv/s2 --save
 
 # yarn
-$ yarn add @antv/s2
+$ yarn add @antv/s2 --save
+
+# pnpm
+$ pnpm install @antv/s2 --save
 ```
 
 ### 使用 React 或 Vue3 版本
 
 ```bash
 # React
-$ yarn add @antv/s2 @antv/s2-react
+$ yarn add @antv/s2 @antv/s2-react --save
 
 # Vue3
-$ yarn add @antv/s2 @antv/s2-vue
+$ yarn add @antv/s2 @antv/s2-vue --save
 ```
 
 ### 浏览器引入（不推荐）
@@ -34,6 +38,8 @@ $ yarn add @antv/s2 @antv/s2-vue
 
 创建 `S2` 表格有三种方式，基础类版本 `(s2-core)` 和 基于 `core` 层 封装的 `React` 和 `Vue3` 版本
 
+### 版本
+
 <embed src="@/docs/common/packages.zh.md"></embed>
 
 ### 基础类
@@ -184,7 +190,8 @@ s2.render();
 
 ### `React` 版本
 
-`S2` 提供了开箱即用的 `React` 版本 [表格组件](/examples/gallery#category-表格组件）, 还有丰富的配套 [分析组件](/examples/gallery#category-Tooltip), 帮助开发者快速满足业务看数分析需求。
+`S2` 提供了开箱即用的 `React` 版本 [表格组件](examples/gallery#category-表格组件)
+, 还有丰富的配套 [分析组件](/examples/gallery#category-Tooltip), 帮助开发者快速满足业务看数分析需求。
 
 #### 表格组件使用
 
@@ -194,8 +201,6 @@ import ReactDOM from 'react-dom';
 import { SheetComponent } from '@antv/s2-react';
 import '@antv/s2-react/dist/style.min.css';
 
-const container = document.getElementById('container');
-
 ReactDOM.render(
   <SheetComponent
     dataCfg={s2DataConfig}
@@ -206,18 +211,19 @@ ReactDOM.render(
 
 ```
 
-#### 注意事项
-
-`React` 版本的 `分析组件` 如：`高级排序`, `导出`, `下钻`, `Tooltip` 等组件基于 `antd` 组件库开发，如需使用，需要额外安装，并引入对应样式
+:::warning{title='注意事项'}
+`React` 版本的 `分析组件` 如：`高级排序`, `导出`, `下钻`, `Tooltip` 等组件基于 `antd` 组件库开发，如需使用，需要额外安装，并引入对应样式。
 
-```ts
-yarn add antd @ant-design/icons
+```bash
+yarn add antd @ant-design/icons --save
 ```
 
 ```ts
 import 'antd/dist/antd.min.css';
 ```
 
+:::
+
 📊 查看 [React 版本透视表 demo](/examples/react-component/sheet#pivot)。
 
 ### `Vue3` 版本
@@ -267,20 +273,26 @@ createApp(App).mount('#app');
 
 ```
 
-#### 注意事项
+:::warning{title='注意事项'}
 
-`Vue3` 版本的 `分析组件` 如：`高级排序`, `导出`, `下钻`, `Tooltip` 等组件基于 `ant-design-vue` 组件库开发，如需使用，需要额外安装，并引入对应样式
+`Vue3` 版本的 `分析组件` 如：`高级排序`, `导出`, `下钻`, `Tooltip` 等组件基于 `ant-design-vue` 组件库开发，如需使用，需要额外安装，并引入对应样式。
 
-```ts
-yarn add ant-design-vue
+```bash
+yarn add ant-design-vue --save
 ```
 
+:::
+
 ```ts
 import "@antv/s2-vue/dist/style.min.css";
 ```
 
 📊 查看 [Vue3 版本透视表 demo](https://codesandbox.io/s/s2-vue-hwg64q)。
 
+## TypeScript
+
+`S2` 使用 `TypeScript` 开发，提供完整的类型定义文件，配合 `VS Code` 等编辑器可以获得良好的类型提示。
+
 ## ⌨️ 本地开发
 
 <embed src="@/docs/common/development.zh.md"></embed>
diff --git a/s2-site/docs/manual/introduction.zh.md b/s2-site/docs/manual/introduction.zh.md
@@ -27,7 +27,7 @@ redirect_from:
 
 ## ❓ 什么是 S2
 
-[S2](https://github.com/antvis/s2) 是一个面向可视分析领域的数据驱动的表可视化引擎。"S" 取自于 "SpreadSheet" 的两个 "S"，"2" 代表了透视表中的行列两个维度。旨在提供美观、易用、高性能、易扩展的多维表格。
+[S2](https://github.com/antvis/s2) 是一个面向可视分析领域的数据驱动的表可视化引擎。`S` 取自于 `SpreadSheet` 的两个 `S`，`2` 代表了透视表中的行列两个维度。旨在提供美观、易用、高性能、易扩展的多维表格。
 
 ![demos](https://gw.alipayobjects.com/zos/antfincdn/6R5Koawk9L/huaban%2525202.png)
 
@@ -42,8 +42,9 @@ redirect_from:
 ## 📦 安装
 
 ```bash
-npm install @antv/s2
-# yarn add @antv/s2
+npm install @antv/s2 --save
+# yarn add @antv/s2 --save
+# pnpm install @antv/s2 --save
 ```
 
 ## 🔨 使用
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,7 +7,4 @@ order: 5 @@
       <a>
         <img width="300" height="auto" alt="DingTalk" src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*2VvTSZmI4vYAAAAAAAAAAAAADmJ7AQ/original">
       </a>
-      <a>
-        <img width="300" height="auto" alt="qq" src="https://gw.alipayobjects.com/zos/antfincdn/v4TlwgORE/qq_qr_code.JPG">
-      </a>
     </p>