跳转到主要内容
调用本接口，更新单元格信息，包括单元格中的值、背景色、超链接、字体大小、水平对齐方式、垂直对齐方式等。

​
请求

​
基本信息

字段值
HTTP URLhttps://api.dingtalk.io/v1.0/doc/workbooks/{workbookId}/sheets/{sheetId}/ranges/{rangeAddress}
HTTP MethodPUT
支持的应用类型appType-企业内部应用　appType-第三方企业应用
权限要求permission-Document.Workbook.Write-钉钉表格写权限

​
请求头

名称类型是否必填描述
x-acs-dingtalk-access-tokenString是调用该接口的访问凭证，可通过以下方式获取： - 企业内部应用，调用获取企业内部应用的accessToken接口获取。 - 第三方企业应用，调用获取第三方应用授权企业的accessToken接口获取。

​
路径参数

名称类型是否必填描述
workbookIdString是表格文件 ID ，知识库 API 返回的nodeId(dentryUuid)即是表格workbookId，可通过调用获取节点和创建知识库文档接口获取。
sheetIdString是工作表ID或名称。 - 企业内部应用，可调用获取所有工作表接口获取id或name参数值。 - 第三方企业应用，可调用创建工作表接口获取id和name。
rangeAddressString是Range地址。

​
查询参数

名称类型是否必填描述
operatorIdString是操作人的unionId，可调用查询用户详情接口获取。 若操作人无权限，接口会报错 The operator has no permission。

​
请求体

名称类型是否必填描述
horizontalAlignmentsArray of Array否水平对齐方式，可选值：为’left’-左对齐、‘center’-居中对齐、‘right’-右对齐、‘general’-默认对齐方式。 根据Range地址范围传参，格式为二维数组。详情请参考如下示例： Range地址范围有几行，该参数二维数组内就有几个元素；Range地址范围内有几列，该参数二维数组每个元素内就有几个值。 示例1：Range地址为A1:B3，范围内是一个三行两列的表格，该参数值格式如下： { "horizontalAlignments": [ ["left", "general"], ["center", "general"], ["right", "general"] ] } 示例2：Range地址为A1:C3，范围内是一个三行三列的表格，该参数值格式如下： { "horizontalAlignments": [ ["left", “left”, "general"], ["center", "center", "general"], ["right", "right", "general"] ] }
numberFormatString否数字格式。---------名称数字格式示例常规”General”文本”@“数字”#,##0”1,234数字（小数点）”#,##0.00”1,234.56百分数”0%“12%百分数（小数点）“0.00%“12.34%科学计数”0.00E+00”1.01E+03人民币”¥#,##0”¥1,234人民币（小数点）¥#,##0.00”¥1,234.56美元”$#,##0”$1,234美元（小数点）”$#,##0.00”$1,234.56日期”yyyy/m/d”2022/1/1日期（中文）“yyyy年m月d日”2022年1月1日日期（中文年月）“yyyy年m月”2022年1月时间”hh:mm:ss”00:00:00日期时间”yyyy/m/d hh:mm:ss”2022/1/1 00:00:00
wordWrapString否换行方式，可选值： - overflow：溢出 - clip：截断 - autoWrap：自动换行
valuesArray of Array否单元格的值，根据Range地址范围传参，格式为二维数组。详情请参考如下示例： Range地址范围有几行，该参数二维数组内就有几个元素；Range地址范围内有几列，该参数二维数组每个元素内就有几个值。 示例1：Range地址为A1:B3，范围内是一个三行两列的表格，该参数值格式如下： { "values": [ ["1", "2"], ["3", "4"], ["5", "6"] ] } 示例2：Range地址为A1:C3，范围内是一个三行三列的表格，该参数值格式如下： { "values": [ ["1","2","3"], ["4","5","6"], ["7","8","9"] ] }
complexValuesArray of Array否单元格的值，根据Range地址范围传参，格式为二维数组。 可通过该字段，给对应单元格填入「富文本格式」的内容，详见后续附录。
backgroundColorsArray of Array否背景色，颜色的16进制值，根据Range地址范围传参，格式为二维数组。详情请参考如下示例： Range地址范围有几行，该参数二维数组内就有几个元素；Range地址范围内有几列，该参数二维数组每个元素内就有几个值。 示例1：Range地址为A1:B3，范围内是一个三行两列的表格，该参数值格式如下： { "backgroundColors": [ ["#ff0000", "#00ff00"], ["#f0f0f0", "#0000ff"], ["#f0f0f0", "#0000ff"] ] } 示例2：Range地址为A1:C3，范围内是一个三行三列的表格，该参数值格式如下： { "backgroundColors": [ ["#ff0000","#ff0000","#ff0000"], ["#ff0000","#ff0000","#ff0000"], ["#ff0000","#ff0000","#ff0000"] ] }
fontColorsArray of Array否字体颜色，颜色的16进制值，根据Range地址范围传参，格式为二维数组。
fontSizesArray of Array否字体大小，根据Range地址范围传参，格式为二维数组。详情请参考如下示例： Range地址范围有几行，该参数二维数组内就有几个元素；Range地址范围内有几列，该参数二维数组每个元素内就有几个值。 示例1：Range地址为A1:B3，范围内是一个三行两列的表格，该参数值格式如下： { "fontSizes": [ [14, 14], [15, 15], [10, 10] ] } 示例2：Range地址为A1:C3，范围内是一个三行三列的表格，该参数值格式如下： { "fontSizes": [ [14, 14, 14], [15, 15, 15], [10, 10, 10] ] }
fontWeightsArray of Array否字体粗细，可选值： - bold：加粗 - normal：正常
hyperlinksArray of Array否超链接，根据Range地址范围传参，格式为二维数组。详情请参考如下示例： Range地址范围有几行，该参数二维数组内就有几个元素；Range地址范围内有几列，该参数二维数组每个元素内就有几个值。 示例1：Range地址为A1:B3，范围内是一个三行两列的表格，该参数值格式如下： { "hyperlinks": [ [ { "type": "path", "link": "https://www.dingtalk.io", "text": "test" }, { "type": "sheet", "link": "Sheet2", "text": "测试" } ], [ { "type": "range", "link": "Sheet2!A4", "text": "test" }, { "type": "path", "link": "https://www.dingtalk.io", "text": "测试" } ], [ { "type": "range", "link": "Sheet2!A4", "text": "2" }, { "type": "sheet", "link": "Sheet2", "text": "测试" } ] ] } 示例2：Range地址为A1:C3，范围内是一个三行三列的表格，该参数值格式如下： { "hyperlinks": [ [ { "type": "path", "link": "https://www.dingtalk.io", "text": "test" }, { "type": "sheet", "link": "Sheet2", "text": "测试" },{ "type": "path", "link": "https://www.dingtalk.io", "text": "test" } ], [ { "type": "range", "link": "Sheet2!A4", "text": "test" }, { "type": "path", "link": "https://www.dingtalk.io", "text": "测试" },{ "type": "path", "link": "https://www.dingtalk.io", "text": "test" } ], [ { "type": "range", "link": "Sheet2!A4", "text": "2" }, { "type": "sheet", "link": "Sheet2", "text": "测试" },{ "type": "path", "link": "https://www.dingtalk.io", "text": "test" } ] ] }
verticalAlignmentsArray of Array否垂直对齐方式，可选值：为’top’-顶部对齐、‘middle’-垂直居中、‘bottom’-底部对齐。 根据Range地址范围传参，格式为二维数组。详情请参考如下示例： Range地址范围有几行，该参数二维数组内就有几个元素；Range地址范围内有几列，该参数二维数组每个元素内就有几个值。 示例1：Range地址为A1:B3，范围内是一个三行两列的表格，该参数值格式如下： { "verticalAlignments": [ ["top", "top"], ["middle", "middle"], ["bottom", "bottom"] ] } 示例2：Range地址为A1:C3，范围内是一个三行三列的表格，该参数值格式如下： { "verticalAlignments": [ ["top", "top", "top"], ["middle", "middle", "middle"], ["bottom", "bottom", "bottom"] ] }

