Plotly.py 交互式时间序列:Range Slider 与 Range Selector 完整配置指南
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 中,它们对应两类图对象层级:
layout.xaxis.rangeselector(plotly/graph_objs/layout/xaxis/_rangeselector.py)layout.xaxis.rangeslider(plotly/graph_objs/layout/xaxis/_rangeslider.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 行。)
该示例的关键设计点:
- 五个 y 轴通过
domain均分高度:yaxis~yaxis5的domain依次为[0, 0.2]、[0.2, 0.4]……[0.8, 1],并以anchor="x"共享同一个 x 轴; rangeslider同时设置了autorange=True与显式range:此时滑块的显示窗口被限定到该区间,主图仍可自由缩放;hovermode="x"+dragmode="zoom":鼠标悬停显示共享 x 轴十字参考线,拖动框选放大,配合底部滑块形成完整的"总览 + 细节"交互体验;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 覆盖或隐藏它们。
六、使用技巧与注意事项
- 务必声明
type="date":Range Slider/Selector 仅对日期 x 轴可用。如果你的 x 数据是 ISO 字符串或 pandas 日期列,plotly.py 通常能自动推断为 date 类型,但显式声明可避免歧义。 stepmode="todate"与"backward"的区别:YTD 类按钮依赖todate将起点对齐到自然年/月起点;若想实现"最近 N 个周期",应使用backward。- 滑块可见时垂直轴被锁定:源码明确说明滑块开启会使垂直相交轴进入
fixedrange,因此"框选缩放 y 轴"与"底部滑块总览"是两种互补而非冲突的交互——框选 x 方向时由滑块接管总览,y 方向缩放受限。 range的类型适配:date 轴传日期字符串(datetime 对象与 Unix 毫秒会被自动转换)、log 轴传对数化数值、category 轴传 0 起始的类别序号,三者不可混用。- 金融图默认开启:蜡烛图、OHLC 图默认显示滑块,可用
fig.update_layout(xaxis_rangeslider_visible=False)关闭,参见 candlestick-charts.md 与 ohlc-charts.md。
七、进一步查阅
- 本文内容主体:doc/python/range-slider.md(含两段完整可运行代码)
- 图对象定义:Rangeselector、Rangeslider、Button、rangeslider.YAxis
- 同一交互控件体系的相关文档:sliders.md(通用滑块)、range-slider 周边交互(自定义按钮)
上述图对象源码均由代码生成器自动产出(文件头部标注 THIS FILE IS AUTO-GENERATED),其属性描述与校验规则与 plotly.js 的 schema 保持一致,是查询属性取值范围最可靠的本地参考。