QtTaskTree::GroupItem Class
class QtTaskTree::GroupItemGroupItem 代表可能作为任何Group 组成部分的基本元素。更多内容...
| 标题： | #include <qtasktree.h> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS TaskTree) target_link_libraries(mytarget PRIVATE Qt6::TaskTree) |
| qmake： | QT += tasktree |
| 自： | Qt 6.11 |
| 被继承于： | |
| 状态： | 技术预览 |
该类处于技术预览阶段，内容可能会发生变更。
注意：该类中的所有函数均为可重入函数。
公共类型
公共函数
| GroupItem(const QtTaskTree::GroupItems &children) | |
| GroupItem(const QtTaskTree::Storage<StorageStruct> &storage) | |
| GroupItem(std::initializer_list<QtTaskTree::GroupItem> children) | |
| GroupItem(QtTaskTree::GroupItem &&other) |
详细说明
GroupItem 是一个基本元素，可以作为任何Group 的一部分。它封装了任何 GroupItem 子类所提供的功能。它是一种值类型，即使该 GroupItem 实例最初是通过子类的构造函数创建的，复制它也是安全的。
GroupItem主要有四种类型：
| GroupItem 类型 | 简要说明 |
|---|---|
| QCustomTask | 定义异步任务类型以及任务的开始、完成和错误处理程序。通过唯一的任务名称进行别名标识，例如QThreadFunctionTask<ResultType> 或QNetworkReplyWrapperTask 。异步任务是使用任务树的主要原因。 |
| Group | 用于容纳其他组项的容器。由于该组属于 GroupItem 类型，因此可以将其嵌套在另一个组中。对其父组而言，该组被视为单个异步任务。 |
| 包含以下内容的 GroupItemStorage | 允许组的子任务之间交换数据。当包含Storage 的GroupItem被放置在组内时，任务树会在进入该组之前实例化存储的数据对象，并在离开该组之后立即销毁它。 |
| 其他组控件 | 由 `ExecutionMode ` 或 `workflowPolicy()` 返回的项目会影响组的运行行为。由 `onGroupSetup()` 或 `onGroupDone()` 返回的项目则定义了在组开始或结束执行时调用的自定义处理程序。 |
成员类型文档
[alias] GroupItem::GroupDoneHandler
std::function<DoneResult(DoneWith)> 或DoneResult 的类型别名。
GroupDoneHandler 是onGroupDone() 元素的一个参数。任何具有上述签名的函数，当作为组完成处理程序传递时，将在组执行结束时由正在运行的任务树调用。
DoneWith 参数是可选的，您的完成处理程序可以省略它。如果提供了该参数，它将包含有关该组最终结果的信息，这些信息将报告给其父任务。
返回的 `DoneResult ` 值是可选的，您的处理程序可以返回 `void ` 代替。在这种情况下，该组的最终结果将等于 `DoneWith ` 参数所指示的值。当处理程序返回 `DoneResult ` 值时，该组的最终结果可以在 `done` 处理程序的主体内部通过返回值进行调整。
对于类型为DoneResult 的 GroupDoneHandler，不会执行任何额外处理，且该组将无条件地以传入的DoneResult 值结束，忽略该组的工作流策略。
另请参阅 onGroupDone()、GroupSetupHandler 以及QCustomTask::TaskDoneHandler 。
[alias] GroupItem::GroupSetupHandler
std::function<SetupResult()> 的类型别名。
GroupSetupHandler 是onGroupSetup() 元素的一个参数。任何具有上述签名的函数，当作为组设置处理程序传递时，都将在组执行开始时由正在运行的任务树调用。
处理程序的返回值用于指示运行中的组在处理程序调用完成后如何继续。SetupResult::Continue 的默认返回值指示组继续运行，即开始执行其子任务。SetupResult::StopWithSuccess 或SetupResult::StopWithError 的返回值则分别指示组跳过子任务的执行，并立即以成功或错误状态结束。
当返回类型为SetupResult::StopWithSuccess 或SetupResult::StopWithError 时，该组的完成处理程序（如果提供）将在随后立即被同步调用。
注意：即使 组设置处理程序返回StopWithSuccess 或StopWithError ，组的完成处理程序仍会被调用。此行为与任务完成处理程序的行为不同，未来可能会发生变化。
onGroupSetup() 元素也接受简写形式的函数std::function<void()> ，即返回值为void 。在这种情况下，默认假设返回值为SetupResult::Continue 。
另请参阅 onGroupSetup()、GroupDoneHandler 以及QCustomTask::TaskSetupHandler 。
成员函数文档
GroupItem::GroupItem(const QtTaskTree::GroupItems &children)
根据给定的children 列表构建一个GroupItem元素。
当该 GroupItem 元素被QTaskTree 解析时，它会被直接替换为对应的children 。
当使用Group 元素列表来构建 元素时，此构造函数非常有用：
static GroupItems getItems();
...
const Group root {
parallel,
finishAllAndSuccess,
getItems(), // GroupItems list is wrapped into a single GroupItem element
onGroupSetup(...),
onGroupDone(...)
};若要创建子树，请改用 `Group `。
另请参阅 Group 。
template <typename StorageStruct> GroupItem::GroupItem(const QtTaskTree::Storage<StorageStruct> &storage)
构建一个包含storage 对象的GroupItem元素。
当正在运行的任务树进入包含此GroupItem 的Group 元素时，会动态创建一个StorageStruct 实例。
当该组在执行完成后即将被离开时，先前实例化的StorageStruct 将被删除。
可以通过Storage::operator->()、Storage::operator*() 或Storage::activeStorage() 方法，从父Group 元素（包括嵌套组及其任务）的任何处理程序主体内部访问动态创建的StorageStruct 实例。
另请参阅 Storage 。
GroupItem::GroupItem(std::initializer_list<QtTaskTree::GroupItem> children)
这是一个重载函数。
另请参阅 GroupItem(const QtTaskTree::GroupItems &children)。
[constexpr noexcept default] GroupItem::GroupItem(QtTaskTree::GroupItem &&other)
通过 Move 构造一个 `GroupItem` 的实例。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
