En esta página

QDesktopServices Class

La clase QDesktopServices ofrece métodos para acceder a servicios comunes del escritorio. Más información...

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

Miembros públicos estáticos

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

Descripción detallada

Muchos entornos de escritorio ofrecen servicios que las aplicaciones pueden utilizar para realizar tareas comunes, como abrir una página web, de una forma coherente y que tenga en cuenta las preferencias del usuario en cuanto a las aplicaciones.

Esta clase contiene funciones que proporcionan interfaces sencillas para acceder a estos servicios y que indican si han tenido éxito o han fallado.

La función ` openUrl()` se utiliza para abrir archivos ubicados en direcciones URL arbitrarias en aplicaciones externas. Para las direcciones URL que corresponden a recursos del sistema de archivos local (donde el esquema de URL es «file»), se utilizará una aplicación adecuada para abrir el archivo; de lo contrario, se utilizará un navegador web para recuperar y mostrar el archivo.

La configuración del escritorio del usuario determina si determinados tipos de archivos ejecutables se abren para su visualización o si, por el contrario, se ejecutan. Algunos entornos de escritorio están configurados para impedir que los usuarios ejecuten archivos obtenidos de direcciones URL no locales, o para solicitar el permiso del usuario antes de hacerlo.

Manejadores de URL

El comportamiento de la función openUrl() puede personalizarse para esquemas de URL individuales, con el fin de permitir que las aplicaciones anulen el comportamiento predeterminado para determinados tipos de URL.

El mecanismo de distribución permite utilizar solo un controlador personalizado para cada esquema de URL; esto se configura mediante la función ` setUrlHandler()`. Cada controlador se implementa como una ranura que solo acepta un único argumento ` QUrl `.

Los controladores existentes para cada esquema pueden eliminarse con la función ` unsetUrlHandler()`. Esto restablece el comportamiento predeterminado para el esquema en cuestión.

Este sistema facilita, por ejemplo, la implementación de un sistema de ayuda. La ayuda podría proporcionarse en etiquetas y navegadores de texto mediante las URL help://myapplication/mytopic, y al registrar un controlador es posible mostrar el texto de ayuda dentro de la aplicación:

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

Si, dentro del controlador, decides que no puedes abrir la URL solicitada, basta con volver a llamar a QDesktopServices::openUrl() con el mismo argumento, y la función intentará abrir la URL utilizando el mecanismo adecuado para el entorno de escritorio del usuario.

En combinación con la configuración específica de la plataforma, los esquemas registrados por la función openUrl() también pueden ponerse a disposición de otras aplicaciones, lo que permite establecer enlaces profundos entre aplicaciones o un mecanismo muy básico de comunicación entre procesos (IPC) basado en URL.

Véase también QSystemTrayIcon, QProcess y QStandardPaths.

Documentación de funciones miembro

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

Abre la dirección url en el navegador web adecuado para el entorno de escritorio del usuario y devuelve true si la operación se realiza con éxito; en caso contrario, devuelve false.

Si la URL hace referencia a un archivo local (es decir, el esquema de la URL es «file»), se abrirá con una aplicación adecuada en lugar de con un navegador web.

El siguiente ejemplo abre un archivo del sistema de archivos de Windows que se encuentra en una ruta que contiene espacios:

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

Si se especifica una URL de tipo mailto, se utilizará el cliente de correo electrónico del usuario para abrir una ventana de redacción que contenga las opciones especificadas en la URL, de forma similar a como un navegador web gestiona los enlaces mailto.

Por ejemplo, la siguiente URL contiene un destinatario (user@foo.com), un asunto (Test) y el cuerpo del mensaje (Just a test):

mailto:user@foo.com?subject=Test&body=Just a test

Advertencia: Aunque muchos clientes de correo electrónico pueden enviar archivos adjuntos y son compatibles con Unicode, es posible que el usuario haya configurado su cliente sin estas características. Además, algunos clientes de correo electrónico (por ejemplo, Lotus Notes) tienen problemas con las URL largas.

Advertencia: Un valor de retorno de « true » indica que la aplicación ha solicitado con éxito al sistema operativo que abra la URL en una aplicación externa. No obstante, es posible que la aplicación externa no se inicie o que no consiga abrir la URL solicitada. Este resultado no se comunicará a la aplicación.

