docs: cell config, facade range api

dream-num · Apr 25, 2024 · 34c5022 · 34c5022
1 parent 97bc3b7
commit 34c5022
Show file tree

Hide file tree

Showing 4 changed files with 141 additions and 101 deletions.
diff --git a/packages/community/src/content/docs/guides/configuration/cell-data.mdx b/packages/community/src/content/docs/guides/configuration/cell-data.mdx
@@ -10,20 +10,26 @@ This document is only applicable to 📊 Univer Sheet.
 
 ## Cell Position
 
-The cell data in Univer Sheet is stored in the [cellData](/api/core/interfaces/IWorksheetData.html#cellData) field of [IWorksheetData](/api/core/interfaces/IWorksheetData.html), cellData is a two-dimensional Map structure, each key value marks the position of the cell, and the value is an [ICellData](/api/core/interfaces/ICellData.html) object, which contains all the cell information such as cell value, style, type, etc.
+The cell data in Univer Sheet is stored in the [cellData](/api/core/interfaces/IWorksheetData.html#cellData) field of [IWorksheetData](/api/core/interfaces/IWorksheetData.html), cellData is a two-dimensional Map structure, with the first and second indexes representing the row number and column number respectively, and each cell is an [ICellData](/api/core/interfaces/ICellData.html) object, which contains all the cell information such as cell value, style, type, etc.
 
-Just like this.
+The structure of cellData is as follows
 
 ```typescript
 // IWorksheetData
 {   
   cellData: {
+    // first row
     0: {
+      // first column
       0: { v: 'A1' },
+      // second column
       1: { v: 'B1' },
     },
+    // second row
     1: {
+      // first column
       0: { v: 'A2' },
+      // second column
       1: { v: 'B2' },
     },
   }
@@ -37,7 +43,7 @@ The complete cell information is as follows.
 | Property | Description |
 | --- | --- |
 | v | Cell original value |
-| s | Cell style object or style id |
+| s | Cell style id or style object |
 | t | Cell type |
 | p | Rich text, also a 📝 Univer Doc |
 | f | Formula |
@@ -48,7 +54,7 @@ Check out the type information of each field of [ICellData](/api/core/interfaces
 
 ### Cell Original Value
 
-`cellData.v` stores the original value of the cell, which can be a string or a number.
+`cellData.v` stores the original value of the cell, which can be a string or a number. For cells with formulas, `v` stores the calculation result of the formula.
 
 Here we show two different cell values.
 
@@ -66,9 +72,45 @@ Here we show two different cell values.
 
 ### Cell Style
 
-`cellData.s` stores the style of the cell. If the type is an object, it represents a complete cell style object [IStyleData](/api/core/interfaces/IStyleData.html).
+`cellData.s` stores the style id or style object of the cell.
 
-The complete style field is as follows.
+If `s` is a string, it represents a style id. Univer Sheet supports reference optimization for styles. The repeated style objects are stored in the [styles](/api/core/interfaces/IWorkbookData.html#styles) field of IWorkbookData, which is a Map structure, each key is the style id, and the value is the style object.
+
+```typescript
+// IWorkbookData
+{
+  styles: {
+    'random_style_id_1': {
+      fs: 12,
+      bg: {
+        rgb: '#ff0000'
+      }
+    }
+  }
+}
+```
+
+Then store the id in the cell style to achieve the purpose of style reuse.
+
+```typescript
+// IWorksheetData
+{
+  cellData: {
+    0: {
+      0: { 
+        v: 'A1', 
+        s: 'random_style_id_1'
+      },
+      1: { 
+        v: 'B1', 
+        s: 'random_style_id_1'
+      },
+    },
+  }
+}
+```
+
+If `s` is an object, it represents a complete cell style object [IStyleData](/api/core/interfaces/IStyleData.html).
 
 The complete style field is as follows.
 
@@ -343,45 +385,9 @@ You can check out the type information of each field of [IStyleData](/api/core/i
 } 
 ```
 
-Cell style may also be a string, representing the style id. Univer Sheet supports reference optimization for styles. The repeated style objects are stored in the [styles](/api/core/interfaces/IWorkbookData.html#styles) field of [IWorkbookData](/api/core/interfaces/IWorkbookData.html), which is a Map structure, each key is the style id, and the value is the style object.
-
-```typescript
-// IWorkbookData
-{
-  styles: {
-    'random_style_id_1': {
-      fs: 12,
-      bg: {
-        rgb: '#ff0000'
-      }
-    }
-  }
-}
-```
-
-Then store the id in the cell style to achieve the purpose of style reuse.
-
-```typescript
-// IWorksheetData
-{
-  cellData: {
-    0: {
-      0: { 
-        v: 'A1', 
-        s: 'random_style_id_1'
-      },
-      1: { 
-        v: 'B1', 
-        s: 'random_style_id_1'
-      },
-    },
-  }
-}
-```
-
 ### Cell Type
 
-`cellData.t` is an enum number, represents the type of the cell. `1` means string, `2` means number, `3` means boolean, `4` means force text.
+`cellData.t` is an enumeration [CellValueType](/api/core/enums/CellValueType.html), represents the type of the cell. `1` means string, `2` means number, `3` means boolean, `4` means force text. Univer will automatically recognize it if it is not set.
 
 If the cell is a boolean type, the value of `cellData.v` is stored as `0` or `1`, `0` means false, `1` means true.
 

diff --git a/packages/community/src/content/docs/guides/facade/sheet.mdx b/packages/community/src/content/docs/guides/facade/sheet.mdx
@@ -163,24 +163,19 @@ univerAPI.executeCommand('sheet.command.active-sheet', { unitId: workbookId, sub
 
 ## Cell
 
-Cell data is stored in the worksheet as a two-dimensional array, with the first and second indexes representing the row number and column number respectively.
+Cell data is stored in the worksheet as a two-dimensional Map, with the first and second indexes representing the row number and column number respectively.
 
 The following is a typical cell object:
 
 ```ts
 {
   v: 'Hello, Univer',
-  s: 'styleName',
-  f: '=A1+B1',
+  s: 'styleId',
   t: CellValueType.STRING
 }
 ```
 
-- `v` stores the value of the cell, which can be a string, number, or boolean. For cells with formulas, `v` stores the result of the formula.
-- `s` stores the style name, which points to the style sheet in the workbook; or stores the style object.
-- `f` stores the formula
-- `t` stores the value type, which is automatically recognized by Univer if not set. For the enumeration document, see [CellValueType](/api/core/enums/CellValueType.html)
-- `p` stores rich text content
+For detailed field descriptions, please refer to [Configure Cell Data](/guides/configuration/cell-data/).
 
 :::tip
 Cell operations can be regarded as operations on a range of rows and columns with a height of 1 and a width of 1. For the operation range, please refer to [Range](#range).
@@ -235,11 +230,29 @@ range.forEach((cell, row, column) => {
 
 If a value or cell object is passed in, all cells in the range will be overwritten. If it starts with `=`, it will be interpreted as a formula.
 
+For example, to set the value of A1:B2 to `Hello, Univer`:
 ```ts
 const range = activeSheet.getRange(0, 0, 2, 2);
 range.setValue('Hello, Univer');
 ```
 
+Set the value of A1+B1 to the formula:
+```ts
+const range = activeSheet.getRange(0, 0, 2, 2);
+range.setValue('=A1+B1');
+```
+
+Set the value of A1:B2 to the cell object:
+```ts
+const range = activeSheet.getRange(0, 0, 2, 2);
+range.setValue({ 
+  v: 'Hello, Univer',
+  custom: {
+      key: 'value',
+  },
+});
+```
+
 #### Set multiple values with an array
 
 The length and width of the array must match the length and width of the range.

diff --git a/packages/community/src/content/docs/zh-cn/guides/configuration/cell-data.mdx b/packages/community/src/content/docs/zh-cn/guides/configuration/cell-data.mdx
@@ -10,20 +10,26 @@ sidebar:
 
 ## 单元格位置
 
-Univer Sheet 中的单元格数据存储在 [IWorksheetData](/api/core/interfaces/IWorksheetData.html) 的 [cellData](/api/core/interfaces/IWorksheetData.html#cellData) 字段中，cellData 是一个二维 Map 结构，每个 key 值标记了单元格的位置，value 是一个 [ICellData](/api/core/interfaces/ICellData.html) 对象，包含了单元格值、样式、类型等所有单元格信息。
+Univer Sheet 中的单元格数据存储在 [IWorksheetData](/api/core/interfaces/IWorksheetData.html) 的 [cellData](/api/core/interfaces/IWorksheetData.html#cellData) 字段中，cellData 是一个二维 Map 结构，一二级索引分别代表行号和列号，每一个单元格是一个 [ICellData](/api/core/interfaces/ICellData.html) 对象，包含了单元格值、样式、类型等所有单元格信息。
 
-类似于这样。
+cellData 的结构如下
 
 ```typescript
 // IWorksheetData
 {   
   cellData: {
+    // 第一行
     0: {
+      // 第一列
       0: { v: 'A1' },
+      // 第二列
       1: { v: 'B1' },
     },
+    // 第二行
     1: {
+      // 第一列
       0: { v: 'A2' },
+      // 第二列
       1: { v: 'B2' },
     },
   }
@@ -37,7 +43,7 @@ Univer Sheet 中的单元格数据存储在 [IWorksheetData](/api/core/interface
 | 属性 | 说明 |
 | --- | --- |
 | v | 单元格的原始值 |
-| s | 单元格的样式对象或者样式 id |
+| s | 单元格的样式 id 或者样式对象 |
 | t | 单元格的类型 |
 | p | 富文本，同时也是一个 📝 Univer Doc |
 | f | 公式 |
@@ -48,7 +54,7 @@ Univer Sheet 中的单元格数据存储在 [IWorksheetData](/api/core/interface
 
 ### 单元格原始值
 
-`cellData.v` 存储了单元格的原始值，可以为字符串或者数字。
+`cellData.v` 存储了单元格的原始值，可以为字符串或者数字。有公式的单元格，`v` 存放公式的计算结果。
 
 如下展示了两种不同的单元格值。
 
@@ -66,7 +72,45 @@ Univer Sheet 中的单元格数据存储在 [IWorksheetData](/api/core/interface
 
 ### 单元格样式
 
-`cellData.s` 存储了单元格的样式，如果类型是一个对象，则表示一个完整的单元格样式对象 [IStyleData](/api/core/interfaces/IStyleData.html)。
+`cellData.s` 存储了单元格的样式 id 或者样式对象。
+
+如果 `s` 是一个字符串，表示样式 id。Univer Sheet 支持对样式做引用优化，将重复的样式对象存储在 IWorkbookData 的 [styles](/api/core/interfaces/IWorkbookData.html#styles) 字段中，是一个 Map 结构，每个 key 是样式 id，value 是样式对象。
+
+```typescript
+// IWorkbookData
+{
+  styles: {
+    'random_style_id_1': {
+      fs: 12,
+      bg: {
+        rgb: '#ff0000'
+      }
+    }
+  }
+}
+```
+
+然后将 id 存储到单元格样式中，达到样式复用的目的。
+
+```typescript
+// IWorksheetData
+{
+  cellData: {
+    0: {
+      0: { 
+        v: 'A1', 
+        s: 'random_style_id_1'
+      },
+      1: { 
+        v: 'B1', 
+        s: 'random_style_id_1'
+      },
+    },
+  }
+}
+```
+
+如果 `s` 是一个对象，则表示一个完整的单元格样式对象 [IStyleData](/api/core/interfaces/IStyleData.html)。
 
 完整的样式字段如下。
 
@@ -341,45 +385,9 @@ Univer Sheet 中的单元格数据存储在 [IWorksheetData](/api/core/interface
 } 
 ```
 
-单元格样式还有可能是一个字符串，表示样式 id。Univer Sheet 支持对样式做引用优化，将重复的样式对象存储在 IWorkbookData 的 [styles](/api/core/interfaces/IWorkbookData.html#styles) 字段中，是一个 Map 结构，每个 key 是样式 id，value 是样式对象。
-
-```typescript
-// IWorkbookData
-{
-  styles: {
-    'random_style_id_1': {
-      fs: 12,
-      bg: {
-        rgb: '#ff0000'
-      }
-    }
-  }
-}
-```
-
-然后将 id 存储到单元格样式中，达到样式复用的目的。
-
-```typescript
-// IWorksheetData
-{
-  cellData: {
-    0: {
-      0: { 
-        v: 'A1', 
-        s: 'random_style_id_1'
-      },
-      1: { 
-        v: 'B1', 
-        s: 'random_style_id_1'
-      },
-    },
-  }
-}
-```
-
 ### 单元格类型
 
-`cellData.t` 是一个枚举，表示单元格的类型。`1` 表示字符串，`2` 表示数字，`3` 表示布尔值，`4` 表示强制文本。
+`cellData.t` 是一个枚举 [CellValueType](/api/core/enums/CellValueType.html)，表示单元格的类型。`1` 表示字符串，`2` 表示数字，`3` 表示布尔值，`4` 表示强制文本，不设置时 Univer 会自动识别。
 
 其中，如果单元格是布尔类型，则 `cellData.v` 的值存储为 `0` 或 `1`，`0` 表示 false，`1` 表示 true。
 

diff --git a/packages/community/src/content/docs/zh-cn/guides/facade/sheet.mdx b/packages/community/src/content/docs/zh-cn/guides/facade/sheet.mdx
@@ -163,24 +163,19 @@ univerAPI.executeCommand('sheet.command.active-sheet', { unitId: workbookId, sub
 
 ## 单元格 Cell
 
-单元格数据以二维数组的形式存储在工作表中，一二级索引分别代表行号和列号。
+单元格数据以二维 Map 的形式存储在工作表中，一二级索引分别代表行号和列号。
 
 以下是一个典型的单元格对象：
 
 ```ts
 {
   v: 'Hello, Univer',
-  s: 'styleName',
-  f: '=A1+B1',
+  s: 'styleId',
   t: CellValueType.STRING
 }
 ```
 
-- `v` 存放单元格的值，可以是字符串、数字、布尔值。有公式的单元格，`v` 存放公式的计算结果。
-- `s` 存放样式名称，指向工作簿中的样式表；或者存放样式对象。
-- `f` 存放公式
-- `t` 存放值的类型，不设置时 Univer 会自动识别，枚举文档见 [CellValueType](/api/core/enums/CellValueType.html)
-- `p` 存放富文本内容
+详细的字段说明请参考 [单元格信息](/zh-cn/guides/configuration/cell-data/)。
 
 :::tip
 对单元格的操作可以看作对行高 1 、列宽 1 的范围进行操作，操作范围请阅读 [范围-range](#范围-range)。
@@ -235,11 +230,29 @@ range.forEach((cell, row, column) => {
 
 传入一个值或者单元格对象，将会覆盖范围内所有单元格，如果以 `=` 开头，将被解释为公式。
 
+比如，设置 A1:B2 的值为 `Hello, Univer`：
 ```ts
 const range = activeSheet.getRange(0, 0, 2, 2);
 range.setValue('Hello, Univer');
 ```
 
+设置 A1+B1 的值为公式：
+```ts
+const range = activeSheet.getRange(0, 0, 2, 2);
+range.setValue('=A1+B1');
+```
+
+设置 A1:B2 的值为单元格对象：
+```ts
+const range = activeSheet.getRange(0, 0, 2, 2);
+range.setValue({ 
+  v: 'Hello, Univer',
+  custom: {
+      key: 'value',
+  },
+});
+```
+
 #### 通过数组设置多个值
 
 数组的长度和宽度必须和范围的长宽一致。