PySide6.QtQml.QQml引擎¶

class QQmlEngine¶

QQmlEngine 类提供了一个用于实例化 QML 组件的环境。更多…

继承者： QQmlApplicationEngine

概要¶

属性¶

offlineStoragePathᅟ - 用于存储离线用户数据的目录

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述¶

一个QQmlEngine用于管理components以及从中创建的对象，并执行它们的绑定和函数。QQmlEngine还继承自QJSEngine，这使得您的QML组件和JavaScript代码之间能够无缝集成。

每个QML组件都在一个QQmlContext中实例化。在QML中，上下文是按层次结构排列的，这个层次结构由QQmlEngine管理。默认情况下，组件在root context中实例化。

另请参阅

QQmlComponent QQmlContext QML 全局对象 QQmlApplicationEngine

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property offlineStoragePathᅟ: str¶

此属性保存用于存储离线用户数据的目录。

返回放置SQL和其他离线存储的目录。

使用openDatabaseSync()创建的SQL数据库存储在这里。

默认是平台标准用户应用程序数据目录中的QML/OfflineStorage。

请注意，路径可能当前在文件系统中不存在，因此希望在此位置创建新文件的调用者应首先创建它 - 请参阅 QDir::mkpath()。

另请参阅

Qt Quick Local Storage QML Types

Access functions:

offlineStoragePath()
setOfflineStoragePath()
信号 offlineStoragePathChanged()

__init__([p=None])¶

Parameters:: p – QObject

使用给定的parent创建一个新的QQmlEngine。

addImageProvider(id, provider)¶

Parameters:

id – str
provider – QQmlImageProviderBase

设置用于通过image: url方案请求的图像的provider，主机为providerId。QQmlEngine拥有provider的所有权。

图像提供者支持位图和线程图像请求。有关实现和使用图像提供者的详细信息，请参阅QQuickImageProvider文档。

在加载任何QML源文件之前，应将所有必需的图像提供程序添加到引擎中。

另请参阅

removeImageProvider() QQmlImageProviderBase

addImportPath(dir)¶

Parameters:: dir – str

将 path 添加为引擎在基于URL的目录结构中搜索已安装模块的目录。

path 可以是本地文件系统目录、Qt 资源路径 (:/imports)、Qt 资源 URL (qrc:/imports) 或 URL。

path 在添加到导入路径列表之前将被转换为规范形式。

新添加的 path 将会首先出现在 importPathList() 中。

另请参阅 setImportPathList() , QML 模块 , 以及 QML 导入路径

addNamedBundle(arg__1, arg__2)¶

Parameters:

arg__1 – str
arg__2 – 字符串

Return type:

布尔

注意

此函数已弃用。

addPluginPath(dir)¶

Parameters:: dir – str

将 path 添加为引擎搜索导入模块（在 qmldir 文件中引用）的本机插件的目录。

默认情况下，列表仅包含.，即引擎在qmldir文件本身的目录中搜索。

新添加的 path 将首先出现在 pluginPathList() 中。

另请参阅

setPluginPathList()

addUrlInterceptor(urlInterceptor)¶

Parameters:: urlInterceptor – QQmlAbstractUrlInterceptor

添加一个urlInterceptor，用于在QML中解析URL时使用。这也适用于用于加载脚本文件和QML类型的URL。在引擎加载文件时，不应修改URL拦截器，否则URL选择可能不一致。当提供多个URL拦截器时，将按照它们添加的顺序为每个URL调用。

QQmlEngine 不拥有拦截器的所有权，也不会删除它。

baseUrl()¶

Return type:: QUrl

返回此引擎的基础URL。基础URL仅在将相对URL传递给QQmlComponent构造函数时用于解析组件。

如果未明确设置基本URL，此方法返回应用程序的当前工作目录。

另请参阅

setBaseUrl()

captureProperty(object, property)¶

Parameters:

object – QObject
属性 – QMetaProperty

clearComponentCache()¶

