QtTaskTree::QCustomTask Class
template <typename Task, typename Adapter = QtTaskTree::QDefaultTaskAdapter<Task>, typename Deleter = std::default_delete<Task>> class QtTaskTree::QCustomTask用于声明自定义任务项并定义其设置和完成处理程序的类模板。更多
| 头文件： | #include <qtasktree.h> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS TaskTree)target_link_libraries(mytarget PRIVATE Qt6::TaskTree) |
| qmake： | QT += tasktree |
| 自 | Qt 6.11 |
| 继承： | QtTaskTree::ExecutableItem |
注意：该类中的所有函数都是可重入的。
公共类型
公共函数
| QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always) |
相关非成员
| QBarrierTask | |
| QNetworkReplyWrapperTask | |
| QProcessTask | |
| QTaskTreeTask | |
| QTcpSocketWrapperTask | |
| QThreadFunctionTask | |
| QTimeoutTask |
详细描述
描述任务树配方中的自定义任务项。
自定义任务名称是使用 QCustomTask 模板和给定的任务、适配器和删除器用唯一名称别名的。例如，QThreadFunctionTask<T> 是 QCustomTask 的别名，它被定义为与QThreadFunction<T> 一起工作的关联任务类。下表包含 TaskTree 库提供的自定义任务及其关联任务类：
| 别名任务名称 | 关联任务类 | 简要说明 |
|---|---|---|
| QBarrierTask | QBarrier | 启动等待者任务。 |
| QThreadFunctionTask<返回类型 | QThreadFunction<返回类型 | 启动异步任务。在单独的线程中运行。 |
| QProcessTask | QProcess | 启动进程。 |
| QNetworkReplyWrapperTask | QNetworkReplyWrapper | 发送网络查询。 |
| QTaskTreeTask | QTaskTree | 启动嵌套任务树。 |
| QTcpSocketWrapperTask | QTcpSocketWrapper | 建立 TCP 连接 |
| QTimeoutTask | std::chrono::milliseconds | 启动计时器。 |
Task 模板参数为必选参数，用于指定运行中的QTaskTree 在成为 recipe 的一部分时将实例化什么类型的Task 。Task 类型必须是默认可构造的。
Adapter 模板参数是可选参数。如果QDefaultTaskAdapter<Task> 可以适应Task 类型，则可以跳过它。否则，某些Task 的Adapter 需要具有以下形式：
class Adapter { public: void operator()(Task *task, QTaskInterface *iface) { ... } };
执行上面的 operator() 来启动task ，并在任务完成后对传递的iface 调用QTaskInterface::reportDone() 方法。
保证传入的Task 和QTaskInterface 比传入的Adapter 寿命长。如有必要，Adapter 的析构函数仍可访问传入的Task 。
更多详情，请参阅QTaskInterface 。
Deleter 模板参数为可选参数。默认情况下，使用std::default_delete<Task> 。当运行中的Task 的析构函数有可能阻塞调用线程时，自定义Deleter 就很有用。与其阻塞，自定义删除程序可以将运行中的任务转移到一个单独的线程中，并在该线程中实现阻塞销毁。这样，运行中的任务就可以通过阻塞析构函数实现快速销毁（从调用线程中看到）。
另请参见 QTaskInterface 。
成员类型文档
[alias] QCustomTask::TaskDoneHandler
std::function<QtTaskTree::DoneResult(const Task &, QtTaskTree::DoneWith)> 或DoneResult 的别名。
TaskDoneHandler 是自定义任务元素构造函数的可选参数。任何具有上述签名的函数在作为任务完成处理程序传递时，都将在任务执行结束后、执行的最终结果向父组群报告之前被运行中的任务树调用。
在处理程序的主体中，您可以检索已完成任务的最终数据。附加参数（包括存储空间）可通过 lambda 捕捉传递给处理程序。此外，还可以动态决定任务是以其返回值结束，还是对最终结果进行调整。
DoneWith 参数是可选的，您的完成处理程序可以省略它。提供该参数时，它将保存任务最终结果的相关信息，并将报告给任务的父节点。
如果不打算从已完成任务中读取任何数据，则可以省略const Task & 参数。
返回的DoneResult 值是可选的，您的处理程序可以返回void 。在这种情况下，任务的最终结果将等于DoneResult 参数指示的值。当处理程序返回DoneResult 值时，任务的最终结果可能会在完成处理程序的正文中根据返回值进行调整。
对于DoneResult 类型的 TaskDoneHandler，不会执行额外的处理，任务会无条件地以传入的DoneResult 值结束。
另请参阅 QCustomTask(),TaskSetupHandler, 和GroupDoneHandler 。
[alias] QCustomTask::TaskSetupHandler
std::function<SetupResult(Task &)> 的类型别名。
TaskSetupHandler 是自定义任务元素构造函数的可选参数。任何具有上述签名的函数在作为任务设置处理程序传递时，都将在任务创建后、启动前被运行中的任务树调用。
在处理程序的主体中，您可以根据需要配置任务。附加参数（包括存储空间）可通过 lambda 捕捉传递给处理程序。您可以动态决定是启动任务还是在任务成功或出错时跳过任务。
注意： 不要自己在启动处理程序内启动任务。QTaskTree QTaskTree 已经知道如何启动任务，这要归功于传递给QCustomTask<Task, Adapter, Deleter> 构造函数的适配器模板参数。
处理程序的返回值指示运行中的任务树在处理程序调用结束后如何继续。SetupResult::Continue 的返回值指示任务树继续运行，即执行相关的Task 。SetupResult::StopWithSuccess 或SetupResult::StopWithError 的返回值会指示任务树跳过任务的执行，并分别在成功或出错的情况下立即完成任务。
当返回类型为SetupResult::StopWithSuccess 或SetupResult::StopWithError 时，任务的已完成处理程序（如果提供）不会被调用。
自定义任务的构造函数也接受std::function<void(Task &)> 的缩写形式，即返回值为void 。在这种情况下，假定返回值为SetupResult::Continue 。
另请参阅 QCustomTask(),TaskDoneHandler, 和GroupSetupHandler 。
成员函数文档
[explicit] template <
typename SetupHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskSetupHandler,
typename DoneHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskDoneHandler,
std::enable_if_t<!std::is_same_v<q20::remove_cvref_t<SetupHandler>, QCustomTask<Task, Adapter, Deleter>>, bool> = true
>
QCustomTask::QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)
构建一个 QCustomTask 实例，并将setup 和done 处理程序附加到任务中。当运行中的任务树要启动任务时，它会实例化相关的Task 对象，调用setup 处理程序并引用已创建的任务，然后启动任务。当运行中的任务结束时，任务树会调用done 处理程序，并将const 作为已创建任务的引用。
传递的setup 处理程序属于TaskSetupHandler 类型。例如
static void parseAndLog(const QString &input); ... const QString input = ...; const auto onFirstSetup = [input](QThreadFunction<void> &task) { if (input == "Skip") return SetupResult::StopWithSuccess; // This task won't start, the next one will if (input == "Error") return SetupResult::StopWithError; // This task and the next one won't start task.setThreadFunctionData(parseAndLog, input); // This task will start, and the next one will start after this one finished with success return SetupResult::Continue; }; const auto onSecondSetup = [input](QThreadFunction<void> &task) { task.setThreadFunctionData(parseAndLog, input); }; const Group group { QThreadFunctionTask<void>(onFirstSetup), QThreadFunctionTask<void>(onSecondSetup) };
done 处理程序属于TaskDoneHandler 类型。默认情况下，只要任务完成，就会调用done 处理程序。如果希望仅在任务执行成功、失败或取消时调用处理程序，请为callDone 参数传递一个非默认值。
另请参阅 TaskSetupHandler 和TaskDoneHandler 。
相关非成员
[alias] QBarrierTask
QCustomTask<QBarrier> 的别名类型，用于配方内部。
[alias] QNetworkReplyWrapperTask
QCustomTask<QNetworkReplyWrapper> 的别名类型，用于配方内部。
[alias] QProcessTask
为QCustomTask<QProcess> 输入别名，使用QProcessTaskDeleter ，以便在食谱中使用。
[alias] QTaskTreeTask
QCustomTask<QTaskTree> 的别名类型，用于配方内部。
[alias] QTcpSocketWrapperTask
QCustomTask<QTcpSocketWrapper> 的别名类型，用于配方内部。
[alias] template <typename ResultType> QThreadFunctionTask
QCustomTask<QThreadFunction<ResultType>> 的类型别名，用于配方内部。
[alias] QTimeoutTask
键入QCustomTask<std::chrono::milliseconds> 的别名，在配方中使用。std::chrono::milliseconds 用于设置超时持续时间。默认超时时间为std::chrono::milliseconds::zero() ，也就是说，一旦控件返回到正在运行的事件循环，QTimeoutTask 就会结束。
使用示例：
using namespace std::chrono; using namespace std::chrono_literals; const auto onSetup = [](milliseconds &timeout) { timeout = 1000ms; } const auto onDone = [] { qDebug() << "Timed out."; } const Group root { QTimeoutTask(onSetup, onDone) };
另请参阅 timeoutTask().
© 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.
