Python文档主题
write_xl() 函数
通过 write_xl 函数将数据回写到工作表。
注意
支持将一维和二维的容器对象，如 list tuple set dict 回写到工作表，不支持更高维度的容器的回写。
提示
一维容器对象：向量表示，容器中不包含其它容器；
二维容器对象：矩阵，容器中的元素为只包含标量的容器。
提示
不同类型的数据回写时处理逻辑是不同的。请参考示例部分获取更多信息。
函数签名
python
def write_xl(data: object,
range: str = "",
new_sheet: bool = False,
sheet_name: str = "",
overfill: bool = True,
book_url: str = "",
start_row: int | None = None,
start_column: int | None = None,
write_df_index: bool = False) -> None:
参数列表
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| data | object | 必填 | 要回写到工作表里的数据。 支持的数据类型包括： Python 基本数据类型； 维度不超过2维的容器类型，如： list 和 tuple；pandas.DataFrame；不支持写入图片。 |
| range | str | 空字符串 | 工作表中的选区描述。 可以为一个单元格。为要写入数据的选区的左上角。 当 new_sheet=True时可以为空。默认为新工作表的A1位置。 |
| new_sheet | bool | False | 是否将数据写入到新建的工作表中。 |
| sheet_name | str | 空字符串 | 写入数据的选区所在的工作表名称。 当 new_sheet=False 时为表格中已经存在的工作表名称。当 new_sheet=True 时为新建的工作表的名称。 |
| overfill | bool | True | 当 range 不足以容纳 data 时，是否允许超出部分继续写入。如果设置为 False 超出 range 的 data 部分会被丢弃。 |
| book_url | str | 字符串 | 指定写入的表格文件地址。 必须为金山文档云文档地址。 默认当前表格。 |
| start_row | int | 空值 | 选区左上单元格的行，从0开始 |
| start_column | int | 空值 | 选区左上单元格的列，从0开始 |
| write_df_index | bool | False | 是否写入pandas.DataFrame里的index列 |
示例
1. 将字符串、数字回写到工作表。
python
# 将 s 回写到当前工作表的 A1 单元格
s = "hello world"
write_xl(s, "A1")
# 将 i 回写到工作表2的 B1 单元格
i = 100
write_xl(i, "B1", sheet_name="工作表2")
# 将 f 回写到新建的工作表中的 C1 单元格
f = 0.1
writre_xl(f, "C1", new_sheet = True)
2. 将 pandas.DataFrame 回写到工作表。
提示
将 DataFrame 回写到工作表时，是按照数据在 DataFrame 中的相对位置（行/列）进行写入的。如果设置了 overfill=False 超过选区 range 的部分会被丢弃。
python
import pandas as pd
# 构造一个有 columns 的 DataFrame
df = pd.DataFrame({"Name": ["foo", "bar", "baz"], "Age": [1, 2, 3]})
# 将 df 写入到当前工作表的 A1 位置
# 由于 df 中包含 columns 定义
# 最终会写入到 A1:B4 选区
# 相当于第1行是表头，其余3行为数据
# +-------+-----+
# | Name | Age |
# +-------+-----+
# | foo | 1 |
# +-------+-----+
# | bar | 2 |
# +-------+-----+
# | baz | 3 |
# +-------+-----+
write_xl(df, "A1")
# 构造一个无 columns 的 DataFrame
df2 = pd.DataFrame([["foo", 1], ["bar", 2], ["baz", 3]])
# 将 df2 写入到当前工作表的 A1 位置
# 由于 df2 中没有 columns（未显式定义，默认使用 pandas.RangeIndex）
# 最终会写入到 A1:B3 选区
# 相当于没有表头，只有3行数据
# +-------+-----+
# | foo | 1 |
# +-------+-----+
# | bar | 2 |
# +-------+-----+
# | baz | 3 |
# +-------+-----+
write_xl(df2, "A1")
# 也可以单独回写某个 series，行为与只有一个“列”的 DataFrame 一致
write_xl(df['name'], "A1:B1")
3. 将 list、tuple和set回写到工作表。
提示
示例中仅包含 list。set和tuple的逻辑与list一致。
- 将一维
list、tuple和set回写到工作表。
注意
当 range 是一个矩阵（例如：“A1:C10”），如果list或tuple或set中包含的数据长度（len()函数返回的长度）大于range选区的大小，且overfill=True会返回错误并写入失败。因为此时无法推断出要向工作表的哪个方向（行/列）去做扩张。
python
# 构造一个有10个元素的 list
l = [i for i in range(10)]
# 将 l 回写到以 A1 开头的一行中
# +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
# | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
# +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
write_xl(l, "A1")
# 将 l 回写到当前工作表的 A1:C1 区域
# 即将 l 回写成工作表中的一行
# 但是此时 A1:C1 选区不足以容纳 10 个元素
# 且 overfill=False 截断 l 中的元素
# +-----+-----+-----+
# | 0 | 1 | 2 |
# +-----+-----+-----+
write_xl(l, "A1:C1", overfill=False)
# 将 l 回写到当前工作表的 A1：A10 区域
# 与之前的示例相同，即将 l 回写成工作表中的一列
# +-----+
# | 0 |
# +-----+
# | 1 |
# +-----+
# | 2 |
# +-----+
# | 3 |
# +-----+
# | 4 |
# +-----+
# | 5 |
# +-----+
# | 6 |
# +-----+
# | 7 |
# +-----+
# | 8 |
# +-----+
# | 9 |
# +-----+
write_xl(l, "A1:A10")
# 将 l 回写到当前工作表的 A1:E2 区域
# 即将 l 回写成工作表中2行*5列
# 此时要求 l 的长度必须不大于选区的长度
# 否则无法判断该如何写入数据，导致报错
# +-----+-----+-----+-----+-----+
# | 0 | 1 | 2 | 3 | 4 |
# +-----+-----+-----+-----+-----+
# | 5 | 6 | 7 | 8 | 9 |
# +-----+-----+-----+-----+-----+
write_xl(l, "A1:E2")
- 将二维
list、tuple和set回写到工作表。
注意
容器中的元素会被处理成工作表的一个行。
python
# 构造一个二维的 list
data = [["foo", 1], ["bar", 2], ["baz", 3]]
# 将 data 回写到当前工作表的 A1 位置
# 将会在工作表中写入如下数据：
# data 中的每一个子列表，被处理成工作表中的一行
# +-------+-----+
# | foo | 1 |
# +-------+-----+
# | bar | 2 |
# +-------+-----+
# | baz | 3 |
# +-------+-----+
write_xl(data, "A1")
4. 将dict回写到工作表。
注意
dict的key被当作表头中的列名；value被处理成一列数据。
python
# 构造一个一维的 dict
data = {"Name": "foo", "Age": 1}
# 将 data 回写到当前工作表的 A1 位置
# 将会在表个中写入如下数据：
# +-------+-----+
# | Name | Age |
# +-------+-----+
# | foo | 1 |
# +-------+-----+
write_xl(data, "A1")
# 构造一个一维的 dict
data = {"Name": "fox", "Age": 2}
# 以第0行0列开始，将 data 回写到指定book_url的工作表
# 将会在表个中写入如下数据：
# +-------+-----+
# | Name | Age |
# +-------+-----+
# | fox | 2 |
# +-------+-----+
write_xl(data, book_url="https://kdocs.cn/l/foo", start_row=0, start_column=0)
# 构造一个二维的 dict
data = {'Name': ['foo', 'bar', 'baz'], 'Age': [1, 2, 3]}
# 将 data 回写到当前工作表的 A1 位置
# 将会在工作表中写入如下数据：
# +-------+-----+
# | Name | Age |
# +-------+-----+
# | foo | 1 |
# +-------+-----+
# | bar | 2 |
# +-------+-----+
# | baz | 3 |
# +-------+-----+
write_xl(data, "A1")