清除引擎的内部组件缓存。

此函数会导致引擎先前加载的大多数组件的属性元数据被销毁。它通过从引擎的组件缓存中删除未引用的组件来实现这一点。它不会删除仍然被引用的组件，因为这几乎肯定会导致后续的崩溃。

如果没有引用任何组件，此函数将引擎返回到不包含任何已加载组件数据的状态。这可能有助于重新加载先前组件集的较小子集，或加载先前加载组件的新版本。

一旦组件缓存被清除，必须加载组件才能创建任何新对象。

注意

从QML组件创建的任何现有对象都会保留其类型，即使您清除了组件缓存。这包括单例对象。如果在清除缓存后从相同的QML代码创建更多对象，新对象的类型将与旧对象不同。将这样的新对象分配给在清除缓存之前创建的对象的声明类型的属性将不起作用。

作为一般经验法则，确保在清除组件缓存时，没有从QML组件创建的对象仍然存在。

另请参阅

trimComponentCache() clearSingletons()

clearSingletons()¶

清除引擎拥有的所有单例。

此函数删除所有单例实例，删除引擎拥有的所有QObjects。这在调用clearComponentCache()之前确保没有留下任何QML创建的对象非常有用。

如果引擎拥有单例，则持有基于QObject的单例实例的QML属性将变为null；如果引擎不拥有它，则保留其值。单例不会通过访问现有的QML创建的对象自动重新创建。只有在实例化新组件时，单例才会重新创建。

另请参阅

clearComponentCache()

static contextForObject(object)¶

Parameters:: 对象 – QObject
Return type:: QQmlContext

返回 QQmlContext 的 object，如果没有设置上下文，则返回 nullptr。

当QQmlEngine实例化一个QObject时，会自动为其分配一个内部上下文。这些内部上下文是只读的。您无法在它们上设置上下文属性。

另请参阅

setContextForObject() qmlContext() qmlEngine() setContextProperty()

exit(retCode)¶

Parameters:: retCode – int

当引擎加载的QML希望以指定的返回代码retCode退出事件循环时，会发出此信号。

另请参阅

quit()

imageProvider(id)¶

Parameters:: id – str
Return type:: QQmlImageProviderBase

如果找到为providerId设置的图像提供者，则返回该提供者；否则返回None。

另请参阅

QQuickImageProvider

importPathList()¶

Return type:: 字符串列表

返回引擎在基于URL的目录结构中搜索已安装模块的目录列表。

例如，如果路径中包含/opt/MyApp/lib/imports，那么导入com.mycompany.Feature的QML将导致QQmlEngine在/opt/MyApp/lib/imports/com/mycompany/Feature/中查找该模块提供的组件。需要一个qmldir文件来定义类型版本映射，并可能包含QML扩展插件。

默认情况下，此列表包含QML导入路径中提到的路径。

另请参阅

addImportPath() setImportPathList()

importPlugin(filePath, uri, errors)¶

Parameters:

filePath – str
uri – 字符串
errors – QList

Return type:

布尔

注意

此函数已弃用。

使用“import”语句从QML导入模块。

导入名为 filePath 的插件，使用提供的 uri。如果插件成功导入，则返回 true；否则返回 false。

在失败且非空的情况下，errors 列表将包含任何发生的错误，并将其前置。

插件必须是一个实现了QQmlEngineExtensionPlugin接口的Qt插件。

注意

直接这样加载插件可能会混淆模块导入逻辑。为了使导入逻辑从特定位置加载插件，你可以使用 addPluginPath()。每个插件应该是你可以使用“import”语句导入的QML模块的一部分。

incubationController()¶

Return type:: QQmlIncubationController

返回当前设置的孵化控制器，如果未设置控制器则返回0。

另请参阅

setIncubationController()

interceptUrl(url, type)¶

Parameters:

url – QUrl
type – DataType

Return type:

QUrl

在给定的url上运行当前的URL拦截器，并根据给定的type返回结果。

