📒 基本用法

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

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

支持指定写入数据的位置，表格类型文件支持数据自动匹配表头。

✅️️ add_data()方法

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

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

• xlsx、csv 和 db 文件可用列表插入一维或二维列表数据。一维列表表示一行，二维列表表示多行。
• json 和 jsonl 文件每次只能插入一个数据。
• txt 文件可插入单个str表示一行，或用一维列表插入多行文本。
• xlsx、csv 和 db 文件当传入数据是dict格式时（包括在二维数据中的dict），会自动匹配表头，存放到对应列。

参数名称	类型	默认值	说明
data	Any	必填	插入的数据，任意格式
coord	str tuple int	None	要添加数据的坐标，不同格式文件用法不同
table	str None True	None	要写入的数据表，仅支持 xlsx、db 格式。为None表示用table属性的值，为True表示活动的表格

返回：None

---

✅️ 插入新数据

在data参数传入数据，而不指定coord参数，会将数据添加到文件或活动数据表末尾。 指定位置插入功能在各类文件单独章节介绍。

📌 添加单个或一维数据

除 byte 格式文件，将任意数据单一数据（如str）传入add_data()方法，可在文件末尾添加一条数据。

xlsx、csv、db、json、jsonl 文件可接收dict或一维列表添加一行数据。

from DrissionRecord import Recorder

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

xlsx、csv、db 文件可传入dict数据自动匹配表头。

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.add_data({'a': 1, 'b': 2, 'c': 3})  # 自动根据表头将数据填入对应列
r.record()

json 和 jsonl 格式文件每次只接收一条数据，列表也视作一条数据。

from DrissionRecord import Recorder

r = Recorder('data.jsonl')
r.add_data(['a', 'b', 'c'])
r.record()

---

📌 添加二维数据

xlsx、csv、db 格式文件可接收二维列表一次添加多行数据。

txt 类型文件添加str组成的一维列表，可一次添加多行。

注意

从 v2.0.0 开始，添加二维数据时，由于只调用了一次add_data()，缓存数据量也只增加 1。

from DrissionRecord import Recorder

r = Recorder('data.xlsx')
r.add_data([['a', 'b', 'c'],
            ['d', 'e', 'f'],
            {'a': 1, 'b': 2, 'c': 3}])  # 添加三行数据
r.record()

txt 文件用由str组成的一维列表添加多行数据：

from DrissionRecord import Recorder

r = Recorder('data.txt')
r.add_data(['aaa', 'bbb', 'ccc'])  # 添加三行数据
r.record()

---

📌 指定数据表

xlsx 和 db 文件可用set.table()或table参数指定插入数据表。

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

---

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

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

此功能不支持 byte 和 txt 文件。

💡 set.left()方法和set.right()方法

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

返回类型	说明
Setter	设置对象

提醒

如果数据是dict，left和right设置也需要是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	一班