PyGWalker 组件 API

当你希望用 Python 方法链构建 PyGWalker 图表，而不只是使用拖放探索器时，请使用 pygwalker.component(...)。

import pygwalker as pyg
 
chart = (
    pyg.component(df, spec_path="./gw_config.json", computation="browser")
    .bar()
    .encode(x="category", y="sum(revenue)", color="region")
    .layout(width=720, height=420)
)
 
html = chart.to_html()

Factory

pyg.component(
    dataset,
    *,
    field_specs=None,
    spec="",
    spec_path=None,
    spec_io_mode="rw",
    theme_key="vega",
    appearance="media",
    show_cloud_tool=False,
    computation=None,
    kernel_computation=None,
    kanaries_api_key="",
    **kwargs,
) -> Component

dataset 可以是 pandas DataFrame、polars DataFrame、pyarrow Table、数据库 Connector 或连接器式字符串。

本地图表状态文件请使用 spec_path。新代码请使用 computation；kernel_computation 是旧参数，并计划在 PyGWalker 0.7.0 中移除。

Mark 方法

Mark 方法会返回复制后的 Component，因此链式调用可以安全复用。

方法	图表 mark
`.bar()`	Bar
`.line()`	Line
`.area()`	Area
`.trail()`	Trail
`.scatter()`	Point/scatter
`.circle()`	Circle
`.tick()`	Tick
`.rect()`	Rect
`.arc()`	Arc
`.text()`	Text
`.box()`	Box plot
`.table()`	Table
`.poi()`	Geographic point of interest

编码

使用 .encode(...) 将字段映射到视觉通道。

chart = (
    pyg.component(df)
    .scatter()
    .encode(
        x="ad_spend",
        y="revenue",
        color="channel",
        size="sum(orders)",
    )
)

支持的通道：

encode(
    x="",
    y="",
    color="",
    opacity="",
    size="",
    shape="",
    radius="",
    theta="",
    longitude="",
    latitude="",
    geoid="",
    details="",
    text="",
)

x 和 y 也可以接收字段列表。sum(revenue) 这类聚合表达式使用 Graphic Walker 的聚合模型。

布局和模式

使用 .layout(...) 设置图表尺寸和布局选项。

chart = chart.layout(mode="fixed", width=640, height=360)

用以下方法切换渲染模式：

方法	用途
`.profiling()`	渲染 profiling/table 模式。
`.explorer()`	围绕当前图表状态渲染完整探索器。
`.copy()`	在分支图表链前创建显式副本。
`.to_html()`	返回当前组件的 HTML。

静态导出限制

组件 .to_html() 是静态 HTML。Explorer 和 profiling 组件导出会拒绝 live kernel/cloud 计算：

# Use browser computation when exporting component HTML.
component = pyg.component(df, computation="browser")
html = component.explorer().to_html()

当图表需要 kernel 或 cloud 计算时，请使用 live 适配器，例如 Notebook API、Streamlit 或 Gradio。

PyGWalker 组件 API

Factory

Mark 方法

编码

布局和模式

静态导出限制

相关指南