QDesktopServices 类

QDesktopServices 类提供访问常见桌面服务的方法。更多...

头文件	#include <QDesktopServices>
CMake	find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake	QT += gui

所有成员列表，包括继承成员

静态公共成员

bool	openUrl(const QUrl &url)
void	setUrlHandler(const QString &scheme, QObject *receiver, const char *method)
void	unsetUrlHandler(const QString &scheme)

详细描述

许多桌面环境都提供服务，应用程序可以使用它们执行常见任务，例如打开网页，并且这样做既一致又考虑了用户的应用程序首选项。

此类包含提供简单接口的函数，指示这些服务是否成功或失败。

该 openUrl() 函数用于在外部应用程序中打开位于任意 URL 的文件。对于对应于本地文件系统上资源（其中 URL 方案为 "file"）的 URL，将使用合适的应用程序来打开该文件；否则，将使用 Web 浏览器来获取和显示该文件。

用户的桌面设置控制是否打开某些可执行文件类型进行浏览，或者是否直接执行。某些桌面环境被配置为阻止用户执行从非本地 URL 获得的文件，或者在使用之前要求用户许可。

URL 处理程序

可以自定义 openUrl() 函数的行为，以针对每个 URL 方案，允许应用程序覆盖某些类型 URL 的默认处理行为。

调度机制只允许对每个 URL 方案使用一个自定义处理程序；这是通过 setUrlHandler() 函数设置的。每个处理程序都作为一个槽来实现，仅接受一个 QUrl 参数。

可以使用 unsetUrlHandler() 函数删除每个方案的现有处理程序。这将把给定方案的处理行为恢复到默认行为。

此系统使得实现帮助系统变得容易，例如。使用 help://myapplication/mytopic URL 在标签和文本浏览器中提供帮助，并注册处理程序后，可以在应用程序内显示帮助文本

class MyHelpHandler : public QObject
{
    Q_OBJECT
public:
    // ...
public slots:
    void showHelp(const QUrl &url);
};
QDesktopServices::setUrlHandler("help", helpInstance, "showHelp");

如果在处理程序中您决定无法打开请求的 URL，您可以再次带有相同参数调用 QDesktopServices::openUrl()，它将尝试使用用户桌面环境的合适机制打开 URL

结合平台特定的设置，由 openUrl() 函数注册的方案也可以暴露给其他应用程序，为应用程序深度链接或一个非常基础的基于URL的IPC机制打开大门。

另请参阅 QSystemTrayIcon、QProcess 和 QStandardPaths。

成员函数文档

`[静态]` bool QDesktopServices::openUrl(const QUrl &url)

在用户桌面环境的适当Web浏览器中打开指定的 url，如果成功则返回 true；否则返回 false。

如果URL是本地文件的引用（即URL方案是 "file"），则它将以合适的程序打开，而不是Web浏览器。

以下示例在Windows文件系统上的路径包含空格的位置打开一个文件

QDesktopServices::openUrl(QUrl("file:///C:/Program Files", QUrl::TolerantMode));

如果指定了 mailto URL，则将使用用户的电子邮件客户端打开一个包含URL中指定的选项的 composer 窗口，类似于Web浏览器处理 mailto 链接的方式。

例如，以下URL包含收件人（[email protected]）、主题（Test）和消息正文（Just a test）

mailto:[email protected]?subject=Test&body=Just a test

注意： 尽管许多电子邮件客户端可以发送附件并且支持Unicode，但用户可能未配置邮箱客户端具有这些功能。此外，某些电子邮件客户端（例如Lotus Notes）存在长URL的问题。

注意： 返回值为 true 表示应用程序已成功请求操作系统在外部应用程序中打开URL。外部应用程序可能仍无法启动或无法打开请求的URL。此结果不会返回给应用程序。

注意： 在iOS上传递给此函数的URL，除非它们的方案列在应用程序的Info.plist文件中的LSApplicationQueriesSchemes密钥中，否则不会加载。有关更多信息，请参阅有关canOpenURL:的Apple开发者文档。例如，以下行启用了具有HTTPS方案的URL

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>https</string>
</array>

