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

引言

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

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

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

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

实现步骤详解

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"),
)

性能优化建议

1. 数据分块加载：实现更精细的数据分块策略，减少每次请求的数据量
2. 缓存机制：在服务器端添加数据缓存，避免重复处理相同请求
3. 预加载：对于可能被频繁访问的节点，实现预加载策略
4. 压缩传输：启用Gzip压缩减少网络传输量

常见问题解决

1. MantineProvider错误：确保使用最新版Vizro，该问题在v0.1.39已修复
2. 数据格式不一致：严格验证输入数据格式，确保符合预期结构
3. 跨域问题：在开发环境中配置正确的CORS策略

总结

通过Vizro实现服务器端行模型展示树形数据，我们能够高效处理大型层级数据集。这种方法结合了Vizro的易用性和AG Grid的强大功能，为复杂数据可视化需求提供了优雅的解决方案。关键点包括：

1. 正确转换树形数据为适合SSRM处理的格式
2. 实现高效的服务器端数据处理API
3. 合理配置AG Grid的树形展示选项
4. 使用客户端回调优化数据加载体验

这种实现方式不仅适用于组织结构数据，也可广泛应用于任何需要展示层级关系的场景，如文件系统、产品分类等。