📒 添加数据
本节介绍向Recorder对象添加数据。
Recorder支持非常灵活的数据输入，每次可接收单条 或多条数据。
支持指定写入数据的位置，支持数据自动匹配表头。
✅️️ add_data()方法参数
使用add_data()方法添加任意数据。
数据格式可以是单个数据（如字符串'abc'）、一维数据（如['abc', 'def']）、二维数据（如[(1, 2, 3), (4, 5, 6)]）。
单个数据、一维数据视作一行，二维数据每个成员视作一行。
当传入数据是dict格式时（包括在二维数据中的dict），会自动匹配表头，存放到对应列（只支持 csv 和 xlsx）。
数据默认添加到活动数据表末尾，可指定数据表和坐标。
| 参数名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
data | Any | 必填 | 插入的数据，任意格式 |
coord | strtupleint | None | 要添加数据的坐标，非 xlsx 或 csv 时无效，格式：'A3'格式坐标、(3, 1)或(3, '列名')格式坐标、int表示行号 |
table | strNoneTrue | 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 | strNoneTrue | 必填 | 表名称，为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, '表头值')：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()
📌 默认数据列
可用set.data_col()方法设置默认写入列，之后坐标只要填行号就可以。
| 参数名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
col | strint | 必填 | 表头名或列序号，列序号从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 文件写入数据时也支持设置坐标，但坐标中只有行参数有效。
向 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 | strNone | 必填 | 超链接，为None时删除链接 |
coord | strtupleint | 必填 | 要写入数据的坐标，格式详见上文 |
content | Any | None | 单元格内容，为None设置超链接文本 |
table | strNoneTrue | 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 | strPath | 必填 | 图片路径 |
coord | strtupleint | 必填 | 要写入数据的坐标，格式详见上文 |
width | float | None | 图片宽度，为None时高度按比例缩放 |
height | float | None | 图片高度，为None时根据宽度按比例缩放 |
table | strNoneTrue | 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()