注意： 对于Android Nougat（SDK 24）及以上版本，具有file方案的URL将使用FileProvider打开，它首先尝试获取可共享的content方案URI。因此，Qt for Android使用权限为${applicationId}.qtprovider的文件提供者，其中applicationId是应用包名，以避免名称冲突。有关更多信息，请参阅设置文件共享。

另请参阅 setUrlHandler。

`[静态]` void QDesktopServices::setUrlHandler(const QString &scheme, QObject **receiver*, const char **method*)

设置给定 scheme 的处理器为由 receiver 对象提供的 method 处理器。

此函数提供了一种自定义 openUrl 的行为的方法。如果使用指定 scheme 的URL调用 openUrl()，则将调用 receiver 对象上的给定 method，而不是 QDesktopServices 启动外部应用程序。

提供的方法必须实现为一个槽，该槽只接受单个QUrl参数。

class MyHelpHandler : public QObject
{
    Q_OBJECT
public:
    // ...
public slots:
    void showHelp(const QUrl &url);
};

如果使用setUrlHandler()为已存在处理器的方案设置新的处理器，现有处理器将被新处理器替换。由于QDesktopServices不拥有处理器，替换处理器时不会删除任何对象。

请注意，处理器将会在调用QDesktopServices::openUrl()的同一个线程中调用。

在销毁处理器对象之前，您必须调用unsetUrlHandler()，以防止使用openUrl()的并发调用与处理器对象的销毁重叠。

iOS

要为此函数在iOS上从其他应用接收数据，您还需要将自定义方案添加到Info.plist文件中的CFBundleURLSchemes列表。

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
        </array>
    </dict>
</array>

有关更多信息，请参阅Apple开发者文档中的定义应用的自定义URL方案。

警告：无法声明支持某些知名URL方案，包括http和https。这仅限于通用链接。

要声明支持http和https，Info.plist文件中的上述条目不允许。这只有在将您的域添加到Entitlements文件中时才可能。

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:your.domain.com</string>
</array>

当应用程序安装时，iOS将搜索您的域上的/.well-known/apple-app-site-association。如果您想监听https://your.domain.com/help?topic=ABCDEF，您需要在提供以下内容

{
    "applinks": {
        "apps": [],
        "details": [{
            "appIDs" : [ "ABCDE12345.com.example.app" ],
            "components": [{
                "/": "/help",
                "?": { "topic": "?*"}
            }]
        }]
    }
}

有关更多信息，请参阅Apple开发者文档中的支持关联域。

Android

要为此函数在Android上从其他应用接收数据，您需要在应用程序清单中的activity中添加一个或多个intent过滤。

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="your.domain.com" android:port="1337" android:path="/help"/>
</intent-filter>

有关更多信息，请参阅Android开发者文档中的创建应用内容的深度链接。

如果您希望立即在不要求用户选择应用的情况下在Android应用中打开相应的功能，需要验证您的链接。要启用验证，请向intent过滤中添加另一个参数

<intent-filter android:autoVerify="true">

当应用程序安装时，Android将搜索https://your.domain.com/.well-known/assetlinks.json。如果您想监听https://your.domain.com:1337/help，您需要在提供以下内容

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

有关更多信息，请参阅Android开发者文档中的验证Android应用链接。

另请参阅：openUrl()和unsetUrlHandler()。

`[static]` void QDesktopServices::unsetUrlHandler(const QString &方案)

移除指定方案之前设置的URL处理器。

在注册方案的处理器对象销毁之前调用此函数，以防止并发openUrl()调用继续调用已销毁的处理器对象。

另请参阅 setUrlHandler。

QDesktopServices 类

静态公共成员

详细描述

URL 处理程序

成员函数文档

[静态] bool QDesktopServices::openUrl(const QUrl &url)

[静态] void QDesktopServices::setUrlHandler(const QString &scheme, QObject *receiver, const char *method)

iOS

Android

[static] void QDesktopServices::unsetUrlHandler(const QString &方案)

`[静态]` bool QDesktopServices::openUrl(const QUrl &url)

`[静态]` void QDesktopServices::setUrlHandler(const QString &scheme, QObject **receiver*, const char **method*)

`[static]` void QDesktopServices::unsetUrlHandler(const QString &方案)