append_row与append_rows方法的区别及正确用法示例

两个方法是表格操作库（最常见为gspread操作Google Sheets）中用于在工作表末尾追加数据的实例方法，核心差异是要求传入的参数结构、对应的追加数据规模完全不同：

• append_row 用于追加单行数据，入参要求是一维列表，列表内每个元素对应该行的一个单元格值。
  你之前能正常运行的写法完全符合参数要求：

  # 正确：传入一维列表，追加1行，两个单元格分别写入test、test2
  worksheet.append_row(['test', 'test2'])
  

  如果误给这个方法传入嵌套的二维列表，会把整个列表当成单个单元格的内容写入，出现格式错误。

• append_rows 用于批量追加多行数据，入参要求是二维嵌套列表：外层列表的每个元素是代表一整行的一维列表，内层一维列表的每个元素对应该行的单个单元格值。
  你之前直接传['test', 'test2']运行失败的原因非常明确：方法会把传入的一维列表识别为“多行数据集合”，遍历每个元素作为单独一行处理——而字符串本身是可迭代对象，会把'test'拆成t/e/s/t四个字符作为第一行的四个单元格，把'test2'拆成五个字符作为第二行，和预期效果完全不符，部分版本还会直接抛出参数格式错误。
  你后来写的可运行版本，刚好符合参数要求：

  test = ["test1", "test2", "test3"]
  # 正确：传入嵌套列表，外层列表仅1个元素（代表1行），这行三个单元格对应test的三个值
  val = worksheet.append_rows([test])
  

效果对比示例 #

假设当前工作表末尾无数据，从A列开始写入：

1. 用append_row实现写入2行数据，需要调用两次方法：

   # 追加第一行表头
   worksheet.append_row(["商品名", "价格", "库存"])
   # 追加第二行数据
   worksheet.append_row(["可乐", 3, 120])
   

2. 用append_rows实现完全相同的写入效果，仅需一次调用，批量传入所有行数据，大数据量场景下性能远高于多次调用单行追加：

   all_rows = [
       ["商品名", "价格", "库存"],
       ["可乐", 3, 120]
   ]
   worksheet.append_rows(all_rows)
   

两种写法最终写入的表格内容完全一致：

踩坑提示 #

• 哪怕用append_rows只追加1行数据，也必须把单行的一维列表包裹在外层列表中，写成[单行数据]的格式，不能直接传入一维列表，这是这个方法最常见的使用错误。
• 两个方法都需要通过具体的工作表实例（比如你代码里的worksheet对象）调用，不要直接用Worksheet类调用实例方法，否则会因为缺少实例绑定参数报错。

内容的提问来源于stack exchange，提问作者doyeop