Skip to content

PyGWalker Streamlit API

使用 StreamlitRenderer 将 PyGWalker 嵌入 Streamlit 应用。当数据集和图表状态会在 rerun 之间复用时，请缓存 renderer。

import pandas as pd
import streamlit as st
from pygwalker.api.streamlit import StreamlitRenderer
 
st.set_page_config(page_title="PyGWalker", layout="wide")
 
@st.cache_resource
def get_renderer():
    df = pd.read_csv("data.csv")
    return StreamlitRenderer(
        df,
        spec_path="./gw_config.json",
        spec_io_mode="rw",
        computation="kernel",
    )
 
renderer = get_renderer()
renderer.explorer()

构造函数

StreamlitRenderer(
    dataset,
    gid=None,
    *,
    field_specs=None,
    theme_key="g2",
    appearance="media",
    spec="",
    spec_path=None,
    spec_io_mode="r",
    computation=None,
    kernel_computation=None,
    use_kernel_calc=None,
    show_cloud_tool=None,
    kanaries_api_key="",
    default_tab="vis",
    **kwargs,
)

dataset 可以是 pandas DataFrame、polars DataFrame、pyarrow Table、数据库 Connector，或可复用的 pygwalker.Walker。

关键选项

选项默认值说明
spec_pathNone本地图表状态文件。本地文件请优先使用它。
spec_io_mode"r"当 Streamlit UI 需要将图表编辑保存回 spec 文件时，使用 "rw"。
computationNone使用 "browser"、"kernel" 或 "cloud" 强制选择模式。Streamlit 自动行为默认使用 kernel 侧计算。
show_cloud_toolNone控制可用时是否显示 cloud UI。
default_tab"vis"初始探索器标签页。

kernel_computation 和 use_kernel_calc 是旧兼容选项。请优先使用 computation；这些旧参数计划在 PyGWalker 0.7.0 中移除。

主要方法

方法用途
renderer.explorer(key="explorer", default_tab="vis")完整的拖放探索器。
renderer.viewer(key="viewer")只读/filter-renderer UI。
renderer.chart(index, key="chart", size=None, pre_filters=None)按从 0 开始的索引渲染已保存图表。
renderer.table(key="table")渲染表格视图。
renderer.set_global_pre_filters(pre_filters)对所有图表应用过滤器，除非某次 chart 调用覆盖它们。

渲染已保存图表

将图表保存到 spec_path 后，可以按索引渲染某个图表。

renderer.chart(0, size=(720, 420))

使用 PreFilter 应用图表级过滤器。

from pygwalker.api.streamlit import PreFilter
 
renderer.chart(
    0,
    pre_filters=[
        PreFilter(field="category", op="one of", value=["A", "B"]),
        PreFilter(field="revenue", op="range", value=[0, 100000]),
    ],
)

PreFilter 接受：

PreFilter(
    field: str,
    op: "range" | "temporal range" | "one of",
    value: list[int | float | str],
)

对于 op="temporal range"，值可以是毫秒时间戳或可解析的日期字符串。

复用 Walker

如果同一份数据集和选项需要与其他适配器共享，请先构造 Walker。

import pygwalker as pyg
from pygwalker.api.streamlit import StreamlitRenderer
 
walker = pyg.Walker(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    computation="kernel",
)
 
renderer = StreamlitRenderer(walker)
renderer.explorer()

传入 Walker 时，请将构造选项放在 pyg.Walker(...) 上。StreamlitRenderer(walker, spec_path="./other.json") 会被拒绝，因为它会与已有对象冲突。

get_streamlit_html

get_streamlit_html 返回 Streamlit 组件使用的 HTML 字符串。

from pygwalker.api.streamlit import get_streamlit_html
 
html = get_streamlit_html(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    mode="explore",
    computation="kernel",
)

支持的模式为 "explore"、"filter_renderer" 和 "table"。

常见陷阱

陷阱修复方式
每次 rerun 都重新创建 StreamlitRenderer用 @st.cache_resource 包裹构造逻辑。
对本地文件使用 spec="./gw_config.json"使用 spec_path="./gw_config.json"。
提供 Walker 后又传入构造选项将这些选项移到 pyg.Walker(...)。
新代码以 kernel_computation=True 开始使用 computation="kernel"。

相关指南