Advertencia: Las URL pasadas a esta función en iOS no se cargarán a menos que sus esquemas figuren en la clave LSApplicationQueriesSchemes del archivo Info.plist de la aplicación. Para obtener más información, consulta la documentación para desarrolladores de Apple sobre canOpenURL:. Por ejemplo, las siguientes líneas habilitan las URL con el esquema HTTPS:

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

Nota: En Android Nougat (SDK 24) y versiones posteriores, las URL con el esquema file se abren mediante FileProvider, que intenta obtener primero una URI del esquema content que se pueda compartir. Por ese motivo, Qt para Android define un proveedor de archivos con la autoridad ${applicationId}.qtprovider, siendo applicationId el nombre del paquete de la aplicación para evitar conflictos de nombres. Para obtener más información, consulta también «Configuración del uso compartido de archivos».

Véase también setUrlHandler().

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

Establece el controlador de la propiedad « scheme » como el controlador « method » proporcionado por el objeto « receiver ».

Esta función permite personalizar el comportamiento de ` openUrl()`. Si se llama a ` openUrl()` con una URL que contenga el ` scheme ` especificado, se invocará el ` method ` del objeto ` receiver ` en lugar de que ` QDesktopServices ` inicie una aplicación externa.

El método proporcionado debe implementarse como una ranura que solo acepte un único argumento « QUrl ».

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

Si se utiliza `setUrlHandler()` para establecer un nuevo controlador para un esquema que ya cuenta con uno, el controlador existente simplemente se sustituye por el nuevo. Dado que ` QDesktopServices ` no asume la propiedad de los controladores, no se elimina ningún objeto cuando se sustituye un controlador.

Tenga en cuenta que el controlador siempre se invocará desde el mismo hilo que invoca a QDesktopServices::openUrl().

Debes llamar a ` unsetUrlHandler()` antes de destruir el objeto controlador, de modo que la destrucción de dicho objeto no se solape con invocaciones concurrentes de ` openUrl()` que lo utilicen.

iOS y macOS

Para utilizar esta función con el fin de recibir datos de otras aplicaciones en iOS/macOS, también debes añadir el esquema personalizado a la lista CFBundleURLSchemes de tu archivo Info.plist:

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

Para obtener más información, consulta la documentación para desarrolladores de Apple sobre cómo definir un esquema de URL personalizado para tu aplicación.

Advertencia: Noes posible declarar compatibilidad con algunos esquemas de URL muy conocidos, como http y https. Esto solo está permitido para los enlaces universales.

Para declarar compatibilidad con http y https, no se permite la entrada anterior en el archivo Info.plist. Esto solo es posible cuando añades tu dominio al archivo Entitlements:

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

iOS/macOS buscará el archivo /.well-known/apple-app-site-association en tu dominio cuando se instale la aplicación. Si quieres que se pueda acceder a https://your.domain.com/help?topic=ABCDEF, debes incluir allí el siguiente contenido:

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

Para obtener más información, consulta la documentación para desarrolladores de Apple sobre cómo admitir dominios asociados.

Android

Para utilizar esta función con el fin de recibir datos de otras aplicaciones en Android, debes añadir uno o varios filtros de intención al elemento « activity » del manifiesto de tu aplicación:

<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>

Para obtener más información, consulta la documentación para desarrolladores de Android sobre cómo crear enlaces profundos al contenido de la aplicación.

Para abrir inmediatamente el contenido correspondiente en tu aplicación de Android, sin que el usuario tenga que seleccionar la aplicación, debes verificar tu enlace. Para habilitar la verificación, añade un parámetro adicional a tu filtro de intención:

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

Android buscará https://your.domain.com/.well-known/assetlinks.json cuando la aplicación esté instalada. Si quieres escuchar https://your.domain.com:1337/help, debes proporcionar allí el siguiente contenido:

[{
  "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"]
  }
}]

Para obtener más información, consulta la documentación para desarrolladores de Android sobre cómo verificar los enlaces de aplicaciones de Android.

Véase también openUrl() y unsetUrlHandler().

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

Elimina un gestor de URL establecido previamente para el scheme especificado.

Llama a esta función antes de que se destruya el objeto de controlador registrado para scheme, con el fin de evitar que las llamadas simultáneas a openUrl() sigan invocando al objeto de controlador ya destruido.

Véase también setUrlHandler().

© 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.