ipydatagrid API速查手册：DataGrid、选择器与渲染器属性完整清单（附示例代码）

ipydatagrid API速查手册：DataGrid、选择器与渲染器属性完整清单（附示例代码）

【免费下载链接】ipydatagridFast Datagrid widget for the Jupyter Notebook and JupyterLab项目地址: https://gitcode.com/gh_mirrors/ip/ipydatagrid

ipydatagrid 是面向 Jupyter Notebook 与 JupyterLab 的高性能 DataGrid（数据网格）控件。本文把它的三大核心 API —— DataGrid 构建属性、选择器（Selections）接口、单元格渲染器（Renderers）属性 —— 整理成一份完整清单，每个属性都配默认值说明与简短示例代码，方便新手随查随用。

📦 快速开始：三步创建 DataGrid

先安装：

pip install ipydatagrid

最小示例（完整演示见 examples/DataGrid.ipynb 同目录下的examples/DataGrid.ipynb）：

import pandas as pd from ipydatagrid import DataGrid df = pd.DataFrame({"A": [1, 2, 3], "B": ["x", "y", "z"]}) grid = DataGrid(df) grid

DataGrid的完整实现位于 ipydatagrid/datagrid.py，所有可从ipydatagrid直接导入的类在 ipydatagrid/init.py 中统一导出。

🧩 DataGrid 构建属性完整清单

示例：自定义布局 + 主题条纹（参考examples/Themes.ipynb）：

grid = DataGrid(df, layout={"height": "300px"}, horizontal_stripes=True) grid.auto_fit_params = {"area": "body", "padding": 60, "numCols": 1} grid.auto_fit_columns = True # 列宽自动适配，见 examples/Column Width Auto-Fit.ipynb

🎯 选择器（Selections）API：编程式选区与取值

ipydatagrid的选择模型是"矩形选区"列表，内部以{r1, c1, r2, c2}（左上角到右下角，行列均从 0 开始）表示。相关实现在 ipydatagrid/datagrid.py 的SelectionHelper与SelectionIterator类中，交互演示见examples/Selections.ipynb。

快速示例：

grid.select(row1=1, column1=1, row2=2, column2=2, clear_mode="all") # 矩形选区 grid.select(4, 1) # 单个单元格 print(grid.selected_cell_values) # 读取选中值 grid.clear_selection()

💡 提示：按住Ctrl/Cmd拖选可累加选区，按住Shift可在两次点击间选区。

✍️ 单元格读写与事件回调

grid.editable = True # 开启就地编辑：双击单元格或输入新值即可修改 grid.set_cell_value("Origin", 4, "Canada") grid.on_cell_change(lambda c: print("changed:", c["row"], c["column"], c["value"]))

编辑与事件回调的完整交互演示见examples/CellEditing.ipynb。

🎨 渲染器（Renderers）属性完整清单

全部渲染器定义在 ipydatagrid/cellrenderer.py，效果演示见examples/DataGrid.ipynb与examples/ConditionalFormatting.ipynb。

TextRenderer（默认渲染器，其他渲染器的基类）：

BarRenderer（继承 TextRenderer，增加）：

其余渲染器：

• HyperlinkRenderer：url与url_name两个VegaExpr，单元格渲染为可点击链接（需按住Ctrl/Cmd点击，避免误触选择行为），演示见examples/HyperlinkRenderer.ipynb。
• HtmlRenderer：单元格内渲染 HTML 片段，常用属性与 TextRenderer 一致，演示见examples/HtmlRenderer.ipynb。
• ImageRenderer：placeholder（加载占位）、width/height（默认""/100%）、text_color、background_color。

按列装配渲染器：

from ipydatagrid import DataGrid, BarRenderer, TextRenderer from bqplot import ColorScale renderers = { "Horsepower": BarRenderer(bar_color=ColorScale(min=0, max=200, scheme="viridis")), "Name": TextRenderer(text_color="navy"), } grid = DataGrid(df, renderers=renderers)

🌈 Vega 表达式与条件格式化

VegaExpr/Expr是渲染器属性的"瑞士军刀"：传入一个 JS 风格表达式（或 Python 函数），即可让颜色、字体等随cell.value、cell.row、cell.metadata动态变化，实现跨列条件格式化（完整示例见examples/ConditionalFormatting.ipynb）。

from ipydatagrid import VegaExpr, TextRenderer renderer = TextRenderer( background_color=VegaExpr("cell.value < 100 ? 'red' : 'green'") ) grid = DataGrid(df, default_renderer=renderer)

grid_style可用的样式键（优先级高于默认渲染器、低于列渲染器）：background_color、row_background_color、column_background_color、grid_line_color、header_background_color、selection_fill_color、selection_border_color、cursor_fill_color、scroll_shadow等，配色示例见examples/Themes.ipynb。

⚡ StreamingDataGrid：大数据懒加载

数据量大时用 ipydatagrid/datagrid.py 中的StreamingDataGrid子类：前端只按需向后端拉取视口内的数据，内存占用更低、首屏更快（演示见examples/Streaming.ipynb）。

from ipydatagrid import StreamingDataGrid sgrid = StreamingDataGrid(df, debounce_delay=50) df.update(new_columns) # 数据变更 sgrid.tick() # 触发前端刷新

⚠️ 注意：StreamingDataGrid 依赖活动内核，导出为静态 HTML 后不可用。

📁 核心文件路径一览

以上属性清单覆盖了 ipydatagrid 日常开发中的全部高频 API。建议配合examples/目录下的 Notebook 逐个上手：从Selections.ipynb掌握选区，再到ConditionalFormatting.ipynb玩转 Vega 表达式，即可快速构建出专业级的 Jupyter 数据网格。

【免费下载链接】ipydatagridFast Datagrid widget for the Jupyter Notebook and JupyterLab项目地址: https://gitcode.com/gh_mirrors/ip/ipydatagrid