📒 添加数据

本节介绍向Recorder对象添加数据。

Recorder支持非常灵活的数据输入，每次可接收单条或多条数据。

支持指定写入数据的位置，支持数据自动匹配表头。

✅️️ add_data()方法参数

使用add_data()方法添加任意数据。

数据格式可以是单个数据（如字符串'abc'）、一维数据（如['abc', 'def']）、二维数据（如[(1, 2, 3), (4, 5, 6)]）。

单个数据、一维数据视作一行，二维数据每个成员视作一行。

当传入数据是dict格式时（包括在二维数据中的dict），会自动匹配表头，存放到对应列（只支持 csv 和 xlsx）。

数据默认添加到活动数据表末尾，可指定数据表和坐标。

参数名称	类型	默认值	说明
data	Any	必填	插入的数据，任意格式
coord	str tuple int	None	要写入数据的坐标
table	str None True	None	要写入的数据表，仅支持 xlsx 格式。为None表示用set.table()方法设置的值，为True表示活动的表格

返回：None

说明

• coord参数在非 xlsx 和 csv文件时，只有行数据有效
• table参数只在 xlsx 文件时有效

✅️ 插入新行

最简单的插入数据是传入一维或二维数据，会添加到文件或活动数据表末尾。

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.add_data('abc')  # 单个数据，占一行
r.add_data(['a', 'b', 'c'])  # 一维数据，占一行
r.add_data([('a', 'b', 'c'),  # 二维数据，每条数据占一行
            ('d', 'e', 'f')])
r.record()

---

✅️ 指定数据表

xlsx 格式文件可指定把数据插入到某个数据表，这个功能在其它格式文件时无效。

可通过set.table()方法或add_data()方法的table参数指定。

此设置默认为None，表示活动数据表。

如果指定的数据表不存在，会自动创建。

📌 指定默认数据表

使用set.table()方法指定数据表后，后续添加的数据都会添加到这个数据表。

参数名称	类型	默认值	说明
name	str None True	必填	表名称，为None或Ture时表示活动数据表

返回类型	说明
RecorderSetter	设置对象

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.set.table('Sheet1')
r.add_data('abc')
r.record()

---

📌 每个数据独立指定数据表

add_data()方法的table参数可在每次插入数据时指定该数据所在数据表。

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.add_data('abc', table='Sheet1')
r.record()

---

✅️ 指定坐标

add_data()方法的coord参数可指定数据插入位置。

xlsx 和 csv 文件支持设置具体单元格，其它类型文件只支持设置写入数据的行。

📌 坐标格式

坐标支持以下三种格式：

• 'A1'：传统字符串格式坐标，不区分大小写
• (1, 1)：tuple格式，第一位是行，第二位是列，均为int
• 1：int格式指定某一行，列为set.data_col()设置的列号，默认1

以上三种格式中，数字如果是0，表示写入到新行或新列。

数字如果是负数，表示从后往前数，如-1为倒数第一列，列倒数时已header的长度为准，并非一定是表格真实列数。

如：(0, -3)表示新行倒数第三列；'a-1'表示新行倒数第一列；-1表示倒数第一行。

---

📌 绝对坐标

指定一个单元格，如'A3'、(3, 4)，把数据写入到以这个单元格为左上角的矩形区域。

from DrissionRecord import Recorder

r = Recorder('data.csv')
r.add_data(('a', 'b'), 'B2')  # 写入一维数据到B2单元格开始的区域
r.add_data(((1, 2, 3), (4, 5, 6)),
           coord=(3, 3))  # 写入二维数据到第三行第三列为左上角的矩形区域
r.record()

执行结果：

	a	b
		1	2	3
		4	5	6

---

📌 相对坐标

💡 坐标支持负数，表示从后向前数。

如(-1, -1)表示倒数第一行倒数第一列，也支持'A-1'形式。

倒数列号是以表头长度计算的，不是最大列数，这是为了避免不断向倒数第一列添加数据导致列数不断增加。

说明

如果倒数数字大于行数或列数，会设定数字为1。

from DrissionRecord import Recorder

r = Recorder('data.csv')
r.add_data('abc', (-1, -1))  # 添加数据到倒数第一行倒数第一列
r.record()

💡 0表示新行或新列。

如(0, 3)表示在新行第三列开始写入数据，(3, 0)表示在第三行新列开始写入。

新列是根据表头长度进行计算，这是为了避免不断向增加新列导致列数不断增加。

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.add_data('abc', (0, 3))  # 在新行第三列写入数据
r.record()

📌 默认数据列

可用set.data_col()方法设置默认写入列，之后坐标只要填行号就可以。

