Vizro项目中实现服务器端行模型(SSRM)展示树形数据的实践指南

2025-06-27 17:24:29作者：滑思眉Philip

引言

在现代Web应用开发中，高效展示大型数据集是一个常见挑战。Vizro作为基于Dash构建的数据可视化框架，提供了强大的表格展示能力。本文将详细介绍如何在Vizro项目中实现服务器端行模型(Server-Side Row Model, SSRM)来展示树形结构数据，这种技术特别适合处理大型层级数据集。

服务器端行模型(SSRM)概述

服务器端行模型是一种高级数据加载策略，它只在需要时从服务器请求数据，而不是一次性加载所有数据。这种模型特别适合以下场景：

处理超大型数据集(百万级行以上)
需要实现无限滚动或分页加载
数据需要复杂的服务器端处理
树形结构数据的懒加载

实现步骤详解

1. 基础环境配置

首先确保使用最新版本的Vizro(v0.1.39或更高)和相关依赖：

pip install vizro==0.1.39 dash-ag-grid==31.3.1

2. 数据准备与转换

树形数据通常以嵌套JSON格式存储，我们需要将其转换为适合SSRM处理的扁平结构：

import pandas as pd
import requests

# 获取原始树形数据
rowData = requests.get("https://www.ag-grid.com/example-assets/small-tree-data.json").json()

# 转换为扁平结构DataFrame
def extractRowsFromData(groupKeys, data):
    response = []
    if len(groupKeys) == 0:
        for row in data:
            response.append({
                "group": not row.get("children") is None,
                "employeeId": row["employeeId"],
                "employeeName": row["employeeName"],
                "employmentType": row["employmentType"],
                "jobTitle": row["jobTitle"],
            })
        return response
    key = groupKeys[0]
    for row in data:
        if row["employeeId"] == key:
            response += extractRowsFromData(groupKeys[1:], row["children"])
    return response

pandas_row_data = pd.DataFrame([
    {
        "employeeId": row["employeeId"],
        "employeeName": row["employeeName"],
        "employmentType": row["employmentType"],
        "jobTitle": row["jobTitle"],
    }
    for row in extractRowsFromData([], rowData)
])

3. 服务器端数据处理API

创建Flask路由处理数据请求：

from vizro import Vizro
import flask
import json

app = Vizro()
server = app.dash.server

@server.route("/api/serverData", methods=["POST"])
def serverData():
    response = extractRowsFromData(flask.request.json["groupKeys"], rowData)
    return json.dumps(response)

4. Vizro仪表板配置

使用Vizro模型构建仪表板界面：

import vizro.models as vm
from vizro.tables import dash_ag_grid

page_1 = vm.Page(
    title="组织结构树形展示",
    components=[
        vm.AgGrid(
            figure=dash_ag_grid(
                id="grid",
                data_frame=pandas_row_data,
                columnDefs=[
                    {"field": "employeeId", "hide": True},
                    {"field": "employeeName", "hide": True},
                    {"field": "jobTitle"},
                    {"field": "employmentType"},
                ],
                defaultColDef={"flex": 1},
                dashGridOptions={
                    "autoGroupColumnDef": {
                        "field": "employeeName",
                        "cellRendererParams": {"function": "groupRenderer"},
                    },
                    "treeData": True,
                    "isServerSideGroupOpenByDefault": {
                        "function": "params ? params.rowNode.level < 2 : null"
                    },
                    "isServerSideGroup": {"function": "params ? params.group : null"},
                    "getServerSideGroupKey": {
                        "function": "params ? params.employeeId : null"
                    },
                },
                enableEnterpriseModules=True,
                rowModelType="serverSide",
            ),
        )
    ],
)

dashboard = vm.Dashboard(pages=[page_1])

5. 客户端JavaScript处理

添加客户端逻辑处理数据加载：

async function getServerData(request) {
    response = await fetch('./api/serverData', {
        'method': 'POST', 'body': JSON.stringify(request),
        'headers': { 'content-type': 'application/json' }
    })
    return response.json()
}

function createServerSideDatasource() {
    return {
        getRows: async (params) => {
            console.log('ServerSideDatasource.getRows: params = ', params);
            var allRows = await getServerData(params.request)
            var request = params.request;
            var doingInfinite = request.startRow != null && request.endRow != null;
            var result = doingInfinite
                ? {
                    rowData: allRows.slice(request.startRow, request.endRow),
                    rowCount: allRows.length,
                }
                : { rowData: allRows };
            console.log('getRows: result = ', result);
            setTimeout(function () {
                params.success(result);
            }, 200);
        },
    };
}

var dagfuncs = window.dashAgGridFunctions = window.dashAgGridFunctions || {};

dagfuncs.groupRenderer = function () {
    return {
        innerRenderer: (params) => {
            return params.data.employeeName;
        }
    }
}

6. 客户端回调注册

使用Dash的clientside_callback初始化数据源：

from dash import clientside_callback, Input, Output

clientside_callback(
    """async function (id) {
        const delay = ms => new Promise(res => setTimeout(res, ms));
        const updateData = (grid) => {
          var datasource = createServerSideDatasource();
          grid.setServerSideDatasource(datasource);
        };
        var grid;
            try {
                grid = dash_ag_grid.getApi(id)
            } catch {}
            count = 0
            while (!grid) {
                await delay(200)
                try {
                    grid = dash_ag_grid.getApi(id)
                } catch {}
                count++
                if (count > 20) {
                    break;
                }
            }
            if (grid) {
                updateData(grid)
            }
        return window.dash_clientside.no_update
    }""",
    Output("grid", "id"),
    Input("grid", "id"),
)