Skip to content

PyGWalker Gradio API

使用 get_html_on_gradio 为 Gradio 应用生成 PyGWalker iframe HTML。启动应用时挂载 PYGWALKER_ROUTE，让 PyGWalker 通信路由可用。

import gradio as gr
import pandas as pd
from pygwalker.api.gradio import PYGWALKER_ROUTE, get_html_on_gradio
 
df = pd.read_csv("data.csv")
 
with gr.Blocks() as demo:
    pyg_html = get_html_on_gradio(
        df,
        spec_path="./gw_config.json",
        spec_io_mode="rw",
        computation="kernel",
    )
    gr.HTML(pyg_html)
 
demo.launch(app_kwargs={"routes": [PYGWALKER_ROUTE]})

get_html_on_gradio

签名：

get_html_on_gradio(
    dataset,
    gid=None,
    *,
    field_specs=None,
    theme_key="g2",
    appearance="media",
    spec="",
    spec_path=None,
    spec_io_mode="r",
    computation=None,
    kernel_computation=None,
    kanaries_api_key="",
    default_tab="vis",
    **kwargs,
) -> str

dataset 可以是 pandas DataFrame、polars DataFrame、pyarrow Table 或数据库 Connector。

关键选项

选项默认值说明
spec_pathNone本地图表状态文件。本地文件请优先使用它。
spec_io_mode"r"当 Gradio UI 需要保存图表编辑时使用 "rw"。
computationNone使用 "browser"、"kernel" 或 "cloud" 显式选择模式。
kernel_computationNone旧兼容参数。请优先使用 computation；计划在 PyGWalker 0.7.0 中移除。
default_tab"vis"初始探索器标签页。

计算说明

Gradio 作为 live 应用运行，因此支持 kernel 和 cloud 计算。

get_html_on_gradio(df, computation="browser")
get_html_on_gradio(df, computation="kernel")
get_html_on_gradio(df, computation="cloud", kanaries_api_key="...")

不要将非 auto 的 computation 值与已启用的旧计算参数混用。当这些选项冲突时，PyGWalker 会抛出 ValueError。

常见陷阱

陷阱修复方式
iframe 已渲染但交互失败用 app_kwargs={"routes": [PYGWALKER_ROUTE]} 启动。
本地图表编辑没有保存同时使用 spec_path 和 spec_io_mode="rw"。
新代码使用 kernel_computation=True使用 computation="kernel"。
需要静态 HTML 导出而不是 Gradio 应用使用带 computation="browser" 的 HTML 导出。

相关指南