旧式 UI 扩展功能 整页已过时

QuModLibs.Modules.UI.Funcs 是早期基于已过时的 QUIAutoControlFuntion 扩展出的 UI 功能包。本页所有内容都属于旧式 API 说明，仅建议维护历史项目时参考。

整页过时

本页描述的 QGridAdapter、QVirtualGridManager 以及基于 QUIAutoControlFuntion 的 Auto Tick 管理策略都已过时。现代化网格管理请使用 QuModLibs.Modules.UI.Client 中的 QGridBinder + QGridData。

class QGridAdapter 已过时

QGridAdapter 是对 QGridData 的旧式轻量封装，用于为已有的 Grid 或 ScrollView + Grid 控件建立异步渲染监听。

它会在 GridComponentSizeChangedClientEvent 触发时计算当前已渲染的格子控件，并调用绑定的渲染函数。由于该类继承自已过时的 QUIAutoControlFuntion，释放逻辑依赖 Tick 存活检测，新项目不再推荐使用。

旧式构造参数

from .QuModLibs.Modules.UI.Funcs import QGridAdapter

adapter = QGridAdapter(
    uiNode,
    "/panel/scroll_view",
    isScrollGrid=True,
    bindFunc=lambda viewPath, index: None,
    bindGridConName="",
    bindUpdateBeforeFunc=lambda: None,
    bindUpdateFinishFunc=lambda: None,
)

• uiNode：绑定的 UI 节点实例。
• parentPath：Grid 路径；当 isScrollGrid=True 时，通常传 ScrollView 路径。
• isScrollGrid：是否按 ScrollView 内部的 Grid 内容路径计算。
• bindFunc：格子渲染回调，签名为 (viewPath: str, index: int) -> None。
• bindGridConName：格子控件名。当控件名本身含有数字结尾时，显式声明该名称可避免 index 解析错误。
• bindUpdateBeforeFunc：一轮网格渲染回调开始前触发。
• bindUpdateFinishFunc：一轮网格渲染回调结束后触发。

旧式用法

# -*- coding: utf-8 -*-
from .QuModLibs.UI import EasyScreenNodeCls
from .QuModLibs.Modules.UI.Funcs import QGridAdapter

class CustomData:
    def __init__(self, text="", img=""):
        self.text = text
        self.img = img

@EasyScreenNodeCls.Binding("testUI4.main")
class TEST_UI4(EasyScreenNodeCls):
    def __init__(self):
        self.dataList = [
            CustomData("Hello", "..."),
            CustomData("World", "..."),
        ]
        self.gridAdapter = QGridAdapter(
            self,
            "/panel/scroll_view",
            True,
            bindFunc=self.renderView,
        )
        self.gridAdapter.init()
        self.gridAdapter.setGridDimension((1, len(self.dataList)))

    def renderView(self, viewPath="", index=0):
        if index >= len(self.dataList):
            return
        data = self.dataList[index]
        self.GetBaseUIControl(viewPath + "/text").asLabel().SetText(data.text)
        self.GetBaseUIControl(viewPath + "/img").asImage().SetSprite(data.img)

现代化迁移

在 ScreenNodeWrapper / QEScreenNode 这类支持 RAII 的界面中，推荐改用 QGridBinder：

from .QuModLibs.UI import ScreenNodeWrapper
from .QuModLibs.Modules.UI.Client import QGridBinder, QGridData

@ScreenNodeWrapper.autoRegister("testUI4.main")
class TEST_UI4(ScreenNodeWrapper):
    def __init__(self, *args):
        ScreenNodeWrapper.__init__(self, *args)
        self.dataList = []
        self.gridBinder = QGridBinder(
            self,
            QGridData("/panel/scroll_view", True, bindFunc=self.renderView),
        )

    def Create(self):
        ScreenNodeWrapper.Create(self)
        self.gridBinder.setGridDimension((1, len(self.dataList)))

    def renderView(self, viewPath="", index=0):
        ...

QGridBinder 会跟随 RAII 上下文自动启用和释放监听；如果绑定到不支持 RAII 的 UI 节点，则需要手动调用 start() / stop()。

class QVirtualGridManager 已过时

旧文档中曾提到 QVirtualGridManager。当前源码中该类实现已经整体注释，不再作为可直接导入使用的 API。

如果需要类似“虚拟控件对象托管”的能力，请优先基于 QGridBinder + QGridData 自行维护数据列表，并在 bindFunc(viewPath, index) 中把数据渲染到当前可见格子。这样可以保留原有异步可视区域渲染的性能优势，同时避免依赖已经冻结的旧式管理器。