diff --git a/README.md b/README.md index d930a2a..d903b31 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,9 @@ ![logo](/docs/.vuepress/public/img/logo_text.png) [![Join the chat at https://gitter.im/mengshukeji/Luckysheet](https://badges.gitter.im/mengshukeji/Luckysheet.svg)](https://gitter.im/mengshukeji/Luckysheet?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) + + follow on Twitter diff --git a/docs/zh/guide/api.md b/docs/zh/guide/api.md index fff2e20..b365759 100644 --- a/docs/zh/guide/api.md +++ b/docs/zh/guide/api.md @@ -9,7 +9,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 ## 单元格操作 -### getCellValue(row, column [,setting]) +### getCellValue(row, column [,setting])
- **参数**： @@ -504,10 +504,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 [ { "v": "vaule1", - "ct": { - "fa": "General", - "t": "g" - }, + "ct": { "fa": "General", "t": "g" }, "m": "vaule1", "bg": "rgba(255,255,255)", "bl": 0, @@ -520,10 +517,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 }, { "v": "value3", - "ct": { - "fa": "General", - "t": "g" - }, + "ct": { "fa": "General", "t": "g" }, "m": "value3", "bg": "rgba(255,255,255)", "bl": 0, @@ -538,10 +532,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 [ { "v": "vaule2", - "ct": { - "fa": "General", - "t": "g" - }, + "ct": { "fa": "General", "t": "g" }, "m": "vaule2", "bg": "rgba(255,255,255)", "bl": 0, @@ -554,10 +545,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 }, { "v": "value4", - "ct": { - "fa": "General", - "t": "g" - }, + "ct": { "fa": "General", "t": "g" }, "m": "value4", "bg": "rgba(255,255,255)", "bl": 0, @@ -637,9 +625,34 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 + {Number} [order]: 工作表索引；默认值为当前工作表索引 - **说明**： - + 复制指定工作表指定单元格区域的数据，返回`json`格式的数据 +- **示例**: + + - 当前选区为"A1:B2"，首行为标题取得json + + `luckysheet.getRangeJson(true)` + + 则返回结果为： + ```json + [ + { "A": "value1", "B": "value3" }, + { "A": "value2", "B": "value4" } + ] + ``` + + - 当前选区为"A1:B2"，首行不为标题取得json + + `luckysheet.getRangeJson(false)` + + 则返回结果为： + ```json + [ + { "value1": "value2", "value3": "value4" } + ] + ``` + ------------ ### getRangeArray(dimensional [,setting]) @@ -652,7 +665,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 + `"oneDimensional"`: 一维数组 + `"twoDimensional"`: 二维数组 - + `"custom"`: 自定义维数组 + + `"custom"`: 自定义行列数的二维数组 - {PlainObject} [setting]: 可选参数 + {Number} [row]: `dimensional`为`custom`的时候设置，多维数组的行数 + {Number} [column]: `dimensional`为`custom`的时候设置，多维数组的列数 @@ -661,10 +674,80 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 - **说明**： - 复制指定工作表指定单元格区域的数据，返回一维、二维或者自定义维数组格式的数据。 + 复制指定工作表指定单元格区域的数据，返回一维、二维或者自定义行列数的二维数组的数据。 特别注意，只有在`dimensional`设置为`custom`的时候，才需要设置`setting`中的`row`和`column` +- **示例**: + + - 当前选区为"A1:B2"，一维数组 + + `luckysheet.getRangeArray('oneDimensional')` + + 则返回结果为： + ```json + ["value1","value3","value2","value4"] + ``` + + - 当前选区为"A1:B2"，二维数组 + + `luckysheet.getRangeArray('twoDimensional')` + + 则返回结果为： + ```json + [ + [ "value1", "value3" ], + [ "value2", "value4" ] + ] + ``` + + - 当前选区为"A1:C5"，由 'value1'到'value15'的值组成，得到3 + 行2列的二维数组数据 + + `luckysheet.getRangeArray('custom', { row: 3, column: 2 })` + + 则返回结果为： + ```json + [ + [ + { + "m": "value1", + "ct": { "fa": "General", "t": "g" }, + "v": "value1" + }, + { + "ct": { "fa": "General", "t": "g" }, + "v": "value6", + "m": "value6" + } + ], + [ + { + "ct": { "fa": "General", "t": "g" }, + "v": "value11", + "m": "value11" + }, + { + "m": "value2", + "ct": { "fa": "General", "t": "g" }, + "v": "value2" + } + ], + [ + { + "ct": { "fa": "General", "t": "g" }, + "v": "value7", + "m": "value7" + }, + { + "ct": { "fa": "General", "t": "g" }, + "v": "value12", + "m": "value12" + } + ] + ] + ``` + ------------ ### getRangeDiagonal(type [,setting]) @@ -676,6 +759,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 `type`可能的值有： + `"normal"`: 对角线 + + `"anti"`: 反对角线 + `"offset"`: 对角线偏移 - {PlainObject} [setting]: 可选参数 - {Number} [column]: `type`为`offset`的时候设置，对角偏移的列数 @@ -688,6 +772,61 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 特别注意，只有在`type`设置为`offset`的时候，才需要设置`setting`中的`column`。 +- **示例**: + + - 当前选区为"A1:B2"，对角线 + + `luckysheet.getRangeDiagonal('normal')` + + 则返回结果为： + ```json + [ + { + "m": "value1", + "ct": { "fa": "General", "t": "g" }, + "v": "value1" + }, + { + "m": "value4", + "ct": { "fa": "General", "t": "g" }, + "v": "value4" + } + ] + ``` + + - 当前选区为"A1:B2"，反对角线 + + `luckysheet.getRangeDiagonal('anti')` + + 则返回结果为： + ```json + [ + { + "m": "value3", + "ct": { "fa": "General", "t": "g" }, + "v": "value3" + }, + { + "m": "value2", + "ct": { "fa": "General", "t": "g" }, + "v": "value2" + } + ] + ``` + - 当前选区为"A1:B2"，对角线偏移1列 + + `luckysheet.getRangeDiagonal('offset', { column: 1 })` + + 则返回结果为： + ```json + [ + { + "m": "value3", + "ct": { "fa": "General", "t": "g" }, + "v": "value3" + } + ] + ``` ------------ ### getRangeBoolean([setting]) @@ -702,6 +841,20 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 复制指定工作表指定单元格区域的数据，返回布尔值的数据 +- **示例**: + + - 当前选区为"A1:B2" + + `luckysheet.getRangeBoolean()` + + 则返回结果为： + ```json + [ + [ false, false ], + [ false, false ] + ] + ``` + ------------ ### setRangeShow(range [,setting])
@@ -757,6 +910,52 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 将一个单元格数组数据赋值到指定的区域，数据格式同`getRangeValue`方法取到的数据。 +- **示例**: + + + 赋值到当前选区 + + ```js + const data = [ + [ + { + "m": "value1", + "ct": { + "fa": "General", + "t": "g" + }, + "v": "value1" + }, + { + "m": "value3", + "ct": { + "fa": "General", + "t": "g" + }, + "v": "value3" + } + ], + [ + { + "m": "value2", + "ct": { + "fa": "General", + "t": "g" + }, + "v": "value2" + }, + { + "m": "value4", + "ct": { + "fa": "General", + "t": "g" + }, + "v": "value4" + } + ] + ] + luckysheet.setRangeValue(data) + ``` + ------------ ### setRangeFormat(attr, value [,setting]) @@ -791,9 +990,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 - **示例**: - 设置当前工作表`"A1:B2"`范围的单元格文本加粗 - `luckysheet.setRangeFormat("bl", 1, {range:"A1:B2"})` + + `luckysheet.setRangeFormat("bl", 1, {range:"A1:B2"})` - 设置第二个工作表的`"B2"`和`"C4:D5"`范围的单元格背景为红色 - `luckysheet.setRangeFormat("bg", "#ff0000", {range:["B2","C4:D5"], order:1})` + + `luckysheet.setRangeFormat("bg", "#ff0000", {range:["B2","C4:D5"], order:1})` ------------ @@ -825,6 +1026,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 ### setRangeMerge(type [,setting]) - **参数**： + - {String} [type]: 合并单元格类型 `type`可能的值有： @@ -832,6 +1034,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 + `"all"`: 全部合并，区域内所有单元格合并成一个大的单元格 + `"horizontal"`: 水平合并，区域内在同一行的单元格合并成一个单元格 + `"vertical"`: 垂直合并，区域内在同一列的单元格合并成一个单元格 + - {PlainObject} [setting]: 可选参数 + {Array | Object | String} [range]: 选区范围,支持选区的格式为`"A1:B2"`、`"sheetName!A1:B2"`或者`{row:[0,1],column:[0,1]}`，允许多个选区组成的数组；默认为当前选区 + {Number} [order]: 工作表索引；默认值为当前工作表索引 @@ -841,6 +1044,36 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 为指定索引的工作表，选定的范围设定合并单元格 +- **示例**: + + - 当前选区 'A1:B2' 设置为合并单元格，类型为全部合并 + + `luckysheet.setRangeMerge("all")` + 得到 'A1:B1' 的数据为： + ```json + [ + [ + { + "m": "value1", + "ct": { "fa": "General", "t": "g" }, + "v": "value1", + "mc": { "r": 0, "c": 0, "rs": 2, "cs": 2 } + }, + { + "mc": { "r": 0, "c": 0 } + } + ], + [ + { + "mc": { "r": 0, "c": 0 } + }, + { + "mc": { "r": 0, "c": 0 } + } + ] + ] + ``` + ------------ ### cancelRangeMerge( [setting]) @@ -856,6 +1089,12 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 为指定索引的工作表，选定的范围取消合并单元格 +- **示例**: + + - 当前选区 'A1:B2' 已为合并单元格，现在要取消合并 + + `luckysheet.cancelRangeMerge()` + ------------ ### setRangeSort(type [,setting]) @@ -1004,10 +1243,10 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 `luckysheet.setRangeConditionalFormatDefault("lastPercent",{ type: 'value', content: [15] })` - 突出显示高于平均值的单元格 - luckysheet.setRangeConditionalFormatDefault("AboveAverage",{ type: 'value', content: ['AboveAverage'] })` + `luckysheet.setRangeConditionalFormatDefault("AboveAverage",{ type: 'value', content: ['AboveAverage'] })` - 突出显示低于平均值的单元格 - luckysheet.setRangeConditionalFormatDefault("SubAverage",{ type: 'value', content: ['SubAverage'] })` + `luckysheet.setRangeConditionalFormatDefault("SubAverage",{ type: 'value', content: ['SubAverage'] })` ------------ @@ -1122,6 +1361,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 为指定索引的工作表，选定的范围开启条件格式，返回开启条件格式后的数据。 +- **示例**: + + - 当前选区范围开启条件格式，显示渐变色 + `luckysheet.setRangeConditionalFormat("dataBar", { format: ["#63c384", "#ffffff"] })` + ------------ ### deleteRangeConditionalFormat(itemIndex [,setting]) @@ -1142,7 +1386,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 - **示例**: - 删除第三个条件格式规则 - `luckysheet.editRangeConditionalFormat(2)` + `luckysheet.deleteRangeConditionalFormat(2)` ------------ @@ -1159,6 +1403,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 清除指定工作表指定单元格区域的内容，返回清除掉的数据，不同于删除选区的功能，不需要设定单元格移动情况 +- **示例**: + + - 清空当前选区内容 + `luckysheet.clearRange()` + ------------ ### deleteRange(move [,setting]) @@ -1180,6 +1429,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 删除指定工作表指定单元格区域，返回删除掉的数据，同时，指定是右侧单元格左移还是下方单元格上移 +- **示例**: + + - 删除当前选区并且在删除后，右侧单元格左移 + `luckysheet.deleteRange('left')` + ------------ ### insertRange(move [,setting]) @@ -1208,6 +1462,11 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 在指定工作表指定单元格区域，赋值单元格数据，或者新建一块空白区域，返回data数据，同时，指定活动单元格右移或者下移 +- **示例**: + + - 当前选区位置插入空白单元格，并且插入后当前选区单元格右移 + `luckysheet.insertRange('right')` + ------------ ### matrixOperation(type [,setting]) @@ -1237,6 +1496,20 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 指定工作表指定单元格区域的数据进行矩阵操作，返回操作成功后的结果数据 +- **示例**: + + - 当前选区上下翻转 + + `luckysheet.matrixOperation('flipUpDown')` + + 原来的选区复制为二维数组： + + `[["value1","value3"],["value2","value4"]]` + + 上下翻转后选区复制为二维数组： + + `[["value2","value4"],["value1","value3"]]` + ------------ ### matrixCalculation(type, number [,setting]) @@ -1253,9 +1526,6 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 + `"power"`: 次方 + `"root"`: 次方根 + `"log"`: log - + `"removeDuplicateByRow"`: 按行删除重复值 - + `"removeDuplicateByColumn"`: 按列删除重复值 - + `"newMatrix"`: 生产新矩阵 - {Number} [number]: 计算数值，如: 2 - {PlainObject} [setting]: 可选参数 + {Array | Object | String} [range]: 选区范围,支持选区的格式为`"A1:B2"`、`"sheetName!A1:B2"`或者`{row:[0,1],column:[0,1]}`，只能为单个选区；默认为当前选区 @@ -1266,6 +1536,20 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 指定工作表指定单元格区域的数据进行矩阵计算，返回计算成功后的结果数据 +- **示例**: + + - 当前选区所有单元格值加2 + + `luckysheet.matrixCalculation('plus', 2)` + + 原来的选区复制为二维数组： + + `[[1,2],[3,4]]` + + 加2后选区复制为二维数组： + + `[[3,4],[5,6]]` + ------------ ## 工作表操作 @@ -1509,7 +1793,7 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 - **说明**： - 初始化一个luckysheet，可包含多个工作表，参考 [配置列表](/zh/guide/config.html) + 初始化一个Luckysheet，可包含多个工作表，参考 [配置列表](/zh/guide/config.html) ------------ @@ -1526,6 +1810,19 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 ------------ +### destroy([setting]) + +- **参数**： + + - {PlainObject} [setting]: 可选参数 + + {Function} [success]: 表格释放成功后的回调函数 + +- **说明**： + + 删除并释放表格 + +------------ + ### getScreenshot([setting]) - **参数**： @@ -1682,12 +1979,43 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 celldata => data ，celldata一维数组数据转化成表格所需二维数组 ------------ + ## 旧版API ::: warning 为保持兼容性，仍然支持旧版API，但是已不推荐使用。 ::: +### getcellvalue([r] [,c] [,data] [,type]) +- **参数**： + - {Number} [r]:单元格所在行数；可选值；从0开始的整数，0表示第一行 + - {Number} [c]:单元格所在列数；可选值；从0开始的整数，0表示第一列 + - {Array} [data]:表数据，二维数组；可选值；默认值为当前表格数据 + - {String} [type]:单元格属性值；可选值；默认值为'v',表示获取单元格的实际值 +- **说明**： + + 此方法为获取单元格的值。 + + - luckysheet.getcellvalue()：返回当前工作表的所有数据； + - luckysheet.getcellvalue(0)：返回当前工作表第1行数据； + - luckysheet.getcellvalue(null,0)：返回当前工作表第1列数据； + - luckysheet.getcellvalue(0,0)：返回当前工作表第1行第1列单元格的数据的v值； + - luckysheet.getcellvalue(1,1,null,'m'): 返回指定data数据的第2行第2列单元格的原始值。 + + 特殊情况：单元格格式为yyyy-MM-dd，type为'v'时会强制取'm'显示值 + + > 推荐使用新API： getCellValue + + + +### getluckysheetfile() +- **说明**： + + 返回所有表格数据结构的一维数组`luckysheetfile` + + > 推荐使用新API： [getLuckysheetfile](#getLuckysheetfile()) +------------ + ### getconfig() - **说明**： @@ -1727,6 +2055,23 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 ------------ +## setcellvalue(r, c, d, v) +- **参数**： + - {Number} [r]：单元格所在行数；从0开始的整数，0表示第一行。 + - {Number} [c]：单元格所在列数；从0开始的整数，0表示第一列。 + - {Array} [d]：表数据；可选值；二维数组。 + - {Object | String | Number} [v]：要设置的值；可为对象，对象是是要符合单元格对象格式。 +- **说明**： + + 设置某个单元格的值。可配合`luckysheet.jfrefreshgrid()`刷新查看单元格值改变。 + + ```js + luckysheet.setcellvalue(0, 0, luckysheet.flowdata(), 'abc'); + luckysheet.jfrefreshgrid(); + ``` + +------------ + ## jfrefreshgrid() - **说明**： @@ -1734,7 +2079,6 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 > 推荐使用新API： [refresh](#refresh([setting])) - ------------ ## setluckysheet_select_save(v) @@ -1787,10 +2131,4 @@ Luckysheet针对常用的数据操作需求，开放了主要功能的API，开 二维数组数据转化成 `{r, c, v}` 格式 一维数组 - > 推荐使用新API：transToCellData - ------------- -## destroy() -- **说明**： - - 删除并释放表格 \ No newline at end of file + > 推荐使用新API：transToCellData \ No newline at end of file