参数名称	类型	默认值	说明
col	str int	必填	列号或序号，0表示新列（表头长度后一列），不支持输入表头值

返回类型	说明
RecorderSetter	设置对象

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.set.data_col('c')
r.add_data('abc', 3)  # 写入到3行c列
r.record()

---

📌 非表格文件

txt、json、jsonl 文件写入数据时也支持设置坐标，但坐标中只有行参数有效。

说明

向 txt 写入多列数据，会使用空格分隔多列。

from DrissionRecord import Recorder

r = Recorder('data.txt')
r.add_data('abc', 3)  # 把数据写入第三行
r.add_data('abc', (5, 6))  # 写入行，无视列参数
r.record()

---

✅️ 自动匹配表头

处理 xlsx 和 csv 文件时可以根据设置读取表头，添加数据时使用dict传入可进行列的自动匹配。

表头可指定行号自动读取，也可以手动设置，有关功能在表头章节详细说明。

说明

• 如果dict中某个关键字在表头中不存在，该项不会被添加
• dict数据会自动匹配表头，如果不想进行自动匹配，可转为list或传入.values()数据
• 如果设置第 0 行为表头行，可用列号（如'A'）作为dict关键字进行匹配
• dict中可以数字作为关键字，匹配第几列，而无视表头设置，数字从 1 开始

💡 自动匹配表头示例：

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.set.header(('姓名', '性别', '年龄'))  # 设置表头
r.add_data({'姓名': '张三', '年龄': 25, '身高': 170})  # '身高'不会写入，因为表头中没有
r.record()

💡 匹配列序号示例：

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.add_data({1: '王五', 3: 30, 2: '女'})
r.record()

💡 匹配列号示例 1：

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.set.header_row(0)  # 设置第0行为表头行
r.add_data({'a': '李四', 'B': '男', 'c': 20})  # 匹配列号，不分大小写
r.record()

💡 匹配列序号示例 2：

如果表头行不设置为0，又想使用列号匹配，可导入Col()方法，把列序号转换为列号。

from DrissionRecord import Recorder, Col

r = Recorder('data.xlsx')
r.add_data({Col('a'): '李四', Col('B'): '男', Col('c'): 20})

---

✅️ 为每条数据添加固定前后缀

有时要为每条数据都录入同一些内容，比如日期。可设置before和after属性，自动在每条数据前后拼接上指定数据项。

before是在每条数据记录的时候在前面添加一些固定列，after则是在后面。

💡 set.before()方法和set.after()方法

参数名称	类型	默认值	说明
data	Any	必填	插入的数据，任意格式

返回类型	说明
RecorderSetter	设置对象

提醒

如果数据是dict，before和after设置也需要是dict才有效

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.set.before({'日期': '2025-06-10'})
r.set.after({'班级': '一班'})
r.add_data({'姓名': '张三', '身高': 175})
r.add_data({'姓名': '李四', '身高': 180})
r.record()

得到以下内容：

日期	姓名	身高	班级
2025-06-10	张三	175	一班
2025-06-10	李四	180	一班

---

✅️ xlsx 文件特有数据

xlsx 文件还可以添加链接、图片、设置单元格样式。

其中设置单元格样式在专门的章节介绍。

处理其它文件时调用这些方法不起任何效果。

📌 插入或删除链接

💡 add_link()

此方法用于向一个单元格添加超链接。

参数名称	类型	默认值	说明
link	str None	必填	超链接，为None时删除链接
coord	str tuple int	必填	要写入数据的坐标
content	Any	None	单元格内容，为None设置超链接文本
table	str None True	None	要写入的数据表，仅支持 xlsx 格式。为None表示用set.table()方法设置的值，为True表示活动的表格

返回：None

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.add_link('https://DrissionPage.cn', 'B3', 'DrissionPage')
r.record()

---

📌 插入或删除图片

💡 add_img()

此方法用于向一个单元格添加图片。

说明

使用此功能前必须先安装 Pillow 库。

pip install Pillow

参数名称	类型	默认值	说明
img_path	str Path	必填	图片路径
coord	str tuple int	必填	要写入数据的坐标
width	float	None	图片宽度，为None时高度按比例缩放
height	float	None	图片高度，为None时根据宽度按比例缩放
table	str None True	None	要写入的数据表，仅支持 xlsx 格式。为None表示用set.table()方法设置的值，为True表示活动的表格

返回：None

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.add_img('img.jpg', 'A3', width=200, height=100)  # 指定图片大小
r.add_img('img.jpg', 'B3', width=200)  # 指定图片宽度，高度自动按比例设置
r.add_img('img.jpg', 'C3', height=100)  # 指定图片高度，宽度自动按比例设置
r.record()