跳转到内容

Panel 应用套件

每个服务器 Panel 应用都安装了 plaidcloud_panel 套件。它为您的应用提供 PlaidCloud 的外观(与平台其余部分相同的颜色、字体和间距,支持浅色和深色),并提供一组现成的组件,满足大多数应用所需的界面:筛选器、关键数字、大型数据网格、图表和表单。您的应用会自动采用其项目的品牌设置。

import plaidcloud_panel as pcp

导入该套件还会将 PlaidCloud 的外观应用于 Plotly 和 Matplotlib 图表。

在 Panel Studio 中,新建应用 > Studio 可从空白应用、表或视图、另一个 Studio 应用,或图库中的应用开始,无需运行任何命令。

对于保存在 git 仓库中的应用,该套件包含一个可写出可运行的入门应用的命令。从任意文件夹运行它,然后编辑表名和列名:

终端窗口
plaidcloud-panel new --layout dashboard --title "Sales" --table sales --filters region,year --measure amount
选项 作用
--layout dashboard 筛选器位于侧边栏,另有两个关键数字和一个图表。
--layout explorer 筛选器位于侧边栏,另有行数和行表。
--table 应用读取的 PlaidCloud 表。
--filters 以逗号分隔的筛选列。第一个列驱动图表。
--measure 要合计的数值列。
--dir 写入 app.py 和 requirements.txt 的位置。默认为当前文件夹。

如果 app.py 已存在,该命令会停止且不写入任何内容。将这两个文件提交到您的仓库,并将其发布为服务器应用。

此应用按地区和年份筛选销售表,显示两个关键数字、一个图表,以及一个对匹配行分页的网格。网格以千位分隔符显示金额,并以百分比显示利润率。每个部分都跟随筛选器变化。

import panel as pn
import plaidcloud_panel as pcp
from bokeh.plotting import figure
from plaidcloud.utilities.panel_data import table
pn.extension("tabulator")
sales = table("sales")
bar = pcp.FilterBar(sales, "region", "year")
def by_region(t):
df = t.aggregate(by=["region"], total=("amount", "sum"))
regions = df["region"].astype(str).tolist()
fig = figure(x_range=regions, height=320, toolbar_location=None)
fig.vbar(x=regions, top=df["total"].astype(float).tolist(), width=0.8, color=pcp.series()[0])
return fig
def grid(t):
return pcp.DataGrid(t, key="id", totals={"amount": "sum"}, formats={"amount": "0,0", "margin": "0.0%"})
pcp.App(
"Sales",
sidebar=[bar],
main=[
pn.Row(
pcp.KpiCard("Total amount", bar.table, "amount"),
pcp.KpiCard("Orders", bar.table),
),
pcp.Chart(pn.bind(by_region, bar.table), title="Amount by region"),
pcp.Section("Orders", pn.bind(grid, bar.table)),
],
).servable()

每个套件应用的模式都相同:基于表构建一个 FilterBar,然后将每个视图绑定到 bar.table。未绑定到 bar.table(或某个控件)的视图在筛选器更改时永远不会刷新。

pcp.App(title, nav=None, *, main=None, sidebar=None, theme_toggle=True, theme=None, commands=None, tour=None) 构建应用外壳:包含标题、项目徽标和已登录用户的页眉,以及侧边栏和主区域。对结果调用 .servable()。

  • 导航:传入 nav=[("Overview", overview_page), ("Detail", detail_page)],即可在侧边栏顶部得到页面菜单。每个页面是一个 Panel 对象,或返回 Panel 对象的函数。函数在选择页面时运行。
  • 主题:应用默认以浅色主题打开。传入 theme="dark" 可以深色主题打开,或在 URL 中添加 ?theme=dark。使用 theme_toggle=True(默认)时,页眉带有浅色/深色切换开关。
  • 品牌:应用在会话开始时读取其项目的品牌颜色和徽标。没有品牌设置的项目使用 PlaidCloud 默认值。
  • 命令面板:按 Ctrl-K(Mac 上为 Cmd-K)可搜索并运行命令。nav 中的每个页面都列为转到页面名称,commands={"Refresh data": refresh} 可添加您自己的条目,每个条目由一个标签和一个不带参数的函数组成。选择条目后,应用会运行它。
  • 首次运行导览:tour=[("Filters", "Narrow the data here."), ("Grid", "Sort and group the rows.")] 会显示简短的分步介绍,每一步包含一个标题和一行文本。它出现在页面顶部,直到您完成或跳过,之后不会再向您显示。
  • 其他:其他关键字参数会传递给 Panel 的 FastListTemplate。

