fix(frozen,docs): frozen,docs

1.frozen init, 2. docs api,operate BREAKING CHANGE: when init workbook and sheet has frozen row or column,you need init sheet's property frozen
dream-num · Aug 21, 2020 · e1bd844 · e1bd844
1 parent c5f6254
commit e1bd844
Show file tree

Hide file tree

Showing 10 changed files with 378 additions and 89 deletions.
diff --git a/docs/guide/FAQ.md b/docs/guide/FAQ.md
@@ -38,4 +38,12 @@ luckysheet.buildGridData(luckysheetfile)
 
 ## **<span style="font-size:20px;">Q</span>** Is the remote loading data loadUrl or updateUrl?
 
-**<span style="font-size:20px;">A</span>**: [loadUrl](/zh/guide/config.html#loadurl). Configure loadUrl, Luckysheet will request the entire table data through ajax, and updateUrl will be used as the interface address for collaborative editing in real-time saving.
+**<span style="font-size:20px;">A</span>**: [loadUrl](/zh/guide/config.html#loadurl). Configure loadUrl, Luckysheet will request the entire table data through ajax, and updateUrl will be used as the interface address for collaborative editing in real-time saving.
+
+------------
+
+## **<span style="font-size:20px;">Q</span>** How to understand the `index` and `order` of each worksheet?
+
+**<span style="font-size:20px;">A</span>**: Each worksheet has a unique id, which is `index`, which can be incremented by numbers or a random string. And `order` is the order of all worksheets, starting from 0.
+
+------------
diff --git a/docs/zh/guide/FAQ.md b/docs/zh/guide/FAQ.md
@@ -40,4 +40,10 @@ luckysheet.buildGridData(luckysheetfile)
 
 **<span style="font-size:20px;">A</span>** : [loadUrl](/zh/guide/config.html#loadurl)。配置了loadUrl，Luckysheet会通过ajax请求整个表格数据，而updateUrl会作为协同编辑实时保存的接口地址。
 
+------------
+
+## **<span style="font-size:20px;">Q</span>** 如何理解每个sheet页的`index`和`order`？
+
+**<span style="font-size:20px;">A</span>** : 每个sheet页都有一个唯一id，就是`index`，可以用数字递增，也可以使用随机字符串，而`order`是所有的sheet的排序情况，从0开始，即为索引。
+
 ------------
diff --git a/docs/zh/guide/api.md b/docs/zh/guide/api.md
@@ -159,15 +159,15 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 		+ `"false"`: 冻结首行
 		+ `"true"`: 冻结行到选区
 	- {PlainObject} [setting]: 可选参数
-    	+ {Array | Object | String} [range]: `isRange`为`true`的时候设置，开启冻结的选区范围,支持选区的格式为`"A1:B2"`、`"sheetName!A1:B2"`或者`{row:[0,1],column:[0,1]}`，只能为单个选区；默认为当前选区
+    	+ {Array | Object | String} [range]: `isRange`为`true`的时候设置，开启冻结的单元格位置，格式为`{ row_focus:0, column_focus:0 }`，意为当前激活的单元格的行数和列数；默认从当前选区最后的一个选区中取得
     	+ {Number} [order]: 工作表索引；默认值为当前工作表索引
         + {Function} [success]: 操作结束的回调函数
 
 - **说明**：
 
 	冻结行操作
 
-	特别注意，只有在`isRange`设置为`true`的时候，才需要设置`setting`中的`range`。
+	特别注意，只有在`isRange`设置为`true`的时候，才需要设置`setting`中的`range`，且与一般的range格式不同。
 
 - **示例**:
 
@@ -191,15 +191,15 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 		+ `"false"`: 冻结首列
 		+ `"true"`: 冻结列到选区
 	- {PlainObject} [setting]: 可选参数
-    	+ {Array | Object | String} [range]: `isRange`为`true`的时候设置，开启冻结的选区范围,支持选区的格式为`"A1:B2"`、`"sheetName!A1:B2"`或者`{row:[0,1],column:[0,1]}`，只能为单个选区；默认为当前选区
+    	+ {Array | Object | String} [range]: `isRange`为`true`的时候设置，开启冻结的单元格位置，格式为`{ row_focus:0, column_focus:0 }`，意为当前激活的单元格的行数和列数；默认从当前选区最后的一个选区中取得
     	+ {Number} [order]: 工作表索引；默认值为当前工作表索引
         + {Function} [success]: 操作结束的回调函数
 
 - **说明**：
 
 	冻结列操作
 
-	特别注意，只有在`isRange`设置为`true`的时候，才需要设置`setting`中的`range`。
+	特别注意，只有在`isRange`设置为`true`的时候，才需要设置`setting`中的`range`，且与一般的range格式不同。
 
 - **示例**:
 
@@ -219,15 +219,15 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 		+ `"false"`: 冻结行列
 		+ `"true"`: 冻结行列到选区
 	- {PlainObject} [setting]: 可选参数
-    	+ {Array | Object | String} [range]: `isRange`为`true`的时候设置，开启冻结的选区范围,支持选区的格式为`"A1:B2"`、`"sheetName!A1:B2"`或者`{row:[0,1],column:[0,1]}`，只能为单个选区；默认为当前选区
+    	+ {Array | Object | String} [range]: `isRange`为`true`的时候设置，开启冻结的单元格位置，格式为`{ row_focus:0, column_focus:0 }`，意为当前激活的单元格的行数和列数；默认从当前选区最后的一个选区中取得
     	+ {Number} [order]: 工作表索引；默认值为当前工作表索引
         + {Function} [success]: 操作结束的回调函数
 
 - **说明**：
 
 	冻结行列操作
 
-	特别注意，只有在`isRange`设置为`true`的时候，才需要设置`setting`中的`range`。
+	特别注意，只有在`isRange`设置为`true`的时候，才需要设置`setting`中的`range`，且与一般的range格式不同。
 
 - **示例**:
 
@@ -257,7 +257,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开
 
 ------------
 
-### insertRow( row [,setting])
+### insertRow(row [,setting])
 
 - **参数**：
 

diff --git a/docs/zh/guide/operate.md b/docs/zh/guide/operate.md
@@ -8,42 +8,21 @@
 
 以下为所有的支持传输到后台的操作类型，并且以MongoDB做存储示例，讲解如何做前后端交互。
 
-## 格式
-
-- **配置**：
-
-    配置 `updateUrl` 的地址，发送到后台的参数为json的字符串。
-
-- **格式**：
-
-    ```json
-    {
-        compress: false, 
-        gridKey:10004,
-        data: [更新json数据]
-    }
-    ```
-
-- **说明**：
-
-    | 参数 | 说明 | 举例 |
-    | ------------ | ------------ | ------------ |
-    |  compress | Luckysheet采用客户端pako进行zlib参数压缩，如果浏览器支持压缩则为true，否则为false。后台可以根据此参数决定是否解压data中的内容  | 服务端获取参数过程：1. 序列化json字符串 2. 判断compress字段如果为TRUE则解压data字段 3. 解码data字符串URLDecoder.decode(utf-8) |
-    |  gridKey | Luckysheet文件的标识符 | 无 |
-    |  data | 一个包含更新数据的数组，数组中的参数格式请看下面的介绍。实例中：`t`表示更新类型、`i`为sheet的索引、`c`为列号、`r`为行号，`v`为值  | `data: [{ t : 'v', i:0, c : 0,  r : 0 , v: 2 }]` |
-
-
 ## 单元格刷新
 
 - **格式**：
 
     ```json
     {
         "t": "v",
-        "i": 3,
-        "v": "good",
-        "r": 5,
-        "c": 7
+        "i": "Sheet_0554kKiKl4M7_1597974810804",
+        "v": {
+            "v": 233,
+            "ct": { "fa": "General", "t": "n" },
+            "m": "233"
+        },
+        "r": 0,
+        "c": 1
     }
     ```
 
@@ -53,35 +32,39 @@
     | ------------ | ------------ |
     |t|操作类型表示符号|
     |i|当前sheet的索引值|
-    |v|单元格的值，参考 [单元格属性表](/zh/guide/cell.html#基本单元格)|
+    |v|单元格的值，数字、字符串或着对象格式，对象参考 [单元格属性表](/zh/guide/cell.html#基本单元格)|
     |r|单元格的行号|
     |c|单元格的列号|
 
 - **后台更新**：
 
-    前端维护luckysheetfile[i].data，而单元格更新到后台，继续维护`luckysheetfile[i].celldata` 参数，该参数是一个一维数组：
+    前端维护luckysheetfile[i].data，而单元格更新到后台，继续维护`luckysheetfile[i].celldata` 参数，celldata是一个一维数组：
     ```json
     [
         {r:0, c:1, v: "值1"},
         {r:10, c:11, v:"值2"},
         {r:10, c:11, v:{f:"=sum", v:"100"}}
     ]
     ```
-    后台在保存前台推送的数据时，首先需要把参数转换为 `{r:0, c:1:v:100}` 的格式，然后更新 `luckysheetfile[i].celldata` 字段，如果存在该单元格则更新，如果没有则添加，如果存在该单元格但是`v`为null则删除该单元格。
+    后台在保存前台推送的数据时，会更新 `luckysheetfile[i].celldata` 字段，如果存在该单元格则更新，如果没有则添加，如果存在该单元格但是`v`为null则删除该单元格。
 
 ## config操作
 
 - **格式**：
 
   ```json
-  {
-    "t": "cg",
-    "i": 3,
-    "v": {
-        "7": 192
-    },
-    "k": "rowlen"
-  }
+    {
+        "t": "cg",
+        "i": "Sheet_0554kKiKl4M7_1597974810804",
+        "v": [ {
+                "rangeType": "range",
+                "borderType": "border-all",
+                "color": "#000",
+                "style": "1",
+                "range": [ {"row": [ 0, 1 ], "column": [ 1, 1 ] } ]
+            } ],
+        "k": "borderInfo"
+    }
   ```
 
 - **说明**：
@@ -90,40 +73,68 @@
     | ------------ | ------------ |
     |t|操作类型表示符号|
     |i|当前sheet的index值|
-    |v|需要更新的内部key-value|
-    |k|操作的key名称|
+    |v|需要更新value值|
+    |k|操作的key值，可选 边框：`'borderInfo'` / ：行隐藏：`'rowhidden'` / 列隐藏：`'columnhidden'` / 行高：`'rowlen'` / 列宽：`'columnlen'` |
 
 - **后台更新**：
 
-    更新 `luckysheetfile[i].config.[k][v.key] = v.value` ，如果`config`中不存在`k`，则新建一个`k`属性并设置为空，如果`k`中不存在`v.key`，则新建一个`v.key`再更新`v.value`。
+    更新 `luckysheetfile[i].config.[k] = v` ，如果`config`中不存在`k`，则新建一个`k`属性并设置为空。
 
-    1. 修改行高度举例：
-       - 输入：`{"t":"cg","i":3,"v":{"3":10, "5":70, "10":100},"k":" rowlen"}`
-       - 更新：`luckysheetfile[3].config.["rowlen"]["3"] = 10`
+    注意一点，修改config中的某个配置时，会把这个配置全部传输到后台，比如修改borderInfo，本来已经有一个含边框的单元格了，再新设置一个单元格边框，这时候会把这两个单元格边框信息都传输到后台，而不做更细颗粒的操作。
 
-    2. 修改列宽度举例：
-       - 输入：`{"t":"cg","i":1,"v":{"20":74, "15":170, "6":40},"k":" columnlen"}`
-       - 更新：`luckysheetfile[1].config.["columnlen"]["20"] = 74`
-
-    3. 合并单元格举例：
-       - 输入：`{"t":"cg","i":1,"v":{"5_10":{row:[1,3], column:[3,5]},"k":" merge "}`
-       - 更新：`luckysheetfile[1].config.["merge"]["5_10"] = {row:[1,3], column:[3,5]}`
+    1. 行隐藏：
+       - 发送到后台：
+            ```json
+            {
+                "t": "cg",
+                "i": "Sheet_0554kKiKl4M7_1597974810804",
+                "v": { "5": 0, "6": 0, "13": 0, "14": 0 }, // 包含所有隐藏行信息
+                "k": "rowhidden"
+            }
+            ```
+       - 后台更新：`luckysheetfile["Sheet_0554kKiKl4M7_1597974810804"].config.["rowhidden"] = { "5": 0, "6": 0, "13": 0, "14": 0 }`
+
+    2. 修改行高：
+       - 发送到后台：
+            ```json
+           {
+                "t": "cg",
+                "i": "Sheet_0554kKiKl4M7_1597974810804",
+                "v": { "9": 20, "11": 71, "15": 58 }, // 包含所有修改过高度的单元格信息
+                "k": "rowlen"
+            }
+            ```
+       - 后台更新：`luckysheetfile["Sheet_0554kKiKl4M7_1597974810804"].config.["rowlen"] = { "9": 20, "11": 71, "15": 58 }`
+
+    3. 修改列宽：
+       - 发送到后台：
+            ```json
+           {
+                "t": "cg",
+                "i": "Sheet_0554kKiKl4M7_1597974810804",
+                "v": { "2": 135 },
+                "k": "columnlen"
+            }
+            ```
+       - 后台更新：`luckysheetfile["Sheet_0554kKiKl4M7_1597974810804"].config.["columnlen"] = { "2": 135 }`
 
 ## 通用保存
 
 - **格式**：
 
   ```json
-  {
-    "t": "all",
-    "i": 3,
-    "v": {
-        "v": 1,
-        "m":1,
-    },
-    "k": "freezen",
-    "s": false
-  }
+    {
+        "t": "all",
+        "i": 0,
+        "v": {
+            "type": "rangeRow",
+            "range": {
+                "row_focus": 1,
+                "column_focus": 1
+            }
+        },
+        "k": "frozen"
+    }
   ```
 
 - **说明**：
@@ -132,9 +143,8 @@
     | ------------ | ------------ |
     |t|操作类型表示符号|
     |i|当前sheet的index值|
-    |v|需要更新的内部key-value|
-    |k|需要保存的key-value中的`value`|
-    |s|如果是`true`则`v`保存为字符串，否则按照对象进行保存|
+    |v|需要更新value值|
+    |k|操作的key值|
 
 - **后台更新**：
 

diff --git a/docs/zh/guide/sheet.md b/docs/zh/guide/sheet.md
@@ -37,7 +37,7 @@ options.data示例如下：
         "luckysheet_alternateformat_save": [], //交替颜色
         "luckysheet_alternateformat_save_modelCustom": [], //自定义交替颜色	
         "luckysheet_conditionformat_save": {},//条件格式
-        "freezen": {}, //冻结行列
+        "frozen": {}, //冻结行列
         "chart": [], //图表配置
     },
     {
@@ -711,7 +711,7 @@ type: "default": 突出显示单元格规则和项目选区规则，
     ```
 
 ------------
-### frozen(TODO)
+### frozen
 - 类型：Array
 - 默认值：[]
 - 作用： 冻结行列设置，分为6种类型
@@ -721,26 +721,33 @@ type: "default": 突出显示单元格规则和项目选区规则，
     4. "rangeRow": 冻结行到选区
     5. "rangeColumn": 冻结列到选区
     6. "rangeBoth": 冻结行列到选区
-    当设置冻结到选区的时候，需要设置选区范围`range`，支持选区的格式为`"A1:B2"`、`"sheetName!A1:B2"`或者`{row:[0,1],column:[0,1]}`，只能为单个选区；如果已经设置了`luckysheet_select_save`，则直接取当前第一个选区，不用再设置选区。
+    7. "cancel": 取消冻结
+
+    当设置冻结到选区的时候，需要设置开启冻结的单元格位置，格式为`{ row_focus:0, column_focus:0 }`，意为当前激活的单元格的行数和列数。
+
+    sheet新的配置属性，存储更语义化的配置，用于初始化和传给后端。
+
+    注意一点，luckysheetfile中还有一个配置freezen，其中的freezenhorizontaldata仍然用作本地数据，但是不发给后台存储，只做本地调试。
+
 - 示例：
     - 冻结首行
     ```json
     {
         type: 'row'
     }
     ```
-    - 冻结行到`'B2'`选区
+    - 冻结行到`'A1'`选区
      ```json
     {
         type: 'rangeRow',
-        range: {row:[1,1],column:[1,1]}
+        range: {row_focus: 0, column_focus: 0}
     }
     ```
-    - 冻结行列到`'B3:D4'`选区
+    - 冻结行列到`'B2'`选区
      ```json
     {
         type: 'rangeBoth',
-        range: "B3:D4"
+        range: {row_focus: 1, column_focus: 1}
     }
     ```