如何用 Streamlit 的 st.pagination 为大结果集、搜索页和向导实现分页导航【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit如果你的 Streamlit 应用里有一个几百行的数据表、一份搜索结果或者一个分步填写的表单st.pagination提供了一个带上一页/下一页箭头和页码按钮的分页控件直接返回当前选中的页码从 1 开始你只需要用它做数据切片。它是带状态的控件一次始终选中一页选中页会在 rerun 之间保留返回值在下一次 rerun 时更新。本文基于仓库中的产品规格 specs/2026-03-22-st-pagination/product-spec.md、组件实现 lib/streamlit/elements/widgets/pagination.py 和 e2e 演示应用 e2e_playwright/st_pagination.py给出三种典型场景的完整写法和验证方式。组件签名与参数以组件实现 lib/streamlit/elements/widgets/pagination.py 中的签名和 docstring 为准st.pagination( num_pages: int, *, default: int 1, max_visible_pages: int | None 7, width: Literal[content, stretch] | int content, key: Key | None None, on_change: WidgetCallback | None None, args: WidgetArgs | None None, kwargs: WidgetKwargs | None None, disabled: bool False, bind: BindOption None, persist_state: PersistStateOption None, ) - int关键参数含义取自实现文件 docstring参数说明num_pages总页数必须 ≥ 1default初始选中页1-indexed必须在 1 到num_pages之间默认1max_visible_pages最多显示的页码按钮数不含箭头默认70只显示前后箭头1只显示当前页None去掉数量上限窄容器下仍可能自动隐藏部分页码widthcontent随内容、stretch撑满父容器宽度按钮保持居中、int为固定像素宽度key控件唯一 key提供后可以通过st.session_state[key]读取和改写当前页on_change选中页变化时的回调args/kwargs传给回调disabled为True时整个控件禁用bind设为query-params时把页码同步到 URL 查询串要求同时设置key得到可分享、能保留页码状态的链接persist_statepage表示页码只在当前页保留session表示整个会话保留跨页面切换也保留要求有key同时设置bindquery-params时以 URL 绑定为准返回值是当前选中页的int。注意分页控件本身不负责切片数据切片由你自己根据返回的页码计算——这也是产品规格中选择低层控件而非自动分页迭代器的原因它和数据源数据库、API、本地数据解耦。场景一为大结果集做分页数据表docstring 中给出的 dataframe 示例lib/streamlit/elements/widgets/pagination.py展示了完整做法先用st.empty()占位把分页控件放在数据表下方右对齐再按页码切片import streamlit as st import pandas as pd df pd.DataFrame({A: range(100), B: range(100, 200)}) rows_per_page 10 total_pages (len(df) rows_per_page - 1) // rows_per_page # Use placeholders to show dataframe above pagination dataframe_slot st.empty() with st.container(horizontal_alignmentright): page st.pagination(num_pagestotal_pages) start_idx (page - 1) * rows_per_page end_idx start_idx rows_per_page dataframe_slot.dataframe(df.iloc[start_idx:end_idx])这里的要点total_pages (len(df) rows_per_page - 1) // rows_per_page是向上取整的页数计算50 行、每页 10 行得到 5 页。切片区间是(page - 1) * rows_per_page到start_idx rows_per_page因为页码从 1 开始。用st.empty()占位是为了让数据表渲染在分页控件上方如果直接先写分页再写数据表布局会反过来。把df换成pd.read_csv(...)或数据库查询结果即可规格中的 示例 用的是pd.read_csv(large_dataset.csv)、每页 25 行的写法。场景二搜索页——回调、程序化跳转与 URL 同步搜索结果页通常需要一个稳定的key因为要支持程序化改页和监听页码变化。带回调的写法来自 e2e_playwright/st_pagination.py回调内通过st.session_state[key]读当前页def on_change(): st.write(fcallback-page: {st.session_state.callback_pagination}) st.pagination(10, keycallback_pagination, on_changeon_change)on_change在有效页码相对上一次 rerun 发生变化时触发包括用户点击、通过st.session_state[key]的编程式修改以及num_pages变小导致页码回落到default的情况仅当回落后的页码与之前不同时。程序化跳转来自 产品规格 的示例import streamlit as st # Jump to a specific page programmatically if st.button(Go to page 5): st.session_state.my_page 5 # Reset to first page if st.button(Reset): st.session_state.my_page 1 page st.pagination(num_pages10, keymy_page)e2e 应用 e2e_playwright/st_pagination.py 里还演示了三个按钮跳到第 1/5/10 页的搜索页常见模式写法相同按钮回调里给st.session_state[key]赋值控件用同一个key声明。可选分支让搜索结果页的页码可分享。设置bindquery-params并给出key后页码会读写到 URL 查询串key即查询参数名用户把链接发给别人时页码状态得以保留page st.pagination(10, keypage, bindquery-params)没有key时设置bindquery-params会抛出要求提供唯一 key 的异常。场景三多步骤向导把每一步映射为一个页码用widthstretch让控件撑满宽度再按step - 1取步骤标题页码是 1-indexedimport streamlit as st steps [Personal Info, Address, Payment, Review] step st.pagination(num_pageslen(steps), widthstretch) st.header(steps[step - 1]) # Render step content based on current step这是 产品规格 给出的向导示例。注意规格同时说明用自定义标签而不是数字标注向导步骤、输入框直接跳页、每页条数选择器、第 3 / 10 页之类的总数展示目前都在 Out of Scope 清单里尚不支持向导步骤只能用数字页码表达。页码截断、宽度与响应式行为当num_pages超过max_visible_pages时控件按既定模式截断规格中的布局示意 | 1 | 2 | 3 | ... | 10 | (when on page 1-3) | 1 | ... | 5 | 6 | 7 | ... | 10 | (when on page 6) | 1 | ... | 8 | 9 | 10 | (when on page 8-10)首尾页和当前页始终保留当前页周围附带 1–2 页上下文省略号表示被隐藏的区段max_visible_pages0只剩 | 1显示 | 5 | 2显示当前页加末页当前页在边缘时改为首页加末页当前选中页用主色高亮...不可点击。响应式方面控件根据容器可用宽度自动隐藏页码页码按钮永远不会折行空间不足时按箭头 当前页 末页 首页 相邻上下文页的优先级递减极窄容器下会退化为 | 5 | 甚至只有箭头。键盘可访问性Tab 在箭头和页码按钮间移动Enter/Space 激活焦点环只在键盘导航时可见。验证运行结果把上面任一示例保存为streamlit_app.py运行streamlit run streamlit_app.py然后按仓库 e2e 测试 e2e_playwright/st_pagination_test.py 里的断言核对行为这些断言就是分页行为的验收标准初始渲染显示Current page: 1对应st.write(fCurrent page: {page})第 1 页时上一页箭头为 disabled下一页可用点击下一页rerun 后显示Current page: 2点击页码按钮 5rerun 后显示Current page: 5设置default5时初始显示Default page: 5点上一页变为 4disabledTrue时前后箭头和所有页码按钮都是 disablednum_pages1时只显示页码 1两个箭头均 disabled。单元测试 lib/tests/streamlit/elements/pagination_test.py 覆盖了另一侧的可执行断言即参数校验错误。出现以下报错时对照检查参数触发条件异常num_pages 1或非 int/boolStreamlitAPIException信息含num_pages must be an integer of at least 1default 1或 num_pagesStreamlitValueOutOfRangeError信息含required range [1, num_pages]default非 intTrue也被拒绝因为 bool 是 int 子类StreamlitInvalidParameterTypeErrormax_visible_pages 0或非 int/boolStreamlitAPIException信息含max_visible_pages must be a non-negative integer or None设置bindquery-params但没有key要求提供唯一 key 的StreamlitAPIException同一页内重复声明同一无 key 控件提示重复 ID 的StreamlitAPIException状态语义与限制写代码前需要确认几条来自规格与实现的硬规则控件有状态选中页在 rerun 间保留default只在st.session_state[key]尚无值时生效之后再改default不会改变当前页、也不触发on_change。运行期num_pages变小且当前页超过新的num_pages时页码回落到default这算作一次页码变化仅当回落后的页码与之前不同才触发on_change。控件可以放进st.form提交前不触发整页 rerun取值随表单提交生效和st.fragmentfragment 内局部 rerun两者都在 e2e_playwright/st_pagination.py 中有对应演示区块。目前不支持自定义页码标签、跳页输入框、每页条数选择器、总数展示、全局方向键快捷键产品规格 Out of Scope 一节。规格与实现中有一处参数描述口径不同这里如实指出规格中max_visible_pages是maximum number of page buttons而实现 docstring 表述为 Target number of page buttons并说明个别边界情况下实际数量可能略高以保证首尾页始终可见。两者对常规使用的约束一致默认 7、可设0/1/None按上述取值使用即可。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考