pcp.FilterBar(table, "region", "year", amount=pn.widgets.IntInput(name="Amount")) 会为您指定的每一列创建一个可搜索的多选框,列出该列的不同值(最多 1,000 个,列表被截断时会显示提示)。未选择任何内容时,框中显示全部。其他情况请按列名传入您自己的控件。

  • bar.table 是根据当前选择缩小范围后的表。空白控件不会缩小数据范围。
  • 选择内容保存在页面 URL 中(?region=EU),因此筛选后的视图可以通过链接共享。

pcp.KpiCard(label, source, column=None, fn="sum", fmt="{:,.0f}", drill_to=None) 显示一个关键数字。fn 为 sum、count、avg、min 或 max,由服务器对整个表计算。没有 column 时显示行数。将 bar.table 作为源传入,使数字跟随筛选器变化。

传入 drill_to=grid(一个 DataGrid),可在数字下方添加查看行按钮。选择它会将网格指向该卡片自己的表,使网格列出该数字背后的行。

pcp.DataGrid(source, key="id", totals={"amount": "sum"}) 是适用于任意大小数据的表视图。只有当前页会发送到浏览器;分页、排序、合计和导出都在服务器上运行。

  • 分页:每页 200、500 或 1,000 行,带有“上一页”和“下一页”按钮以及行计数器。

  • 排序:点击列标题。排序作用于整个表,而不仅仅是可见的页面。

  • 合计:totals 将列映射到 sum、count、avg、min 或 max。服务器对每个匹配的行计算每一项,并将结果固定为网格的最后一行。

  • 导出:CSV 和 XLSX 按钮会按当前排序下载所有匹配的行,最多 export_cap 行(默认为 100,000)。当表更大时,会有提示告诉您缩小筛选范围。以 =、+、- 或 @ 开头的文本单元格会加上撇号前缀,使电子表格将其读取为文本。

  • 数字格式:formats={"margin": "0.0%", "amount": "0,0"} 为每列设置显示格式,使用 numbro 格式字符串。% 格式会乘以 100。总计行使用相同的格式。没有格式的浮点列最多显示两位小数并带有千位分隔符。复制、CSV 和 XLSX 保留原始值。

  • 键:key 是唯一标识一行的列或列的列表。请始终传入。请参阅稳定分页。

  • 分组依据:group_by=["region"] 每个分组显示一行,带有 totals 度量和 rows 计数(全部由服务器计算),以及覆盖所有匹配行的总计行。传入 groupable=["region", "year"] 可添加分组依据选择器,让查看者选择列。网格最多显示 1,000 个分组,并在截断列表时告知您。分组行没有打开链接。

  • 条件格式:rules 按值为单元格着色。每条规则指定一个 column、一个 op(>、>=、<、<=、==、!= 或 between)、一个 value(between 为 [low, high])和一个 token(success、warning、error 或 info),例如 {"column": "margin", "op": "<", "value": 0, "token": "error"}。总计行从不着色。

  • 复制:复制按钮会将当前页(包含可见列和总计行)以制表符分隔的文本形式放到剪贴板上,可粘贴到 Excel 中。

  • 在 PlaidCloud 中打开:当源是 PlaidCloud 表时,在 PlaidCloud 中打开链接会打开该表。

  • 已保存的列布局:layout_key="orders" 会添加列和已固定选择器,用于选择列并为其排序,以及固定其中一些列。每位查看者的选择会保存在该名称下,并在下次打开应用时恢复。

  • 行链接:row_link 是一个函数,它接受以字典表示的行,并返回网址,不需要链接时返回 None。网格会添加一个打开列,每个有链接的行都带有一个链接。仅会链接 http 和 https 地址以及同一站点上的路径。

  • 刷新:grid.refresh() 会再次查询同一数据源,并保留页码、排序和分组。请在运行写完表之后调用它。

source 是表名,或来自 Data API 的表。要重新筛选网格,请将 grid.source 设置为筛选后的表,或像示例那样基于 bar.table 构建新的网格。

网格受查看者的行级安全约束:它通过查看者自己的连接读取数据。

pcp.Chart(obj, title=None, height=320) 将图表放入带标题的卡片中。obj 可以是 Bokeh 图形、hvPlot 或 HoloViews 绘图、Plotly 图形、Matplotlib 图形,或返回其中任何一种的 pn.bind(...)。Bokeh 图形上的数值坐标轴显示千位分隔符,因此 800000 显示为 800,000。