​
请求示例

HTTP 
PUT /v1.0/doc/workbooks/e54Lqxxxxx/sheets/Sheet1/ranges/A1:B1?operatorId=ppgAQuxxxxx HTTP/1.1
Host:api.dingtalk.io
x-acs-dingtalk-access-token:f86e0bxxx
Content-Type:application/json

{
  "horizontalAlignments" : [ [ "general" ] ],
  "numberFormat" : "@",
  "wordWrap" : "autoWrap",
  "values" : [ [ "text" ] ],
  "complexValues" : [ [ "text" ] ],
  "backgroundColors" : [ [ "#ff0000" ] ],
  "fontColors" : [ [ "#000000" ] ],
  "fontSizes" : [ [ 14 ] ],
  "fontWeights" : [ [ "bold" ] ],
  "hyperlinks" : [ [ {
    "type" : "path",
    "link" : "https://www.dingtalk.io",
    "text" : "DingTalk"
  } ] ],
  "verticalAlignments" : [ [ "middle" ] ]
}

​
响应

​
响应体

名称类型描述
a1NotationString被更新的range地址。

​
响应体示例

HTTP/1.1 200 OK
Content-Type:application/json

{
  "a1Notation" : "A1"
}

​
错误码

若调用该接口报错，可根据错误信息在全局错误码文档中查找解决方案。
HttpCode错误码错误信息说明
400invalidRequest.inputArgs.invalid%s请求参数不合法，请查看错误信息。
400invalidRequest.inputArgs.workbookIdIllegalThe workbookId is illegal.workbookId不合法。
400invalidRequest.resource.notWorkbook%s不支持的文档类型，请检查workbookId。
403forbidden.accessDeniedThe operator has no permission.当前用户无此操作权限。
403forbidden.acrossOrg%s请求不合法，请检查要访问的文档是否归属于accessToken指定的组织。
403forbidden.operationIllegal%s请求操作不合法，请查看错误信息。
403forbidden.document.sizeOverLimitThe document size is over limit and the server is unable to complete your request. Retry is unlikely to work unless the document size is decreased.表格内容过大，请尝试缩减表格内容。
404invalidRequest.resource.notFound%s请求失败，无法找到要访问的资源。
500serviceBusyThe server is busy and unable to complete your request. Please try again later.服务繁忙，请稍后重试。
500internalErrorThe server encountered an internal error and was unable to complete your request. Please try again later.服务内部错误，请稍后再试。