Reviewer's Guide

Enables declarative initial sorting in the fullscreen launcher by introducing a sortColumn Q_PROPERTY on SortProxyModel, wiring it from QML, and ensuring resorting occurs when sortColumn changes, while conditionally enabling item move animations to avoid conflicts with model move signals.

Sequence diagram for declarative initial sorting of fullscreen launcher items

sequenceDiagram
    actor User
    participant QML_Engine
    participant FullscreenFrame_QML
    participant ItemArrangementProxyModel_QML
    participant SortProxyModel
    participant SourceModel
    participant GridView

    User->>QML_Engine: Open fullscreen launcher
    QML_Engine->>FullscreenFrame_QML: Instantiate FullscreenFrame
    FullscreenFrame_QML->>ItemArrangementProxyModel_QML: Create ItemArrangementProxyModel
    ItemArrangementProxyModel_QML->>SortProxyModel: Create SortProxyModel instance

    QML_Engine->>SortProxyModel: setSortRole(IndexInPageRole)
    QML_Engine->>SortProxyModel: setSortColumn(0)
    SortProxyModel->>SortProxyModel: store m_sortColumn = 0

    QML_Engine->>SortProxyModel: setSourceModel(SourceModel)
    SortProxyModel->>SourceModel: setSourceModel
    SourceModel-->>SortProxyModel: beginResetModel
    SortProxyModel->>SortProxyModel: rebuildRowMap using m_sortColumn
    SourceModel-->>SortProxyModel: endResetModel

    SortProxyModel-->>GridView: expose already sorted data
    GridView-->>User: Display items sorted with no move animations

    Note over SortProxyModel,GridView: No beginMoveRows or endMoveRows emitted during initial sort

Sequence diagram for runtime change of sortColumn triggering reorder

sequenceDiagram
    participant QML_Code
    participant SortProxyModel
    participant SourceModel
    participant GridView

    QML_Code->>SortProxyModel: setSortColumn(newColumn)
    SortProxyModel->>SortProxyModel: compare m_sortColumn with newColumn
    alt sortColumn changed and proxy map populated
        SortProxyModel->>SortProxyModel: update m_sortColumn
        SortProxyModel-->>QML_Code: sortColumnChanged signal
        SortProxyModel->>SortProxyModel: reorder()
        SortProxyModel->>GridView: beginMoveRows signals
        SortProxyModel->>GridView: endMoveRows signals
        GridView->>GridView: run itemMoveTransition
    else no change or no data
        SortProxyModel-->>QML_Code: no reordering
    end

Sequence diagram for conditional enabling of itemMoveTransition in FullscreenFrame

sequenceDiagram
    participant FullscreenFrame_QML
    participant GridView
    participant LauncherController

    FullscreenFrame_QML->>GridView: Component.onCompleted
    GridView->>LauncherController: read currentFrame
    LauncherController-->>GridView: currentFrame value
    alt currentFrame is FullscreenFrame
        GridView->>GridView: itemMoveTransition.enabled = true
    else currentFrame is not FullscreenFrame
        GridView->>GridView: itemMoveTransition remains disabled
    end
    GridView->>GridView: gridViewContainer.checkPageSwitchState()

Class diagram for updated SortProxyModel with sortColumn Q_PROPERTY

classDiagram
    class QAbstractProxyModel

    class SortProxyModel {
        <<QML_ELEMENT>>
        - int m_sortRole
        - int m_sortColumn
        - Qt_CaseSensitivity m_sortCaseSensitivity
        + int sortRole()
        + void setSortRole(int role)
        + int sortColumn()
        + void setSortColumn(int column)
        + Qt_CaseSensitivity sortCaseSensitivity()
        + void setSortCaseSensitivity(Qt_CaseSensitivity sensitivity)
        + void setSourceModel(QAbstractItemModel model)
        + void reorder()
        + void sortRoleChanged()
        + void sortColumnChanged()
    }

    SortProxyModel --|> QAbstractProxyModel

File-Level Changes

deepin pr auto review

这段代码 diff 展示了对 SortProxyModel 类的修改，主要目的是在 QML 中支持通过属性声明的方式设置排序列，而不是在 Component.onCompleted 中手动调用 sort() 方法。同时，在 FullscreenFrame.qml 中增加了对当前 Frame 的判断逻辑。

以下是对这段代码的详细审查和改进意见：

1. 语法与逻辑审查

• QML 逻辑改进 (FullscreenFrame.qml):

  • 原代码: Component.onCompleted: { proxyModel.sort(0) }
  • 新代码: sortColumn: 0
  • 分析: 这是一个很好的改进。将命令式的 sort() 调用改为声明式的属性绑定，更符合 QML 的编程范式。根据头文件 sortproxymodel.h 中的注释，这样做可以在模型重置期间启用初始排序，且不发出移动信号，这通常能减少不必要的视图重绘和动画，提升性能。

