wecomteam--wecom-cli/skills/wecomcli-sheet/references/sheet-append-data.md

sheet sheet_append_data API

向在线表格的指定子工作表末尾自动追加一行数据，无需指定行号——数据将写到最末一行之后。适合逐行写入。

命令

wecom-cli doc sheet_append_data '<JSON 参数>'

参数说明

参数	类型	必填	说明
docid	string	是	在线表格 ID
sheet_id	string	是	工作表 ID，通过 sheet sheet_get_info 获取
row	object	是	追加的一行数据
row.values	array	是	单元格数组，按列顺序排列

row.values[] 对象结构：

子字段	类型	说明
cell_value	object	单元格值，形如 {"text": "<文本>"} / {"link": {"url": "<URL>", "text": "<显示文本>"}} / {"formula": "=SUM(A1,A2)"}
cell_format	object	单元格样式；传空对象 {} 表示默认样式

返回字段

字段	类型	说明
row	object	写入的行数据，结构与入参 row 一致

请求示例

{
    "docid": "DOCID",
    "sheet_id": "SHEET_ID",
    "row": {
        "values": [
            { "cell_value": { "text": "新任务" }, "cell_format": {} },
            { "cell_value": { "text": "李四" }, "cell_format": {} }
        ]
    }
}

响应示例

{
    "errcode": 0,
    "errmsg": "ok",
    "row": {
        "values": [
            { "cell_value": { "text": "新任务" } },
            { "cell_value": { "text": "李四" } }
        ]
    }
}

使用规则

• 逐行写入场景：本接口会自动定位到子表最末一行之后追加；批量写不同区域请用 sheet_update_range_data。
• 读 → 写 链路：写入前先用 get_doc_content 识别出目标子表的标题与具体数据，再用 sheet sheet_get_info 拿到 sheets[]，按子表标题匹配 title 确定 sheet_id，并参考其 column_count 核对每行单元格数量与列对齐。