📒 添加数据

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

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

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

✅️️ add_data()方法参数

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

xlsx 和 csv 文件可用列表插入一维或二维列表数据。一维列表表示一行，二维列表表示多行。

json 和 jsonl 文件每次只能插入一个数据。

txt 文件可插入单个str表示一行，或用一维列表插入多行文本。

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

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

参数名称	类型	默认值	说明
data	Any	必填	插入的数据，任意格式
coord	str tuple int	None	要添加数据的坐标，格式：'A3'格式坐标、(3, 1)或(3, '列名')格式坐标、int表示行号，非 xlsx 或 csv 时只有行号有效
table	str None True	None	要写入的数据表，仅支持 xlsx、json 格式。为None表示用set.table()方法设置的值，为True表示活动的表格

返回：None

✅️ 插入新行

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

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 和 json 文件可用set.table()或table参数指定插入数据表（xlsx）或数据块（json）。

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.set.table('sheet1')
r.add_data('abc')  # 添加到sheet1
r.add_data('123', table='sheet2')  # 添加到sheet2
r.record()

---

✅️ 向指定坐标写入数据

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

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

📌 坐标格式

坐标支持以下格式：

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

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

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

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

当要用列号指定列，如'D'，应引入Col()函数进行转换。

from DrissionRecord import Recorder, Col

r = DrissionRecord('test.xlsx')
r.add_data('abc', (1, Col('D')))  # 把数据添加到D1单元格
r.record()

---

📌 绝对坐标

指定一个单元格，如'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()

📌 默认数据列

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

参数名称	类型	默认值	说明
col	str int	必填	表头名或列序号，列序号从1开始，负数表示从后往前数，0表示新列（表头长度后一列），用Col('A')形式输入列号

返回类型	说明
RecorderSetter	设置对象

from DrissionRecord import Recorder, Col

r = Recorder('data.xlsx')
r.set.data_col('ccc')
r.add_data('abc', 3)  # 写入到第3行表头为ccc的列
r.set.data_col(Col('D'))
r.add_data('abc', 4)  # 写入到第4行表头D列
r.record()

---

📌 非表格文件

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

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 格式文件可指定把数据插入到某个数据表。

可通过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()

---

✅️ 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()

---

✅️ json 文件格式

程序对写入的 json 文件有格式要求，支持list格式，或{'键': [数据]}形式的dict数据。

当文件格式为后者时，可用set.table()方法或add_data()方法的table参数指定要把数据添加到哪个键值下。

当为前者时，直接把新数据插入其中。如果有指定table，会自动把文件修改为后一种格式，原有数据保存在"null"键值下。

有如下 json 文件：

[
  [1, 2, 3],
  [4, 5, 6]
]

from DrissionRecord import Recorder

r = Recorder('data.json')
r.add_data(['a', 'b', 'c'], table='字母')
r.record()

结果：

{
  "null": [[1, 2, 3], [4, 5, 6]], 
  "字母": [["a", "b", "c"]]
}