Plotly.py 交互式时间序列:Range Slider 与 Range Selector 完整配置指南

原创2026-09-20 15:52:331,939 阅读
文章标签:图表库数据可视化前端

Plotly.py 交互式时间序列:Range Slider 与 Range Selector 完整配置指南

本指南基于 plotly.py 官方文档 doc/python/range-slider.md,系统讲解如何在 Python 中为图表添加范围滑块(Range Slider)与范围选择按钮(Range Selector),实现纯 Python 驱动的交互式时间轴缩放。读完本文你将掌握 layout.xaxis.rangeselector 与 layout.xaxis.rangeslider 的完整属性体系、step/stepmode 语义,以及如何在多子图场景下叠加滑块与选区。

一、功能定位:什么是 Range Slider 与 Range Selector

Range Slider 是绘制在图表底部的一个迷你总览条,用户可以通过拖动滑动手柄快速缩放主绘图区的时间范围;Range Selector 则是一组预设按钮(如"1m""6m""YTD""1y"),点击即可一键切换到对应时间窗口。二者均挂在 xaxis 下,且仅对类型为 date(或自动推断为日期)的 x 轴生效——这一点可以从 Rangeselector 的源码文档 中的 visible 属性描述得到印证:"range selectors are only available for x axes of type set to or auto-typed to 'date'"。

在 plotly.py 中,它们对应两类图对象层级:

默认情况下,rangeslider 是隐藏的(visible 默认为 False),但在蜡烛图(candlestick)和 OHLC 图等金融图表中会自动开启,若想关闭可参考 candlestick-charts.md 与 ohlc-charts.md 中的写法:fig.update_layout(xaxis_rangeslider_visible=False),这一行代码也展示了 plotly.py 支持以扁平化的下划线语法直接访问嵌套属性。

二、基础示例:苹果股价时间序列 + 滑块与选择器

原文档第一个示例使用 Apple 金融数据(finance-charts-apple.csv),完整代码如下:

import plotly.graph_objects as go

import pandas as pd

# Load data
df = pd.read_csv(
    "https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv")
df.columns = [col.replace("AAPL.", "") for col in df.columns]

# Create figure
fig = go.Figure()

fig.add_trace(
    go.Scatter(x=list(df.Date), y=list(df.High)))

# Set title
fig.update_layout(
    title_text="Time series with range slider and selectors"
)

# Add range slider
fig.update_layout(
    xaxis=dict(
        rangeselector=dict(
            buttons=list([
                dict(count=1,
                     label="1m",
                     step="month",
                     stepmode="backward"),
                dict(count=6,
                     label="6m",
                     step="month",
                     stepmode="backward"),
                dict(count=1,
                     label="YTD",
                     step="year",
                     stepmode="todate"),
                dict(count=1,
                     label="1y",
                     step="year",
                     stepmode="backward"),
                dict(step="all")
            ])
        ),
        rangeslider=dict(
            visible=True
        ),
        type="date"
    )
)

fig.show()

执行后,图表底部会出现可拖动的迷你时间轴(Range Slider),其上方带有一排"1m / 6m / YTD / 1y / all"按钮(Range Selector)。注意 type="date" 被显式声明,这正是滑块与按钮生效的前提条件。

按钮核心参数解析

每个按钮对应 Button 类 的一个实例,其 _valid_props 声明了 count、label、step、stepmode、visible、name、templateitemname 等属性,其中与时间窗口计算直接相关的是前四个:

参数 取值 含义(依据源码属性文档)
count 非负整数/浮点数(区间 [0, inf]) 更新范围所需的步数,与 step 配合指定更新间隔
label 字符串或可转字符串的数字 按钮上显示的文字
step 'month' 'year' 'day' 'hour' 'minute' 'second' 'all' count 值的计量单位;'all' 表示显示全部范围
stepmode 'backward'、'todate' 范围更新模式(见下文)

stepmode 的两种取值语义在源码中描述得非常清晰:

  • backward:将范围起点向前(向过去)回退 count × step 毫秒。例如 count=1, step="month", stepmode="backward" 表示显示最近一个月;
  • todate:将范围起点回退到"从 count × step 之前算起的第一个时间戳"。例如 count=1, step="year", stepmode="todate"(即示例中的 YTD)会把起点对齐到当年 1 月 1 日。源码同时注明:month 和 year 的 todate 模式目前仅适用于内置的格里高利(Gregorian)历法。

示例中五个按钮的含义分别是:近 1 个月(1m)、近 6 个月(6m)、年初至今(YTD,todate 对齐到当年 1 月 1 日)、近 1 年(1y)、全部数据(all)。

