如何为Shiny for Python的DataGrid列标题（或部分）添加工具提示？

DataGrid 底层基于 ag-Grid，我们可以通过传递 options 参数配置列定义，实现为部分或所有列标题添加工具提示的需求。

1. 为部分列标题添加提示 #

直接在列定义数组 columnDefs 中，为目标列指定 headerTooltip 属性即可：

from shiny import App, render, ui
import pandas as pd

app_ui = ui.page_fluid(
    ui.output_data_grid("my_grid")
)

def server(input, output, session):
    @output
    @render.data_grid
    def my_grid():
        # 示例数据
        df = pd.DataFrame({
            "Name": ["Alice", "Bob", "Charlie"],
            "Age": [25, 30, 35],
            "Email": ["alice@example.com", "bob@example.com", "charlie@example.com"]
        })
        
        # 配置列定义，仅给指定列添加标题提示
        column_defs = [
            {"field": "Name", "headerTooltip": "用户姓名"},
            {"field": "Age", "headerTooltip": "用户年龄"},
            # 未设置 headerTooltip 的列不会显示提示
            {"field": "Email"}
        ]
        
        return df, {"columnDefs": column_defs}

app = App(app_ui, server)

2. 为所有列标题添加提示 #

有两种灵活的实现方式：

方式一：用 defaultColDef 统一配置 #

通过默认列定义，为所有列批量设置提示规则，支持动态生成提示内容：

from shiny import App, render, ui
import pandas as pd

app_ui = ui.page_fluid(
    ui.output_data_grid("my_grid")
)

def server(input, output, session):
    @output
    @render.data_grid
    def my_grid():
        df = pd.DataFrame({
            "Name": ["Alice", "Bob", "Charlie"],
            "Age": [25, 30, 35],
            "Email": ["alice@example.com", "bob@example.com", "charlie@example.com"]
        })
        
        # 统一设置所有列的标题提示逻辑
        default_col_def = {
            # 利用 params 参数动态生成提示，可自定义逻辑
            "headerTooltip": lambda params: f"这是「{params.colDef.field}」列"
        }
        
        return df, {"defaultColDef": default_col_def}

方式二：循环生成列定义 #

通过映射表自定义每列的提示文本，适合需要为不同列设置个性化提示的场景：

from shiny import App, render, ui
import pandas as pd

app_ui = ui.page_fluid(
    ui.output_data_grid("my_grid")
)

def server(input, output, session):
    @output
    @render.data_grid
    def my_grid():
        df = pd.DataFrame({
            "Name": ["Alice", "Bob", "Charlie"],
            "Age": [25, 30, 35],
            "Email": ["alice@example.com", "bob@example.com", "charlie@example.com"]
        })
        
        # 自定义列提示映射表
        tooltip_map = {
            "Name": "用户的全名信息",
            "Age": "用户当前的年龄",
            "Email": "用户的官方联系邮箱"
        }
        
        # 循环生成带提示的列定义
        column_defs = [
            {"field": col, "headerTooltip": tooltip_map.get(col, "")}
            for col in df.columns
        ]
        
        return df, {"columnDefs": column_defs}

所有配置均基于 ag-Grid 原生属性，你可以根据需求扩展更多高级功能（如自定义提示样式、延迟显示等）。

内容的提问来源于stack exchange，提问作者lambruscoAcido