• C++ 逻辑改进 (sortproxymodel.cpp):

  • 新增方法: setSortColumn(int column)
  • 分析: 逻辑实现正确。它检查了值是否变化 (m_sortColumn != column)，更新了成员变量，发射了信号，并在源模型已设置的情况下触发了 reorder()。
  • 潜在问题: Q_UNUSED(oldColumn) 这一行代码虽然是为了消除编译器关于未使用变量的警告，但 oldColumn 变量本身在这个上下文中确实没有实际用途（不需要根据旧列做特殊处理）。保留它可能是为了调试或未来扩展，但在当前逻辑下显得多余。建议直接移除 oldColumn 的定义。

• QML 条件判断 (FullscreenFrame.qml):

  • 新增代码:

    if (LauncherController.currentFrame === "FullscreenFrame") {
        itemMoveTransition.enabled = true
    }

  • 分析: 这段逻辑放在 Component.onCompleted 中，意味着组件创建完成时检查一次。如果 LauncherController.currentFrame 在组件生命周期内发生变化，这段代码不会响应。如果这是预期行为（仅初始化时检查），则没有问题。如果需要动态响应，应该使用属性绑定。

2. 代码质量

• 命名规范: sortColumn 和 setSortColumn 命名清晰，符合 Qt 和 C++ 的命名规范。
• 代码注释: 头文件中的注释 @note sortColumn can be set declaratively in QML... 非常有用，解释了修改的意图和行为。
• 变量作用域: 如前所述，oldColumn 变量在 setSortColumn 中定义后未使用，降低了代码的整洁度。

3. 代码性能

• 排序触发时机:
  • 在 setSortColumn 中，如果 sourceModel() 存在且映射非空，会调用 reorder()。这意味着每次设置 sortColumn 都会立即触发排序。
  • 在 QML 中使用 sortColumn: 0 时，这会在对象构造期间发生。相比 Component.onCompleted，这可能会让排序发生得稍早一些，但通常不会带来显著的性能差异。
  • 注意: 如果 reorder() 是一个耗时操作，且在模型数据量很大时频繁调用 setSortColumn，可能会导致界面卡顿。目前的实现通过 if (m_sortColumn != column) 增加了一个守卫，避免了不必要的重复排序，这是很好的做法。

4. 代码安全

• 空指针检查: if (sourceModel() && !m_proxyToSourceMap.empty()) 做了必要的空指针和状态检查，防止了潜在的空指针解引用崩溃。
• 类型安全: 参数类型为 int，与 sortColumn 属性类型一致，没有明显的类型安全问题。

改进建议

1. 移除未使用的变量 (sortproxymodel.cpp):
   建议移除 oldColumn 变量，因为它既没有被使用，也没有在逻辑上提供帮助。这会让代码更简洁。

   // 改进后的 setSortColumn
   void SortProxyModel::setSortColumn(int column)
   {
       if (m_sortColumn != column)
       {
           m_sortColumn = column;
           Q_EMIT sortColumnChanged();
   
           // If source model is already set, reorder to apply the new sort column
           if (sourceModel() && !m_proxyToSourceMap.empty())
           {
               reorder();
           }
       }
   }

2. QML 属性绑定 (FullscreenFrame.qml):
   对于 itemMoveTransition.enabled 的设置，如果逻辑上需要它始终跟随 LauncherController.currentFrame 的状态，建议使用绑定代替命令式赋值：

   // 建议改为属性绑定（如果业务逻辑允许）
   itemMoveTransition.enabled: LauncherController.currentFrame === "FullscreenFrame"

   如果必须放在 onCompleted 中（例如只需要初始化一次），请确保添加注释说明原因，以免后续维护者误以为是遗漏的绑定。

3. 文档完善 (sortproxymodel.h):
   虽然添加了 @note，但可以进一步明确 sortColumn 的默认值（如果有的话），以及它与 sortRole 的关系（例如：sortRole 决定按什么数据排序，sortColumn 决定按模型中的哪一列排序，尽管对于 QAbstractListModel 这种单列模型，column 通常为 0）。

总结

这段代码修改整体质量较高，成功地将命令式调用转换为声明式属性，提升了代码的可维护性和 QML 风格的一致性。逻辑上安全，考虑了边界条件。主要的改进点在于清理未使用的变量以及考虑 QML 端是否可以使用属性绑定来替代 onCompleted 中的条件判断。

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: BLumia, wjyrich

The full list of commands accepted by this bot can be found here.

/forcemerge

This pr force merged! (status: blocked)