三、进阶示例:垂直堆叠子图 + 滑块 + 标注与形状

原文档第二个示例演示了更复杂的场景:五个垂直堆叠的子图(共享 x 轴)共用底部一个 Range Slider,同时叠加状态标注(annotations)和矩形色带(shapes)。完整代码较长,核心结构如下:

import plotly.graph_objects as go

# Create figure
fig = go.Figure()

# Add traces(五条轨迹,分别绑定 yaxis="y"~"y5")
fig.add_trace(go.Scatter(
    x=["2013-01-15", "2013-01-29", "2013-02-26", "2013-04-19", "2013-07-02",
       "2013-08-27", "2013-10-22", "2014-01-20", "2014-05-05", "2014-07-01",
       "2015-02-09", "2015-04-13", "2015-05-13", "2015-06-08", "2015-08-05",
       "2016-02-25"],
    y=["8", "3", "2", "10", "5", "5", "6", "8", "3", "3", "7", "5", "10", "10", "9", "14"],
    name="var0",
    text=["8", "3", "2", "10", "5", "5", "6", "8", "3", "3", "7", "5", "10", "10", "9", "14"],
    yaxis="y",
))
# var1 → yaxis="y2"(日期更短的轨迹)
# var2 → yaxis="y3"
# var3 → yaxis="y4"
# var4 → yaxis="y5"

# style all the traces
fig.update_traces(
    hoverinfo="name+x+text",
    line={"width": 0.5},
    marker={"size": 8},
    mode="lines+markers",
    showlegend=False
)

# Add annotations(状态注释,带箭头)
fig.update_layout(
    annotations=[
        dict(x="2013-06-01", y=0, arrowcolor="rgba(63, 81, 181, 0.2)",
             arrowsize=0.3, ax=0, ay=30, text="state1",
             xref="x", yanchor="bottom", yref="y"),
        dict(x="2014-09-13", y=0, arrowcolor="rgba(76, 175, 80, 0.1)",
             arrowsize=0.3, ax=0, ay=30, text="state2",
             xref="x", yanchor="bottom", yref="y"),
    ],
)

# Add shapes(状态色带)
fig.update_layout(
    shapes=[
        dict(fillcolor="rgba(63, 81, 181, 0.2)", line={"width": 0}, type="rect",
             x0="2013-01-15", x1="2013-10-17", xref="x", y0=0, y1=0.95, yref="paper"),
        dict(fillcolor="rgba(76, 175, 80, 0.1)", line={"width": 0}, type="rect",
             x0="2013-10-22", x1="2015-08-05", xref="x", y0=0, y1=0.95, yref="paper"),
    ]
)

# Update axes(xaxis 挂载 rangeslider;yaxis1~yaxis5 按 domain 分段堆叠)
fig.update_layout(
    xaxis=dict(
        autorange=True,
        range=["2012-10-31 18:36:37.3129", "2016-05-10 05:23:22.6871"],
        rangeslider=dict(
            autorange=True,
            range=["2012-10-31 18:36:37.3129", "2016-05-10 05:23:22.6871"]
        ),
        type="date"
    ),
    yaxis=dict(anchor="x", domain=[0, 0.2], ...),   # 第 1 个 20% 高度
    yaxis2=dict(anchor="x", domain=[0.2, 0.4], ...),
    yaxis3=dict(anchor="x", domain=[0.4, 0.6], title=dict(text="mg/L"), ...),
    yaxis4=dict(anchor="x", domain=[0.6, 0.8], title=dict(text="mmol/L"), ...),
    yaxis5=dict(anchor="x", domain=[0.8, 1], title=dict(text="mg/Kg"), ...)
)

# Update layout
fig.update_layout(
    dragmode="zoom",
    hovermode="x",
    legend=dict(traceorder="reversed"),
    height=600,
    template="plotly_white",
    margin=dict(t=100, b=100),
)

fig.show()

(完整可运行版本请直接查看原文档 doc/python/range-slider.md 的第 94–362 行。)

该示例的关键设计点:

  1. 五个 y 轴通过 domain 均分高度:yaxis~yaxis5 的 domain 依次为 [0, 0.2]、[0.2, 0.4]……[0.8, 1],并以 anchor="x" 共享同一个 x 轴;
  2. rangeslider 同时设置了 autorange=True 与显式 range:此时滑块的显示窗口被限定到该区间,主图仍可自由缩放;
  3. hovermode="x" + dragmode="zoom":鼠标悬停显示共享 x 轴十字参考线,拖动框选放大,配合底部滑块形成完整的"总览 + 细节"交互体验;
  4. template="plotly_white":使用内置白底模板,让色带与多轴配色更清晰。

