如何使用Xlsxwriter 1.2.9为Excel图表添加垂直线？

问题背景 #

需要为使用Xlsxwriter==1.2.9开发的Excel图表添加类似下图的垂直线：

此前尝试的代码因格式错误未达到预期，代码如下：

chart.add_series({'name': 'Vertical Line',
                  'values':f"{sheet_name,2,5,2,5}",
                  'line': {'width': 2.5, 'dash_type': 'dash', 'color': '#9ED8D2'}})

解决方案 #

在Xlsxwriter中添加垂直线需采用组合图表方式，将垂直线作为独立折线图系列添加，具体实现步骤如下：

1. 核心思路 #

垂直线本质是X坐标相同、Y坐标覆盖图表全范围的折线图系列。只需定义两个端点：一个对应Y轴最小值，一个对应Y轴最大值，X轴为目标位置。

2. 正确代码示例 #

import xlsxwriter

# 创建工作簿与工作表
workbook = xlsxwriter.Workbook('chart_with_vline.xlsx')
worksheet = workbook.add_worksheet()
sheet_name = worksheet.get_name()

# 示例业务数据
categories = ['Jan', 'Feb', 'Mar', 'Apr', 'May']
values = [10, 20, 30, 25, 40]

# 写入数据到工作表
worksheet.write_row('A1', categories)
worksheet.write_row('A2', values)

# 定义垂直线的Y轴范围（覆盖图表Y轴区间）
y_min = 0
y_max = 45
# 若不想写入工作表，可直接在系列中用数组，无需这两行
worksheet.write('C1', y_min)
worksheet.write('C2', y_max)

# 创建主图表（以柱形图为例）
chart = workbook.add_chart({'type': 'column'})

# 添加主数据系列
chart.add_series({
    'name': '销售额',
    'categories': f'{sheet_name}!$A$1:$E$1',
    'values': f'{sheet_name}!$A$2:$E$2',
})

# 添加垂直线系列（折线图类型）
chart.add_series({
    'name': '垂直线',
    # X轴指定垂直线位置，这里对应Mar的位置，可按需调整
    'categories': f'={sheet_name}!$C$1:$C$1',
    # Y轴取最小与最大值，形成垂直直线
    'values': f'{sheet_name}!$C$1:$C$2',
    'type': 'line',
    'line': {'width': 2.5, 'dash_type': 'dash', 'color': '#9ED8D2'},
})

# 配置图表参数（可选）
chart.set_title({'name': '带垂直线的销售额图表'})
chart.set_y_axis({'min': y_min, 'max': y_max})

# 插入图表到工作表
worksheet.insert_chart('A4', chart)

workbook.close()

3. 关键注意事项 #

• 单元格范围格式：必须使用sheet_name!$X$Y:$X$Y格式，此前代码中f"{sheet_name,2,5,2,5}"会生成元组字符串，不是Xlsxwriter识别的范围格式。
• 无工作表数据写法：若不想在工作表中存储Y轴极值，可直接用数组定义系列：

  'x_values': [2],  # X轴位置索引（对应第3个分类Mar，索引从0开始）
  'values': [y_min, y_max],
  

内容的提问来源于stack exchange，提问作者Jai Simha Ramanujapura