pcp.Form(*widgets, on_submit=save, submit="Save") 将输入控件排列为一个带提交按钮的表单。form.values() 为每个已命名的控件返回 {widget.name: widget.value},点击按钮时 on_submit 会收到该字典。

组件 用途
pcp.Section(title, *objects) 直接位于页面背景上的带标题分组。
pcp.Card(title, *objects) 位于凸起表面上的带标题分组。
pcp.Tabs(Overview=obj, Detail=obj) 在选中选项卡时加载其内容的选项卡。活动选项卡采用品牌颜色。
pcp.Loading(height=200) 数据加载时显示的闪烁占位符。

pcp.StatusBanner(message, kind="info") 显示内联通知。kind 为 error、warning、success 或 info。

pcp.run_workflow_button(workflow_id, label=None) 会添加一个按钮,以打开应用的人的身份运行 PlaidCloud 工作流,并显示正在运行…,然后显示完成或失败。失败时会指出失败的步骤,最多五个。除非传入 project_id,否则工作流属于应用的项目。

pcp.RunButton(label, start, status) 对任何作业执行同样的操作。start 启动作业并返回运行 ID;status(run_id) 返回 "running"、"succeeded" 或 "failed",或返回 ("failed", reason) 以显示原因。两者都是普通函数,例如对 REST API 的调用。每次运行成功,按钮的 runs 值就加一,因此之后必须刷新的视图可以绑定到它:

run = pcp.run_workflow_button("monthly_load")
grid = pcp.DataGrid("sales", key="id")
run.param.watch(lambda _: grid.refresh(), "runs")

pcp.table_freshness(table_id) 显示表上次写入的时间,例如 Updated 5 min ago。页面保持打开时,时长会继续更新。传入 stale_after=datetime.timedelta(hours=24) 可用警告标记更旧的数据,并在运行后调用 .refresh()。无法确定日期的表显示 Last update unknown,这绝不是错误。pcp.Freshness(fetch) 对任何数据源执行同样的操作,其中 fetch 返回数据上次更改的时间。

pcp.user_state 会在两次访问之间记住每个人的选择,因此应用会按他们离开时的样子打开。

  • pcp.user_state.persist(widget, "region") 会将已保存的值恢复到控件中,并在每次更改时保存。控件已不再提供的已保存值会被忽略。
  • 在 nav 中选择的页面会自动保存。
  • 以 filters. 开头的键(例如 pcp.user_state.persist(widget, "filters.region"))保存筛选器选择。PlaidCloud 每次读取时都会将其修剪为此人当前的行访问权限,因此已保存的筛选器绝不会带回他们已无法看到的值。
  • pcp.user_state.get(key, default) 和 pcp.user_state.set(key, value) 可保存任何其他小型值。

已保存的设置属于一个人在一个应用中的设置,最大 8 KB。设置绝不会在人与人之间共享。如果保存设置时无法连接到 PlaidCloud,应用会保留该设置直到会话结束。

pcp.PrintButton() 会打开浏览器的打印对话框,目标可选择另存为 PDF。打印页面时会隐藏侧边栏和控件,并应用您项目的品牌。每个 DataGrid 会打印其整个当前页(最多 1,000 行),总计行位于最后。深色应用使用浅色调色板打印。

套件自身的文本(例如按钮、通知、命令面板、导览、运行和新鲜度消息以及网格页脚)以英语、德语或法语显示。语言取自页面地址中的 ?lang=de 或 ?lang=fr,否则取浏览器的语言。数字使用该语言的分隔符。您的数据、列名和您编写的任何标签绝不会被翻译。

如果页面加载的首次绘制耗时超过 3,000 毫秒,或运行的查询慢于 2,000 毫秒,会向应用的日志写入警告,指出超出的内容。相同的数值会显示在 Panel Studio 的洞察选项卡上。要为应用设置不同的限制,请设置以下环境变量:

变量 默认 设置
PLAID_PANEL_BUDGET_FIRST_PAINT_MS 3000 首次绘制的毫秒数。
PLAID_PANEL_BUDGET_QUERY_MS 2000 单个查询的毫秒数。

不是整数的值会被忽略,并应用默认值。

pcp.series() 以颜色列表的形式按顺序返回 PlaidCloud 图表调色板。使用它可使您自己绘制的图表与套件自身的组件保持一致,示例中的条形图就是这样做的。

  • Data API:从应用中筛选、分页、计数和聚合 PlaidCloud 表。
  • 警报和摘要:从应用发送 KPI 警报和计划的摘要。
  • 项目品牌设置:为项目中的每个应用一次性设置颜色和徽标。