四、Rangeslider 完整属性表与边界说明

Rangeslider 类 的 _valid_props 声明了 8 个属性,全部参数及语义如下:

属性 类型/取值 含义与边界(依据源码属性文档)
visible bool 是否显示滑块。注意源码特别说明:滑块可见时,其垂直方向(垂直相交)的轴会被自动设置为 fixedrange
range 长度为 2 的列表 滑块的显示范围。未设置时默认取整个 xaxis 范围;对 type="log" 轴需传入取对数后的值;对 type="date" 轴应传日期字符串(也接受 datetime 对象与 Unix 毫秒时间戳,会被自动转换为字符串);对 type="category" 轴则应传数字(按类别出现顺序从 0 起编号的序列号)
autorange bool 是否依据输入数据自动计算滑块范围;一旦提供了 range,autorange 即被置为 False
thickness 数值,区间 [0, 1] 滑块高度占整个绘图区高度的比例
bgcolor 颜色 滑块背景色(支持 CSS 颜色体系中的 hex、rgb/rgba、hsl/hsla、hwb、lab/lch/oklab/oklch 以及 CSS 4 颜色格式)
bordercolor 颜色 滑块边框颜色
borderwidth 整数(区间 [0, 2^63-1]) 滑块边框宽度(px)
yaxis YAxis 对象 滑块内部迷你 y 轴的配置

其中 yaxis 子对象只有两个属性:range(滑块内迷你 y 轴的范围)和 rangemode,后者是枚举值 'auto' / 'fixed' / 'match':auto 表示自动范围;fixed 表示使用 yaxis.range;match 表示跟随主绘图区对应 y 轴的当前范围。当数据量级差异很大(如本示例中 var4 的数值达到数千、而 var3 只有个位数)时,可借助 yaxis.rangemode="match" 让滑块内的迷你曲线与主图保持一致的比例关系。

五、Rangeselector 整体外观属性

除按钮本身外,Rangeselector 类 还提供整组选择器的外观与定位属性:

属性 类型/取值 含义
visible bool 是否显示选择器
buttons Button 元组/字典列表 按钮数组,默认不包含任何按钮
activecolor 颜色 当前激活按钮的背景色
bgcolor 颜色 所有按钮的背景色
bordercolor / borderwidth 颜色 / 数值 [0, inf] 整个选择器外边框的颜色与宽度(px)
font Font 对象 按钮文字字体
x / y 数值,区间 [-2, 3] 选择器在归一化坐标中的位置
xanchor / yanchor 'auto' 'left' 'center' 'right' / 'auto' 'top' 'middle' 'bottom' 位置锚点,决定 x/y 绑定到选择器的哪一侧

此外 buttons 数组项还支持 name 与 templateitemname,用于与 模板系统 配合:模板中命名(name)的按钮会在输出图中自动创建,用户可通过同名 templateitemname 覆盖或隐藏它们。

六、使用技巧与注意事项

  1. 务必声明 type="date":Range Slider/Selector 仅对日期 x 轴可用。如果你的 x 数据是 ISO 字符串或 pandas 日期列,plotly.py 通常能自动推断为 date 类型,但显式声明可避免歧义。
  2. stepmode="todate" 与 "backward" 的区别:YTD 类按钮依赖 todate 将起点对齐到自然年/月起点;若想实现"最近 N 个周期",应使用 backward。
  3. 滑块可见时垂直轴被锁定:源码明确说明滑块开启会使垂直相交轴进入 fixedrange,因此"框选缩放 y 轴"与"底部滑块总览"是两种互补而非冲突的交互——框选 x 方向时由滑块接管总览,y 方向缩放受限。
  4. range 的类型适配:date 轴传日期字符串(datetime 对象与 Unix 毫秒会被自动转换)、log 轴传对数化数值、category 轴传 0 起始的类别序号,三者不可混用。
  5. 金融图默认开启:蜡烛图、OHLC 图默认显示滑块,可用 fig.update_layout(xaxis_rangeslider_visible=False) 关闭,参见 candlestick-charts.md 与 ohlc-charts.md。

七、进一步查阅

上述图对象源码均由代码生成器自动产出(文件头部标注 THIS FILE IS AUTO-GENERATED),其属性描述与校验规则与 plotly.js 的 schema 保持一致,是查询属性取值范围最可靠的本地参考。

登录后查看全文
plotly.py