markCurrentFunctionAsTranslationBinding()¶

如果在QML中作为绑定一部分的函数内部调用此方法，该绑定将被视为翻译绑定。

class I18nAwareClass : public QObject {

  //...

   QString text() const
   {
        if (auto engine = qmlEngine(this))
            engine->markCurrentFunctionAsTranslationBinding();
        return tr("Hello, world!");
   }
};

注意

如果您希望提供自己的替代方案来替代qsTr函数，此函数非常有用。为了确保在语言更改时更新从C++类暴露的属性，建议改为对LanguageChange事件做出反应。这是一种更通用的机制，当类在非QML上下文中使用时也有效，并且开销略小。然而，当类已经与QML引擎紧密绑定时，使用markCurrentFunctionAsTranslationBinding可能是可以接受的。有关更多详细信息，请参阅准备动态语言更改

另请参阅

retranslate

networkAccessManager()¶

Return type:: QNetworkAccessManager

返回一个通用的QNetworkAccessManager，可以被此引擎实例化的任何QML类型使用。

如果已经设置了QQmlNetworkAccessManagerFactory并且尚未创建QNetworkAccessManager，则将使用QQmlNetworkAccessManagerFactory来创建QNetworkAccessManager；否则返回的QNetworkAccessManager将没有设置代理或缓存。

另请参阅

setNetworkAccessManagerFactory()

networkAccessManagerFactory()¶

Return type:: QQmlNetworkAccessManagerFactory

返回当前的 QQmlNetworkAccessManagerFactory 。

另请参阅

setNetworkAccessManagerFactory()

offlineStorageDatabaseFilePath(databaseName)¶

Parameters:: databaseName – str
Return type:: 字符串

返回具有标识符 databaseName 的本地存储数据库所在（或将位于）的文件路径。

另请参阅

openDatabaseSync()

offlineStoragePath()¶

Return type:: 字符串

另请参阅

setOfflineStoragePath()

属性 offlineStoragePathᅟ 的获取器。

offlineStoragePathChanged()¶

当offlineStoragePath发生变化时，会发出此信号。

属性 offlineStoragePathᅟ 的通知信号。

outputWarningsToStandardError()¶

Return type:: 布尔

如果警告消息除了通过warnings()信号发出外，还会输出到stderr，则返回true，否则返回false。

默认值为true。

另请参阅

setOutputWarningsToStandardError()

pluginPathList()¶

Return type:: 字符串列表

返回引擎搜索导入模块（在qmldir文件中引用）的本地插件的目录列表。

默认情况下，列表仅包含.，即引擎在qmldir文件本身的目录中搜索。

另请参阅

addPluginPath() setPluginPathList()

quit()¶

当引擎加载的QML想要退出时，会发出此信号。

另请参阅

exit()

removeImageProvider(id)¶

Parameters:: id – str

移除providerId的图像提供者。

另请参阅

addImageProvider() QQuickImageProvider

removeUrlInterceptor(urlInterceptor)¶

Parameters:: urlInterceptor – QQmlAbstractUrlInterceptor

移除之前使用addUrlInterceptor添加的urlInterceptor。在引擎加载文件时不应修改URL拦截器，否则URL选择可能不一致。

这不会删除拦截器，而只是将其从引擎中移除。之后，您可以在相同或不同的引擎上重新使用它。

retranslate()¶

刷新所有使用标记为翻译的字符串的绑定表达式。

在您使用QCoreApplication::installTranslator安装新的翻译器后调用此函数，以确保您的用户界面显示最新的翻译。

rootContext()¶

Return type:: QQmlContext

返回引擎的根上下文。

根上下文由QQmlEngine自动创建。应该对引擎实例化的所有QML组件实例可用的数据应放在根上下文中。

应该仅对组件实例的子集可用的附加数据应添加到根上下文的子上下文中。

setBaseUrl(url)¶

Parameters:: url – QUrl

设置此引擎的基础URL为url。

另请参阅

