QScxmlStateMachine Class
QScxmlStateMachine 类为由 SCXML 文件生成的状态机提供了一个接口。更多内容...
| 头文件： | #include <QScxmlStateMachine> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Scxml) target_link_libraries(mytarget PRIVATE Qt6::Scxml) |
| qmake： | QT += scxml |
| 在 QML 中： | ScxmlStateMachine |
| 继承自： | QObject |
属性
|
|
公共函数
| QStringList | activeStateNames(bool compress = true) const |
| QBindable<QScxmlDataModel *> | bindableDataModel() |
| QBindable<QVariantMap> | bindableInitialValues() |
| QBindable<bool> | bindableInitialized() const |
| QBindable<QList<QScxmlInvokableService *>> | bindableInvokedServices() |
| QBindable<QScxmlCompiler::Loader *> | bindableLoader() |
| QBindable<QScxmlTableData *> | bindableTableData() |
| void | cancelDelayedEvent(const QString &sendId) |
| QMetaObject::Connection | connectToEvent(const QString &scxmlEventSpec, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToEvent(const QString &scxmlEventSpec, const QObject *context, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToEvent(const QString &scxmlEventSpec, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToState(const QString &scxmlStateName, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToState(const QString &scxmlStateName, const QObject *context, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection) |
| QMetaObject::Connection | connectToState(const QString &scxmlStateName, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection) |
| QScxmlDataModel * | dataModel() const |
| QVariantMap | initialValues() |
| QList<QScxmlInvokableService *> | invokedServices() const |
| bool | isActive(const QString &scxmlStateName) const |
| bool | isDispatchableTarget(const QString &target) const |
| bool | isInitialized() const |
| bool | isInvoked() const |
| bool | isRunning() const |
| QScxmlCompiler::Loader * | loader() const |
| QString | name() const |
| QList<QScxmlError> | parseErrors() const |
| QString | sessionId() const |
| void | setDataModel(QScxmlDataModel *model) |
| void | setInitialValues(const QVariantMap &initialValues) |
| void | setLoader(QScxmlCompiler::Loader *loader) |
| void | setRunning(bool running) |
| void | setTableData(QScxmlTableData *tableData) |
| QStringList | stateNames(bool compress = true) const |
| void | submitEvent(QScxmlEvent *event) |
| void | submitEvent(const QString &eventName) |
| void | submitEvent(const QString &eventName, const QVariant &data) |
| QScxmlTableData * | tableData() const |
公共槽位
信号
| void | dataModelChanged(QScxmlDataModel *model) |
| void | finished() |
| void | initialValuesChanged(const QVariantMap &initialValues) |
| void | initializedChanged(bool initialized) |
| void | invokedServicesChanged(const QList<QScxmlInvokableService *> &invokedServices) |
| void | loaderChanged(QScxmlCompiler::Loader *loader) |
| void | log(const QString &label, const QString &msg) |
| void | reachedStableState() |
| void | runningChanged(bool running) |
| void | tableDataChanged(QScxmlTableData *tableData) |
静态公共成员
| QScxmlStateMachine * | fromData(QIODevice *data, const QString &fileName = QString()) |
| QScxmlStateMachine * | fromFile(const QString &fileName) |
| std::function<void (bool)> | onEntry(Functor functor) |
| std::function<void (bool)> | onEntry(const QObject *receiver, const char *method) |
| std::function<void (bool)> | onEntry(const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver, PointerToMemberFunction method) |
| std::function<void (bool)> | onExit(Functor functor) |
| std::function<void (bool)> | onExit(const QObject *receiver, const char *method) |
| std::function<void (bool)> | onExit(const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver, PointerToMemberFunction method) |
受保护函数
| bool | isActive(int stateIndex) const |
详细说明
QScxmlStateMachine 是状态图 XML（SCXML）的一种实现。
SCXML 文件中定义的所有状态均可作为 QScxmlStateMachine 的属性访问。这些属性为布尔值，用于指示状态是活动状态还是非活动状态。
注意：QScxmlStateMachine 需要一个QEventLoop 才能正常工作。事件循环用于实现事件的delay 属性，并在从嵌套（或父）状态机接收事件时安排状态机的处理。
属性文档
[bindable] dataModel : QScxmlDataModel*
注意：此 属性支持QProperty 绑定。
该属性包含将用于此状态机的数据模型。
SCXML 数据模型在《SCXML 规范 - 5 数据模型与数据操作》中进行了描述。有关支持的数据模型的更多信息，请参阅“SCXML 合规性”。
在状态机已进行initialized 时更改数据模型的情况未在SCXML标准中规定，并将导致未定义的行为。
访问函数：
| QScxmlDataModel * | dataModel() const |
| void | setDataModel(QScxmlDataModel *model) |
通知器信号：
| void | dataModelChanged(QScxmlDataModel *model) |
另请参阅 QScxmlDataModel 、QScxmlNullDataModel 以及QScxmlCppDataModel 。
[bindable] initialValues : QVariantMap
注意：此 属性支持QProperty 绑定。
该属性保存用于配置数据模型的初始值。
访问函数：
| QVariantMap | initialValues() |
| void | setInitialValues(const QVariantMap &initialValues) |
通知器信号：
| void | initialValuesChanged(const QVariantMap &initialValues) |
另请参阅 QScxmlStateMachine::init() 和QScxmlDataModel 。
[bindable read-only] initialized : bool
注意：此 属性支持QProperty 绑定。
该属性表示状态机是否已初始化。
如果状态机已初始化，则该属性值为true ；否则，其值为false 。
访问函数：
| bool | isInitialized() const |
通知器信号：
| void | initializedChanged(bool initialized) |
另请参见 QScxmlStateMachine::init() 和QScxmlDataModel 。
[read-only] invoked : const bool
该属性表示状态机是否由外部状态机调用。
true 当状态机作为服务通过<invoke> 元素启动时，该属性为false ；否则，该属性为 。
访问函数：
| bool | isInvoked() const |
[bindable read-only] invokedServices : QList<QScxmlInvokableService*>
注意：此 属性支持QProperty 绑定。
该属性包含从主状态机（可能为递归调用）调用的 SCXML 服务列表。
访问函数：
| QList<QScxmlInvokableService *> | invokedServices() const |
通知器信号：
| void | invokedServicesChanged(const QList<QScxmlInvokableService *> &invokedServices) |
[bindable] loader : QScxmlCompiler::Loader*
注意：此 属性支持QProperty 绑定。
该属性保存当前用于解析和加载状态机 URI 的加载器。
访问函数：
| QScxmlCompiler::Loader * | loader() const |
| void | setLoader(QScxmlCompiler::Loader *loader) |
通知器信号：
| void | loaderChanged(QScxmlCompiler::Loader *loader) |
[read-only] name : const QString
该属性保存由<scxml> 标签的name属性设置的状态机名称。
访问函数：
| QString | name() const |
[read-only] parseErrors : const QList<QScxmlError>
该属性存储了从 SCXML 文件创建状态机时发生的解析错误列表。
访问函数：
| QList<QScxmlError> | parseErrors() const |
running : bool
该属性保存了该状态机的运行状态
访问函数：
| bool | isRunning() const |
| void | setRunning(bool running) |
通知器信号：
| void | runningChanged(bool running) |
另请参阅 ` start()`。
[read-only] sessionId : const QString
该属性存储当前状态机的会话 ID。
会话 ID 用于父子状态机之间的消息路由。如果某个状态机由<invoke> 元素启动，则它发送的任何事件的invokeid 字段都会被设置为该会话 ID。 状态机将使用事件的来源（由<send> 元素中的target或targetexpr属性设定）来将消息分发到正确的子状态机。
访问函数：
| QString | sessionId() const |
另请参阅 QScxmlEvent::invokeId()。
[bindable] tableData : QScxmlTableData*
注意：此 属性支持QProperty 绑定。
该属性存储从 SCXML 文件生成 C++ 代码时所使用的表格数据。
实现状态机的类将使用此属性来赋值生成的表格数据。状态机不会获取表格数据的所有权。
访问函数：
| QScxmlTableData * | tableData() const |
| void | setTableData(QScxmlTableData *tableData) |
通知器信号：
| void | tableDataChanged(QScxmlTableData *tableData) |
成员函数文档
[invokable] QStringList QScxmlStateMachine::activeStateNames(bool compress = true) const
获取所有活动状态的状态名称列表。
根据定义，当某个状态处于活动状态时，其所有父状态也处于活动状态。当 `compress ` 的值为 `true `（默认值）时，系统将过滤掉父状态，仅返回叶状态；当其值为 `false` 时，将返回完整的活动状态列表。
注意：该函数 可通过元对象系统及 QML 调用。详见Q_INVOKABLE 。
[invokable] void QScxmlStateMachine::cancelDelayedEvent(const QString &sendId)
取消具有指定sendId 的延迟事件。
注意： 可通过元对象系统或从 QML 中调用此 函数。参见Q_INVOKABLE 。
template <typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection)
template <typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, const QObject *context, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection)
根据scxmlEventSpec 指定的事件，创建一个从type 到functor 的连接，其中 可以是函子，也可以是可选对象context 的成员函数。
接收器的functor 必须将QScxmlEvent 作为参数。
与 SCXML 文档中的事件规范不同，此处的scxmlEventSpec 不允许包含空格。若要连接多个具有不同前缀的事件，必须多次调用connectToEvent()。
返回一个连接句柄，该句柄可用于后续断开连接。
QMetaObject::Connection QScxmlStateMachine::connectToEvent(const QString &scxmlEventSpec, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection)
创建从由scxmlEventSpec 指定的事件到receiver 对象中method 的、指定type 的连接。接收器的method 可能将QScxmlEvent 作为参数。例如：
void mySlot(const QScxmlEvent &event);与 SCXML 文档中的事件规范不同，此处的scxmlEventSpec 中不允许包含空格。若要连接到多个具有不同前缀的事件，必须多次调用 connectToEvent()。
该方法返回一个连接句柄，稍后可用于断开连接。
template <typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection)
template <typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, const QObject *context, Functor &&functor, Qt::ConnectionType type = Qt::AutoConnection)
创建一个连接，将给定的type 从由scxmlStateName 指定的状态连接到functor ，后者可以是 functor，也可以是可选的context 对象的成员函数。
接收方的functor 必须接受一个布尔参数，该参数用于指示已连接的状态是处于活动状态还是非活动状态。
返回连接的句柄，该句柄可在后续用于断开连接。
QMetaObject::Connection QScxmlStateMachine::connectToState(const QString &scxmlStateName, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection)
创建一个连接，将由scxmlStateName 标识的状态与receiver 对象中的method 建立连接，该连接属于type 。接收方的method 方法可接受一个布尔参数，用于指示被连接的状态是处于活动状态还是非活动状态。例如：
void mySlot(bool active);返回连接的句柄，该句柄可用于后续断开连接。
QScxmlDataModel *QScxmlStateMachine::dataModel() const
返回状态机所使用的数据模型。
注意： 这是属性 dataModel 的获取 函数。
另请参阅 setDataModel()。
[signal] void QScxmlStateMachine::finished()
当状态机到达顶级终态时，会发出此信号。
另请参阅 running 。
[static] QScxmlStateMachine *QScxmlStateMachine::fromData(QIODevice *data, const QString &fileName = QString())
通过读取由 `data` 指定的 `QIODevice ` 文件来创建状态机。
该方法将始终返回一个状态机。如果在读取 SCXML 文件fileName 时发生错误，则无法启动该状态机。可通过调用parseErrors() 方法获取错误信息。
另请参阅 parseErrors()。
[static] QScxmlStateMachine *QScxmlStateMachine::fromFile(const QString &fileName)
根据fileName 指定的SCXML文件创建一个状态机。
该方法始终返回一个状态机。如果在读取 SCXML 文件时发生错误，则无法启动该状态机。可通过调用parseErrors() 方法获取错误信息。
另请参阅 parseErrors()。
[slot] bool QScxmlStateMachine::init()
初始化状态机。
状态机的初始化包括调用QScxmlDataModel::setup()方法、为<data> 元素设置初始值，以及执行<scxml> 标签中的所有<script> 标签。初始数据值取自initialValues 属性。
若发生解析错误或任何初始化步骤失败，则返回false ；否则返回true 。
[invokable] bool QScxmlStateMachine::isActive(const QString &scxmlStateName) const
如果由 `scxmlStateName ` 指定的状态处于活动状态，则返回 `true `；否则返回 `false `。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[protected] bool QScxmlStateMachine::isActive(int stateIndex) const
如果 ID 为stateIndex 的状态处于活动状态，则返回 `true `。
该方法是 SCXML 状态机编译表示接口的一部分。它仅应供内部使用，且仅应由从 SCXML 文档编译而来的状态机使用。
[invokable] bool QScxmlStateMachine::isDispatchableTarget(const QString &target) const
如果该状态机能够分发一则发往target 的消息，则返回 `true `。
有效目标包括：
#_parent如果当前状态机是由<invoke>#_internal针对当前状态机#_scxml_sessionid，其中sessionid是当前状态机的会话 ID#_servicename，其中servicename是该状态机使用<invoke>启动的某项服务的 ID 或名称
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
bool QScxmlStateMachine::isRunning() const
如果状态机正在运行，则返回true ；否则返回false 。
注意： 这是属性running 的获取 函数。
另请参阅 setRunning() 和runningChanged()。
[signal] void QScxmlStateMachine::log(const QString &label, const QString &msg)
如果在 SCXML 中使用了 `<log> ` 标签，则会发出此信号。label 是 `<log> ` 标签的`label`属性的值。msg 是 `<log> ` 标签中经过求值的`expr` 属性的值。如果不存在`expr` 属性，则返回空字符串。
[static] template <typename Functor> std::function<void (bool)> QScxmlStateMachine::onEntry(Functor functor)
返回一个 functor，该 functor 接受一个布尔参数，当该参数为 `true` 时，会调用给定的 `functor `。给定的 `functor ` 不得接受任何参数。
这对于封装connectToState()的处理程序非常有用，这些处理程序仅应在进入该状态时执行。
[static] std::function<void (bool)> QScxmlStateMachine::onEntry(const QObject *receiver, const char *method)
返回一个接受布尔值参数的函子，当该参数为true 且receiver 尚未被删除时，该函子将使用QMetaObject::invokeMethod()调用receiver 上的指定method 。
给定的method 不能接受任何参数。method 是普通的方法名，不包含在SIGNAL() 或SLOT() 中。
这有助于封装connectToState()的处理程序，这些处理程序仅应在进入该状态时执行。
[static] template <typename PointerToMemberFunction> std::function<void (bool)> QScxmlStateMachine::onEntry(const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver, PointerToMemberFunction method)
返回一个函子，该函子接受一个布尔参数，当该参数为true 且receiver 尚未被删除时，会在receiver 上调用给定的method 。给定的method 不得接受任何参数。
这对于封装connectToState()的处理程序非常有用，这些处理程序仅应在进入该状态时执行。
[static] template <typename Functor> std::function<void (bool)> QScxmlStateMachine::onExit(Functor functor)
返回一个接受布尔参数的函子，当该参数为false 时，会调用给定的functor 。给定的functor 不能接受任何参数。
这对于封装connectToState()的处理程序非常有用，这些处理程序仅应在离开当前状态时才被执行。
[static] std::function<void (bool)> QScxmlStateMachine::onExit(const QObject *receiver, const char *method)
返回一个接受布尔类型参数的函子，当该参数为false 且receiver 尚未被删除时，该函子将使用QMetaObject::invokeMethod()调用receiver 上的method 。
给定的method 不能接受任何参数。method 是普通方法名，不包含在SIGNAL(...)或SLOT(...)中。
这有助于封装connectToState() 的处理程序，这些处理程序仅应在状态被退出时执行。
[static] template <typename PointerToMemberFunction> std::function<void (bool)> QScxmlStateMachine::onExit(const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver, PointerToMemberFunction method)
返回一个函子，该函子接受一个布尔参数，并在该参数为false 且receiver 尚未被删除时，对receiver 调用给定的method 。给定的method 不得接受任何参数。
这对于封装connectToState()的处理程序非常有用，这些处理程序仅应在离开该状态时才被执行。
[signal] void QScxmlStateMachine::reachedStableState()
当宏步骤结束时事件队列为空，或者达到最终状态时，会发出此信号。
[signal] void QScxmlStateMachine::runningChanged(bool running)
当running 属性被修改且参数为running 时，会触发此信号。
注意： 这是属性running 的通知器 信号。
void QScxmlStateMachine::setDataModel(QScxmlDataModel *model)
将此状态机的数据模型设置为model 。状态机与模型之间存在1:1的对应关系。模型一旦设置，便无法再进行更改。此后任何尝试使用此方法设置模型的操作都将被忽略。
注意： 这是属性 `dataModel`的设置器 函数。
另请参阅 dataModel()。
void QScxmlStateMachine::setRunning(bool running)
如果running 的值为true ，则启动状态机；否则停止状态机。
注意： 这是属性running 的设置 函数。
另请参阅 start()、stop()、isRunning() 以及runningChanged()。
[slot] void QScxmlStateMachine::start()
启动此状态机。当进入最终的顶级状态时，状态机将发出finished()信号。
注意： 如果没有正在运行的事件循环（例如通过QCoreApplication::exec() 或QApplication::exec() 启动的主应用程序事件循环），状态机 将无法运行。
注意：在调用 stop() 之后再调用 start() 并不会导致其配置完全重置，因此强烈建议不要这样做。
注意：启动 已完成的机器会触发警告。
另请参阅 runningChanged()、setRunning()、stop() 和finished()。
[invokable] QStringList QScxmlStateMachine::stateNames(bool compress = true) const
获取所有州的州名列表。
当 `compress ` 设置为 `true `（默认值）时，将过滤掉包含子状态的状态，仅返回叶状态。当设置为 `false` 时，将返回所有状态的完整列表。
返回的列表不包含可能存在的嵌套状态机的状态。
注意： 列表中状态名的顺序 即为这些状态在 SCXML 文档中出现的顺序。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[slot] void QScxmlStateMachine::stop()
停止此状态机。该状态机将不再执行任何状态转换。其running 属性被设置为false 。
另请参阅 runningChanged()、start() 和setRunning()。
[invokable] void QScxmlStateMachine::submitEvent(QScxmlEvent *event)
根据事件的优先级，将 SCXML 事件 `event ` 提交到内部或外部事件队列。
如果设置了延迟，则该事件将在超时后被排队待发。状态机将接管event ，并在处理完成后将其删除。
注意：此 函数可通过元对象系统和 QML 调用。参见Q_INVOKABLE 。
[invokable] void QScxmlStateMachine::submitEvent(const QString &eventName)
一个实用方法，用于创建并提交一个名称为指定eventName 的外部事件。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QScxmlStateMachine::submitEvent(const QString &eventName, const QVariant &data)
一个实用方法，用于创建并提交一个外部事件，其名称为指定的eventName ，有效负载数据为data 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
© 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.