baseUrl()

static setContextForObject(object, context)¶

Parameters:

object – QObject
context – QQmlContext

将QQmlContext设置为object的context。如果object已经有一个上下文，则会输出警告，但上下文不会更改。

当QQmlEngine实例化一个QObject时，上下文会自动设置。

另请参阅

contextForObject()

setImportPathList(paths)¶

Parameters:: paths – 字符串列表

将 paths 设置为引擎在基于URL的目录结构中搜索已安装模块的目录列表。

默认情况下，此列表包含QML导入路径中提到的路径。

警告

调用 setImportPathList 不会保留默认的导入路径。

另请参阅

importPathList() addImportPath()

setIncubationController(controller)¶

Parameters:: 控制器 – QQmlIncubationController

设置引擎的孵化controller。引擎只能有一个活动的控制器，并且它不会拥有该控制器的所有权。

另请参阅

incubationController()

setNetworkAccessManagerFactory(factory)¶

Parameters:: factory – QQmlNetworkAccessManagerFactory

设置用于创建QNetworkAccessManager的factory。

QNetworkAccessManager 用于 QML 的所有网络访问。通过实现一个工厂，可以创建具有专门缓存、代理和 cookie 支持的自定义 QNetworkAccessManager。

在执行引擎之前必须设置工厂。

注意

QQmlEngine 不拥有该工厂的所有权。

另请参阅

networkAccessManagerFactory()

setOfflineStoragePath(dir)¶

Parameters:: dir – str

另请参阅

offlineStoragePath()

属性 offlineStoragePathᅟ 的设置器。

setOutputWarningsToStandardError(enabled)¶

Parameters:: enabled – 布尔值

设置是否将警告消息输出到stderr为enabled。

如果 enabled 为 true，QML 生成的任何警告消息将输出到 stderr 并通过 warnings() 信号发出。如果 enabled 为 false，则仅发出 warnings() 信号。这允许应用程序自行处理警告输出。

默认值为true。

另请参阅

outputWarningsToStandardError()

setPluginPathList(paths)¶

Parameters:: paths – 字符串列表

设置引擎搜索导入模块（在qmldir文件中引用）的本机插件的目录列表为paths。

默认情况下，列表仅包含.，即引擎在qmldir文件本身的目录中搜索。

另请参阅

pluginPathList() addPluginPath()

setUrlInterceptor(urlInterceptor)¶

Parameters:: urlInterceptor – QQmlAbstractUrlInterceptor

注意

此函数已弃用。

singletonInstance(qmlTypeId)¶

Parameters:: qmlTypeId – int
Return type:: QObject

返回在qmlTypeId下注册的单例类型的实例。对于基于QObject的单例类型，返回QObject实例，否则返回QJSValue或None。

建议存储QML类型ID，例如作为单例类中的静态成员。通过qmlTypeId()进行查找的成本较高。

singletonInstance(uri, typeName)

Parameters:

uri – 字符串
typeName – str

Return type:

QObject

trimComponentCache()¶

修剪引擎的内部组件缓存。

此函数会导致销毁当前未使用的任何已加载组件的属性元数据。

如果一个组件本身存在任何实例，或者使用该组件的其他组件的任何实例，或者由这些组件实例化的任何对象，则该组件被视为正在使用中。

另请参阅

clearComponentCache()

urlInterceptor()¶

Return type:: QQmlAbstractUrlInterceptor

注意

此函数已弃用。

此API为5.1版本私有

返回最后一个QQmlAbstractUrlInterceptor。它不能在GUI线程之外进行修改。

urlInterceptors()¶

Return type:: QQmlAbstractUrlInterceptor的列表

返回当前活动的URL拦截器列表。

warnings(warnings)¶

Parameters:: warnings – QQmlError 的列表

当QML生成warnings消息时，会发出此信号。

PySide6.QtQml.QQml引擎¶

概要¶

属性¶

方法¶

插槽¶

信号¶

静态函数¶

详细描述¶