QUrl Class
La clase QUrl ofrece una interfaz práctica para trabajar con direcciones URL. Más información...
| Encabezado: | #include <QUrl> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Lista de todos los miembros, incluidos los heredados
- QUrl forma parte de Entrada/Salida y redes, API de programación de redes y Clases compartidas implícitamente.
Nota: Todas las funciones de esta clase son reentrantes.
Comparaciones de QUrl
| Categoría | Tipos comparables |
|---|---|
| débil | QUrl |
Tipos públicos
(since 6.3) enum | AceProcessingOption { IgnoreIDNWhitelist, AceTransitionalProcessing } |
| flags | AceProcessingOptions |
| enum | ComponentFormattingOption { PrettyDecoded, EncodeSpaces, EncodeUnicode, EncodeDelimiters, EncodeReserved, …, FullyDecoded } |
| flags | ComponentFormattingOptions |
| flags | FormattingOptions |
| enum | ParsingMode { TolerantMode, StrictMode, DecodedMode } |
| enum | UrlFormattingOption { None, RemoveScheme, RemovePassword, RemoveUserInfo, RemovePort, …, NormalizePathSegments } |
| enum | UserInputResolutionOption { DefaultResolution, AssumeLocalFile } |
| flags | UserInputResolutionOptions |
Funciones públicas
| QUrl() | |
| QUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode) | |
| QUrl(const QUrl &other) | |
| QUrl(QUrl &&other) | |
| ~QUrl() | |
| QUrl | adjusted(QUrl::FormattingOptions options) const |
| QString | authority(QUrl::ComponentFormattingOptions options = PrettyDecoded) const |
| void | clear() |
| QString | errorString() const |
| QString | fileName(QUrl::ComponentFormattingOptions options = FullyDecoded) const |
| QString | fragment(QUrl::ComponentFormattingOptions options = PrettyDecoded) const |
| bool | hasFragment() const |
| bool | hasQuery() const |
| QString | host(QUrl::ComponentFormattingOptions options = FullyDecoded) const |
| bool | isEmpty() const |
| bool | isLocalFile() const |
| bool | isParentOf(const QUrl &childUrl) const |
| bool | isRelative() const |
| bool | isValid() const |
| bool | matches(const QUrl &url, QUrl::FormattingOptions options) const |
| QString | password(QUrl::ComponentFormattingOptions options = FullyDecoded) const |
| QString | path(QUrl::ComponentFormattingOptions options = FullyDecoded) const |
| int | port(int defaultPort = -1) const |
| QString | query(QUrl::ComponentFormattingOptions options = PrettyDecoded) const |
| QUrl | resolved(const QUrl &relative) const |
| QString | scheme() const |
| void | setAuthority(const QString &authority, QUrl::ParsingMode mode = TolerantMode) |
| void | setFragment(const QString &fragment, QUrl::ParsingMode mode = TolerantMode) |
| void | setHost(const QString &host, QUrl::ParsingMode mode = DecodedMode) |
| void | setPassword(const QString &password, QUrl::ParsingMode mode = DecodedMode) |
| void | setPath(const QString &path, QUrl::ParsingMode mode = DecodedMode) |
| void | setPort(int port) |
| void | setQuery(const QString &query, QUrl::ParsingMode mode = TolerantMode) |
| void | setQuery(const QUrlQuery &query) |
| void | setScheme(const QString &scheme) |
| void | setUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode) |
| void | setUserInfo(const QString &userInfo, QUrl::ParsingMode mode = TolerantMode) |
| void | setUserName(const QString &userName, QUrl::ParsingMode mode = DecodedMode) |
| void | swap(QUrl &other) |
| CFURLRef | toCFURL() const |
| QString | toDisplayString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const |
| QByteArray | toEncoded(QUrl::FormattingOptions options = FullyEncoded) const |
| QString | toLocalFile() const |
| NSURL * | toNSURL() const |
| QString | toString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const |
| QString | url(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const |
| QString | userInfo(QUrl::ComponentFormattingOptions options = PrettyDecoded) const |
| QString | userName(QUrl::ComponentFormattingOptions options = FullyDecoded) const |
| QUrl & | operator=(QUrl &&other) |
| QUrl & | operator=(const QString &url) |
| QUrl & | operator=(const QUrl &url) |
Miembros públicos estáticos
(since 6.3) QString | fromAce(const QByteArray &domain, QUrl::AceProcessingOptions options = {}) |
| QUrl | fromCFURL(CFURLRef url) |
| QUrl | fromEncoded(QByteArrayView input, QUrl::ParsingMode mode = TolerantMode) |
| QUrl | fromLocalFile(const QString &localFile) |
| QUrl | fromNSURL(const NSURL *url) |
| QString | fromPercentEncoding(const QByteArray &input) |
| QList<QUrl> | fromStringList(const QStringList &urls, QUrl::ParsingMode mode = TolerantMode) |
| QUrl | fromUserInput(const QString &userInput, const QString &workingDirectory = QString(), QUrl::UserInputResolutionOptions options = DefaultResolution) |
| QStringList | idnWhitelist() |
| void | setIdnWhitelist(const QStringList &list) |
(since 6.3) QByteArray | toAce(const QString &domain, QUrl::AceProcessingOptions options = {}) |
| QByteArray | toPercentEncoding(const QString &input, const QByteArray &exclude = QByteArray(), const QByteArray &include = QByteArray()) |
| QStringList | toStringList(const QList<QUrl> &urls, QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) |
Elementos no miembros relacionados
| bool | operator!=(const QUrl &lhs, const QUrl &rhs) |
| QDataStream & | operator<<(QDataStream &out, const QUrl &url) |
| bool | operator==(const QUrl &lhs, const QUrl &rhs) |
| QDataStream & | operator>>(QDataStream &in, QUrl &url) |
Macros
Descripción detallada
Puede analizar y construir direcciones URL tanto en formato codificado como sin codificar. QUrl también es compatible con los nombres de dominio internacionalizados (IDN).
La forma más habitual de utilizar QUrl es inicializarlo mediante el constructor, pasando un objeto ` QString ` que contenga una URL completa. Los objetos QUrl también se pueden crear a partir de un objeto ` QByteArray ` que contenga una URL completa utilizando ` QUrl::fromEncoded()`, o de forma heurística a partir de URL incompletas utilizando ` QUrl::fromUserInput()`. La representación de la URL se puede obtener de un objeto QUrl utilizando ` QUrl::toString()` o ` QUrl::toEncoded()`.
Las URL pueden representarse de dos formas: codificadas o sin codificar. La representación sin codificar es adecuada para mostrarla a los usuarios, pero la representación codificada es normalmente la que se envía a un servidor web. Por ejemplo, la URL sin codificar «http://bühler.example.com/List of applicants.xml» se enviaría al servidor como «http://xn–bhler-kva.example.com/List%20of%20applicants.xml».
Una URL también se puede construir pieza a pieza llamando a setScheme(), setUserName(), setPassword(), setHost(), setPort(), setPath(), setQuery() y setFragment(). También hay disponibles algunas funciones de conveniencia: setAuthority() establece el nombre de usuario, la contraseña, el host y el puerto. setUserInfo() establece el nombre de usuario y la contraseña a la vez.
Llama a isValid() para comprobar si la URL es válida. Esto se puede hacer en cualquier momento durante la construcción de una URL. Si isValid() devuelve false, debes clear() la URL antes de continuar, o empezar de nuevo analizando una nueva URL con setUrl().
La construcción de una consulta resulta especialmente cómoda mediante el uso de la clase ` QUrlQuery ` y sus métodos ` QUrlQuery::setQueryItems()`, ` QUrlQuery::addQueryItem()` y ` QUrlQuery::removeQueryItem()`. Utiliza ` QUrlQuery::setQueryDelimiters()` para personalizar los delimitadores utilizados para generar la cadena de consulta.
Para facilitar la generación de cadenas de URL codificadas o cadenas de consulta, existen dos funciones estáticas denominadas fromPercentEncoding() y toPercentEncoding(), que se encargan de la codificación y descodificación en porcentaje de los objetos QString.
fromLocalFile() construye un objeto QUrl analizando una ruta de archivo local. toLocalFile() convierte una URL en una ruta de archivo local.
La representación legible para el usuario de la URL se obtiene con toString(). Esta representación es adecuada para mostrar una URL al usuario sin codificar. Sin embargo, la forma codificada, tal y como la devuelve toEncoded(), está destinada al uso interno, para su envío a servidores web, clientes de correo, etc. Ambas formas son técnicamente correctas y representan la misma URL sin ambigüedades; de hecho, al pasar cualquiera de las dos formas al constructor de QUrl o a setUrl(), se obtendrá el mismo objeto QUrl.
QUrl cumple con la especificación URI del RFC 3986 (Identificador Uniforme de Recursos: Sintaxis Genérica) e incluye extensiones de esquema del RFC 1738 (Localizadores Uniformes de Recursos). Las reglas de conversión de mayúsculas y minúsculas en QUrl se ajustan a la RFC 3491 (Nameprep: un perfil Stringprep para nombres de dominio internacionalizados (IDN)). También es compatible con la especificación de URI de archivos de freedesktop.org, siempre que la configuración regional codifique los nombres de archivo utilizando UTF-8 (requisito de los IDN).
URL relativas frente a rutas relativas
Al llamar a ` isRelative()``, se indicará si la URL es relativa o no. Una URL relativa no incluye ` scheme`. Por ejemplo:
qDebug() << QUrl("main.qml").isRelative(); // true: sin esquema
qDebug() << QUrl("qml/main.qml").isRelative(); // true: no scheme
qDebug() << QUrl("file:main.qml").isRelative(); // false: has "file" scheme
qDebug() << QUrl("file:qml/main.qml").isRelative(); // false: has "file" schemeTen en cuenta que una URL puede ser absoluta aunque contenga una ruta relativa, y viceversa:
// URL absoluta, ruta relativa
QUrl url("file:file.txt");
qDebug() << url.isRelative(); // false: has "file" scheme
qDebug() << QDir::isAbsolutePath(url.path()); // false: relative path
// URL relativa, ruta absoluta
url = QUrl("/home/user/file.txt");
qDebug() << url.isRelative(); // true: has no scheme
qDebug() << QDir::isAbsolutePath(url.path()); // true: absolute pathUna URL relativa se puede resolver pasándola como argumento a la función ` resolved()`, que devuelve una URL absoluta. La función ` isParentOf()` se utiliza para determinar si una URL es la «padre» de otra.
Comprobación de errores
QUrl es capaz de detectar numerosos errores en las URL durante su análisis o cuando los componentes de la URL se establecen mediante métodos setter individuales (como setScheme(), setHost() o setPath()). Si el análisis o la función setter se realizan con éxito, se descartarán las condiciones de error registradas previamente.
Por defecto, los métodos de asignación de QUrl funcionan en modo « QUrl::TolerantMode », lo que significa que aceptan algunos errores comunes y representaciones erróneas de los datos. Un método alternativo de análisis es « QUrl::StrictMode », que aplica comprobaciones adicionales. Véase QUrl::ParsingMode para obtener una descripción de la diferencia entre los modos de análisis.
QUrl solo comprueba la conformidad con la especificación de las URL. No intenta verificar que las URL de protocolos de alto nivel tengan el formato que esperan los controladores de otros lugares. Por ejemplo, QUrl considera válidas todas las URI siguientes, aunque no tengan sentido al utilizarlas:
- «http:/filename.html»
- "mailto://example.com"
Cuando el analizador encuentra un error, lo señala haciendo que isValid() devuelva «false» y que toString() / toEncoded() devuelvan una cadena vacía. Si es necesario mostrar al usuario el motivo por el que no se ha podido analizar la URL, se puede obtener la condición de error de QUrl llamando a errorString(). Tenga en cuenta que este mensaje es muy técnico y puede que no tenga sentido para los usuarios finales.
QUrl solo puede registrar una condición de error. Si se detecta más de un error, no está definido cuál de ellos se notificará.
Conversiones de caracteres
Sigue estas reglas para evitar conversiones de caracteres erróneas al trabajar con URL y cadenas:
- Al crear un ` QString ` que contenga una URL procedente de un ` QByteArray ` o un `char*`, utilice siempre ` QString::fromUtf8()`.
Consideraciones de seguridad
Trata las URL procedentes de una fuente no fiable (la red, un archivo o documento, otra aplicación o el usuario) como entrada hostil.
- Valida la URL analizada, nunca la cadena sin procesar. Aplica cualquier lista de permitidos/denegados, comprobación de origen o de redireccionamiento a los componentes extraídos por QUrl —para comprobar el host, utiliza
url.host(QUrl::FullyEncoded)—, no al texto original. QUrl normaliza formas que una comprobación de cadena pasa por alto: tantohttp://0x7f.0.0.1comohttp://2130706433dan como resultado el host127.0.0.1, yhttp://good.com\\@evil.com/da como resultado el hostevil.com. UtilizaFullyEncodeden lugar de la forma decodificada por defecto, de modo que los hosts internacionalizados (IDN) se comparen en su forma ASCII y no puedan ser suplantados con caracteres Unicode similares. - Utiliza la misma URL analizada tanto para la comprobación como para la solicitud. Pasar la cadena original a un analizador diferente posteriormente reintroduce la discrepancia que la comprobación había solucionado.
- Presta especial atención al utilizar FullyDecoded para obtener componentes. El resultado puede presentar pérdidas o incluso tener un significado diferente, dependiendo del componente obtenido. También puede contener caracteres de control, incluidos
NUL. Consulta Full decoding para obtener más detalles.
Documentación sobre los tipos de miembro
[since 6.3] enum QUrl::AceProcessingOption
flags QUrl::AceProcessingOptions
Las opciones de procesamiento ACE controlan la forma en que se transforman las URL hacia y desde la codificación compatible con ASCII.
| Constante | Valor | Descripción |
|---|---|---|
QUrl::IgnoreIDNWhitelist | 0x1 | Ignora la lista blanca de IDN al convertir las URL a Unicode. |
QUrl::AceTransitionalProcessing | 0x2 | Utiliza el procesamiento transicional descrito en UTS n.º 46. Esto permite una mayor compatibilidad con la especificación IDNA 2003. |
Por defecto, se utiliza el procesamiento no transicional y solo se permiten caracteres no ASCII dentro de las URL cuyos dominios de nivel superior figuren en la lista blanca de IDN.
Esta enumeración se introdujo en Qt 6.3.
El tipo `AceProcessingOptions` es una definición de tipo (`typedef`) para ` QFlags<AceProcessingOption>`. Almacena una combinación OR de valores de `AceProcessingOption`.
Véase también toAce(), fromAce() y idnWhitelist().
enum QUrl::ComponentFormattingOption
flags QUrl::ComponentFormattingOptions
Las opciones de formato de los componentes definen cómo se formatearán los componentes de una URL al representarse como texto. Se pueden combinar con las opciones de QUrl::FormattingOptions cuando se utilizan en toString() y toEncoded().
| Constante | Valor | Descripción |
|---|---|---|
QUrl::PrettyDecoded | 0x000000 | El componente se devuelve en un «formato bonito», con la mayoría de los caracteres codificados con el signo de porcentaje descodificados. El comportamiento exacto de PrettyDecoded varía de un componente a otro y también puede cambiar de una versión de Qt a otra. Este es el valor predeterminado. |
QUrl::EncodeSpaces | 0x100000 | Deja los caracteres de espacio en su forma codificada («%20»). |
QUrl::EncodeUnicode | 0x200000 | Deja los caracteres no US-ASCII codificados en su forma UTF-8 con codificación porcentual (p. ej., «%C3%A9» para el punto de código U+00E9, «E minúscula latina con acento agudo»). |
QUrl::EncodeDelimiters | 0x400000 | 0x800000 | Deja ciertos delimitadores en su forma codificada, tal y como aparecerían en la URL cuando esta se representa como texto. Los delimitadores afectados por este cambio de opción varían de un componente a otro. Este indicador no tiene ningún efecto en toString() ni en toEncoded(). |
QUrl::EncodeReserved | 0x1000000 | Mantiene en su forma codificada los caracteres US-ASCII que la especificación no permite en la URL. Este es el valor predeterminado en toString() y toEncoded(). |
QUrl::DecodeReserved | 0x2000000 | Decodifica los caracteres US-ASCII cuya presencia en la URL no permite la especificación. Esta es la configuración predeterminada en los métodos get de los componentes individuales. |
QUrl::FullyEncoded | EncodeSpaces | EncodeUnicode | EncodeDelimiters | EncodeReserved | Deja todos los caracteres en su forma correctamente codificada, tal y como aparecería este componente como parte de una URL. Cuando se utiliza con toString(), esto genera una URL totalmente conforme en formato QString, exactamente igual al resultado de toEncoded() |
QUrl::FullyDecoded | FullyEncoded | DecodeReserved | 0x4000000 | Intenta decodificar todo lo posible. Para los componentes individuales de la URL, esto decodifica todas las secuencias de codificación porcentual, incluidos los caracteres de control (U+0000 a U+001F) y las secuencias UTF-8 que se encuentren en formato de codificación porcentual. El uso de este modo puede provocar la pérdida de datos; consulta más abajo para obtener más información. |
Los valores de EncodeReserved y DecodeReserved no deben utilizarse juntos en una misma llamada. Si esto ocurre, el comportamiento es indefinido. Se proporcionan como valores independientes porque el comportamiento del «modo bonito» con respecto a los caracteres reservados es diferente en determinados componentes y, especialmente, en la URL completa.
Decodificación completa
El modo FullyDecoded es similar al comportamiento de las funciones que devuelven QString en Qt 4.x, en el sentido de que cada carácter representa a sí mismo y nunca tiene ningún significado especial. Esto es así incluso para el carácter de porcentaje («%»), que debe interpretarse como un porcentaje literal, no como el inicio de una secuencia codificada con porcentaje. El mismo carácter, en todos los demás modos de decodificación, se representa mediante la secuencia «%25».
Siempre que se vuelvan a aplicar datos obtenidos con QUrl::FullyDecoded a un ` QUrl`, hay que tener cuidado de utilizar el parámetro ` QUrl::DecodedMode ` en los métodos de asignación (como ` setPath()` y ` setUserName()`). Si no se hace así, el carácter de porcentaje («%») podría volver a interpretarse como el inicio de una secuencia codificada en porcentaje.
Este modo resulta muy útil cuando se utilizan partes de una URL en un contexto ajeno a las URL. Por ejemplo, para extraer el nombre de usuario, la contraseña o las rutas de los archivos en una aplicación cliente FTP, se debe utilizar el modo FullyDecoded.
Este modo debe utilizarse con precaución, ya que hay dos condiciones que no pueden representarse de forma fiable en el objeto ` QString` devuelto. Son las siguientes:
- Secuencias que no son UTF-8: las URL pueden contener secuencias de caracteres codificados con el signo de porcentaje que no forman secuencias UTF-8 válidas. Dado que las URL deben decodificarse utilizando UTF-8, cualquier fallo del decodificador dará lugar a que el objeto ` QString ` contenga uno o más caracteres de sustitución en el lugar donde se encontraba la secuencia.
- Delimitadores codificados: las URL también pueden distinguir entre un delimitador que aparece en su forma literal y su equivalente en forma codificada con el signo de porcentaje. Esto se da con mayor frecuencia en la consulta, pero está permitido en la mayor parte de la URL.
El siguiente ejemplo ilustra el problema:
QUrl original("http://example.com/?q=a%2B%3Db%26c");
QUrl copy(original);
copy.setQuery(copy.query(QUrl::FullyDecoded), QUrl::DecodedMode);
qDebug() << original.toString(); // prints: http://example.com/?q=a%2B%3Db%26c
qDebug() << copy.toString(); // prints: http://example.com/?q=a+=b&cSi las dos URL se utilizaran mediante HTTP GET, la interpretación del servidor web probablemente sería diferente. En el primer caso, lo interpretaría como un único parámetro, con la clave «q» y el valor «a+=b&c». En el segundo caso, probablemente lo interpretaría como dos parámetros: uno con la clave «q» y el valor «a = b», y el segundo con la clave «c» y sin valor.
El tipo `ComponentFormattingOptions` es una definición de tipo para ` QFlags<ComponentFormattingOption>`. Almacena una combinación OR de valores de `ComponentFormattingOption`.
Véase también QUrl::FormattingOptions.
enum QUrl::ParsingMode
El modo de análisis controla la forma en que QUrl analiza las cadenas de texto.
| Constante | Valor | Descripción |
|---|---|---|
QUrl::TolerantMode | 0 | QUrl intentará corregir algunos errores comunes en las URL. Este modo resulta útil para analizar URL procedentes de fuentes de las que no se sabe si cumplen estrictamente con los estándares. |
QUrl::StrictMode | 1 | Solo se aceptan URL válidas. Este modo resulta útil para la validación general de URL. |
QUrl::DecodedMode | 2 | QUrl interpretará el componente de la URL en su forma totalmente descodificada, donde los caracteres de porcentaje representan a sí mismos, y no el inicio de una secuencia codificada en porcentaje. Este modo solo es válido para los setters que establecen componentes de una URL; no está permitido en el constructor QUrl, en fromEncoded() ni en setUrl(). Para obtener más información sobre este modo, consulta la documentación de QUrl::FullyDecoded. |
En TolerantMode, el analizador tiene el siguiente comportamiento:
- Espacios y «%20»: se aceptarán los caracteres de espacio sin codificar y se tratarán como equivalentes a «%20».
- Caracteres «%» aislados: si algún carácter de porcentaje «%» no va seguido de dos caracteres hexadecimales (por ejemplo, «13% coverage.html»), el analizador asumirá que la entrada no estaba codificada y sustituirá todos los caracteres «%» por «%25».
- Caracteres reservados y no reservados: una URL codificada solo debe contener unos pocos caracteres como literales; todos los demás caracteres deben estar codificados con el signo de porcentaje. En modo TolerantMode, se aceptarán estos caracteres si aparecen en la URL: espacio / comilla doble / «<» / «>» / «» / «^» / «`» / «{» / «|» / «}» Esos mismos caracteres se pueden descodificar de nuevo pasando ` QUrl::DecodeReserved ` a ` toString()` o ` toEncoded()`. En los métodos get de los componentes individuales, esos caracteres suelen devolverse en forma descodificada.
En StrictMode, si se detecta un error de análisis, isValid() devolverá false y errorString() devolverá un mensaje que describe el error. Si se detecta más de un error, no está definido qué error se notificará.
Ten en cuenta que el modo «TolerantMode» no suele ser suficiente para analizar la entrada del usuario, que a menudo contiene más errores y expectativas de las que el analizador puede gestionar. Al tratar datos procedentes directamente del usuario —a diferencia de los datos procedentes de fuentes de transferencia de datos, como otros programas—, se recomienda utilizar ` fromUserInput()`.
Véase también fromUserInput(), setUrl(), toString(), toEncoded() y QUrl::FormattingOptions.
enum QUrl::UrlFormattingOption
flags QUrl::FormattingOptions
Las opciones de formato definen cómo se presenta la URL cuando se muestra como texto.
| Constante | Valor | Descripción |
|---|---|---|
QUrl::None | 0x0 | El formato de la URL no cambia. |
QUrl::RemoveScheme | 0x1 | Se elimina el esquema de la URL. |
QUrl::RemovePassword | 0x2 | Se elimina cualquier contraseña que haya en la URL. |
QUrl::RemoveUserInfo | RemovePassword | 0x4 | Se elimina cualquier información de usuario presente en la URL. |
QUrl::RemovePort | 0x8 | Se elimina cualquier puerto especificado de la URL. |
QUrl::RemoveAuthority | RemoveUserInfo | RemovePort | 0x10 | Elimina el nombre de usuario, la contraseña, el host y el puerto. |
QUrl::RemovePath | 0x20 | Se elimina la ruta de la URL, dejando solo el esquema, la dirección del servidor y el puerto (si existe). |
QUrl::RemoveQuery | 0x40 | Se elimina la parte de consulta de la URL (la que sigue al carácter «?»). |
QUrl::RemoveFragment | 0x80 | Se elimina la parte del fragmento de la URL (incluido el carácter «#»). |
QUrl::RemoveFilename | 0x800 | Se elimina el nombre de archivo (es decir, todo lo que hay después de la última barra «/» de la ruta). Se mantiene la barra «/» final, a menos que se haya activado la opción StripTrailingSlash. Solo es válido si no se ha activado la opción RemovePath. |
QUrl::PreferLocalFile | 0x200 | Si la URL es un archivo local según isLocalFile() y no contiene ninguna consulta ni fragmento, se devuelve una ruta de archivo local. |
QUrl::StripTrailingSlash | 0x400 | Se elimina la barra final de la ruta, si la hay. |
QUrl::NormalizePathSegments | 0x1000 | Modifica la ruta para eliminar separadores de directorios redundantes y para resolver los «.» y «..» (en la medida de lo posible). En el caso de las rutas no locales, se conservan las barras adyacentes. |
Ten en cuenta que las reglas de conversión de mayúsculas a minúsculas de Nameprep, a las que se ajusta QUrl, exigen que los nombres de host se conviertan siempre a minúsculas, independientemente de las opciones de formato de Qt::FormattingOptions utilizadas.
También se pueden utilizar las opciones de QUrl::ComponentFormattingOptions.
El tipo FormattingOptions es un typedef para QFlags<UrlFormattingOption>. Almacena una combinación OR de valores de UrlFormattingOption.
Véase también QUrl::ComponentFormattingOptions.
enum QUrl::UserInputResolutionOption
flags QUrl::UserInputResolutionOptions
Las opciones de resolución de entradas del usuario definen cómo debe interpretar fromUserInput() las cadenas que podrían ser tanto una ruta relativa como la forma abreviada de una URL HTTP. Por ejemplo, file.pl puede ser tanto un archivo local como la URL http://file.pl.
| Constante | Valor | Descripción |
|---|---|---|
QUrl::DefaultResolution | 0 | El mecanismo de resolución por defecto consiste en comprobar si existe un archivo local en el directorio de trabajo indicado a ` fromUserInput` y, solo en ese caso, devolver una ruta local. De lo contrario, se asume que se trata de una URL. |
QUrl::AssumeLocalFile | 1 | Esta opción hace que ` fromUserInput()` devuelva siempre una ruta local, a menos que la entrada contenga un esquema, como ` http://file.pl`. Esto resulta útil para aplicaciones como los editores de texto, que pueden crear el archivo si no existe. |
El tipo `UserInputResolutionOptions` es una definición de tipo (typedef) para ` QFlags<UserInputResolutionOption>`. Almacena una combinación OR de valores de `UserInputResolutionOption`.
Véase también fromUserInput().
Documentación de las funciones miembro
QUrl::QUrl()
Crea un objeto QUrl vacío.
QUrl::QUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)
Crea una URL analizando url. Ten en cuenta que este constructor espera una URL válida o una referencia de URL y no intentará adivinar la intención. Por ejemplo, la siguiente declaración:
QUrl url("example.com");construirá una URL válida, pero puede que no sea la esperada, ya que falta la parte scheme() de la entrada. Para una cadena como la anterior, es posible que las aplicaciones prefieran utilizar fromUserInput(). Tanto para este constructor como para setUrl(), lo que probablemente se pretendía era lo siguiente:
QUrl url("https://example.com");QUrl codificará automáticamente con el símbolo de porcentaje todos los caracteres no permitidos en una URL y decodificará las secuencias codificadas con el símbolo de porcentaje que representen un carácter no reservado (letras, dígitos, guiones, guiones bajos, puntos y tildes). El resto de caracteres se mantienen en su forma original.
Analiza el url utilizando el modo de análisis parsingMode. En TolerantMode (el valor por defecto), QUrl corregirá ciertos errores, en particular la presencia de un carácter de porcentaje («%») no seguido de dos dígitos hexadecimales, y aceptará cualquier carácter en cualquier posición. En StrictMode, no se tolerarán errores de codificación y QUrl comprobará además que no haya ciertos caracteres prohibidos en forma no codificada. Si se detecta un error en StrictMode, isValid() devolverá «false». El modo de análisis DecodedMode no está permitido en este contexto.
Ejemplo:
QUrl url("http://www.example.com/List of holidays.xml");
// url.toEncoded() == "http://www.example.com/List%20of%20holidays.xml"Para construir una URL a partir de una cadena codificada, también puedes utilizar fromEncoded():
Ambas funciones son equivalentes y, en Qt 5, ambas aceptan datos codificados. Por lo general, la elección entre el constructor de QUrl o setUrl() frente a fromEncoded() dependerá de los datos de origen: el constructor y setUrl() admiten un QString, mientras que fromEncoded admite un QByteArray.
Véase también setUrl(), fromEncoded() y TolerantMode.
[noexcept] QUrl::QUrl(const QUrl &other)
Crea una copia de other.
[noexcept] QUrl::QUrl(QUrl &&other)
Crea una instancia de QUrl mediante «move», haciendo que apunte al mismo objeto al que apuntaba other.
[noexcept] QUrl::~QUrl()
Destructor; se ejecuta inmediatamente antes de que se elimine el objeto.
QUrl QUrl::adjusted(QUrl::FormattingOptions options) const
Devuelve una versión ajustada de la URL. La salida se puede personalizar pasando parámetros con options.
Las opciones de codificación de QUrl::ComponentFormattingOption no tienen mucho sentido para este método, al igual que QUrl::PreferLocalFile.
Esto siempre equivale a QUrl(url.toString(options)).
Véase también FormattingOptions, toEncoded() y toString().
QString QUrl::authority(QUrl::ComponentFormattingOptions options = PrettyDecoded) const
Devuelve la autoridad de la URL si está definida; en caso contrario, se devuelve una cadena vacía.
Esta función devuelve un valor inequívoco, que puede contener caracteres aún codificados con el símbolo de porcentaje, además de algunas secuencias de control que no se pueden representar en forma descodificada en QString.
El argumento options controla cómo dar formato al componente de información del usuario. El valor de QUrl::FullyDecoded no está permitido en esta función. Si necesitas obtener datos totalmente decodificados, llama a userName(), password(), host() y port() individualmente.
Véanse también setAuthority(), userInfo(), userName(), password(), host() y port().
void QUrl::clear()
Restablece el contenido de ` QUrl`. Tras llamar a esta función, ` QUrl ` es equivalente a uno que se haya creado con el constructor vacío por defecto.
Véase también isEmpty().
QString QUrl::errorString() const
Devuelve un mensaje de error si la última operación que modificó este objeto QUrl ha dado lugar a un error de análisis. Si no se ha detectado ningún error, esta función devuelve una cadena vacía y isValid() devuelve true.
El mensaje de error devuelto por esta función es de carácter técnico y puede que los usuarios finales no lo entiendan. Resulta especialmente útil para los desarrolladores que intentan comprender por qué QUrl no acepta determinada entrada.
Véase también QUrl::ParsingMode.
QString QUrl::fileName(QUrl::ComponentFormattingOptions options = FullyDecoded) const
Devuelve el nombre del archivo, sin incluir la ruta del directorio.
Ten en cuenta que, si a este objeto ` QUrl ` se le proporciona una ruta que termina en una barra, el nombre del archivo se considera vacío.
Si la ruta no contiene ninguna barra, se devuelve íntegramente como nombre de archivo.
Ejemplo:
QUrl url("http://qt-project.org/support/file.html");
// url.adjusted(RemoveFilename) == "http://qt-project.org/support/"
// url.fileName() == "file.html"El argumento ` options ` controla cómo se formatea el componente del nombre de archivo. Todos los valores producen un resultado inequívoco. Con ` QUrl::FullyDecoded`, todas las secuencias codificadas con «%» se descodifican; de lo contrario, el valor devuelto puede contener algunas secuencias codificadas con «%» para ciertas secuencias de control que no se pueden representar en forma descodificada en ` QString`.
Véase también path().
QString QUrl::fragment(QUrl::ComponentFormattingOptions options = PrettyDecoded) const
Devuelve el fragmento de la URL. Para determinar si la URL analizada contenía un fragmento, utiliza hasFragment().
El argumento ` options ` controla cómo se formatea el componente «fragmento». Todos los valores producen un resultado inequívoco. Con ` QUrl::FullyDecoded`, se descodifican todas las secuencias codificadas con el carácter «%»; de lo contrario, el valor devuelto puede contener algunas secuencias codificadas con el carácter «%» correspondientes a ciertas secuencias de control que no se pueden representar en forma descodificada en ` QString`.
Ten en cuenta que « QUrl::FullyDecoded » puede provocar la pérdida de datos si están presentes esas secuencias no representables. Se recomienda utilizar ese valor cuando el resultado se vaya a utilizar en un contexto distinto al de las URL.
Véanse también setFragment() y hasFragment().
[static, since 6.3] QString QUrl::fromAce(const QByteArray &domain, QUrl::AceProcessingOptions options = {})
Devuelve la forma Unicode del nombre de dominio dado domain, que está codificado en la codificación compatible con ASCII (ACE). El resultado se puede personalizar pasando indicadores con options. El resultado de esta función se considera equivalente a domain.
Si el valor de domain no se puede codificar, se convertirá a QString y se devolverá.
La codificación compatible con ASCII (ACE) está definida en los RFC 3490, RFC 3491 y RFC 3492, y actualizada por la Norma Técnica Unicode n.º 46. Forma parte de la especificación «Internationalizing Domain Names in Applications» (IDNA), que permite escribir nombres de dominio (como "example.com") utilizando caracteres no US-ASCII.
Esta función se introdujo en Qt 6.3.
[static] QUrl QUrl::fromCFURL(CFURLRef url)
Crea un objeto ` QUrl ` que contiene una copia de la URL CFURL url.
[static] QUrl QUrl::fromEncoded(QByteArrayView input, QUrl::ParsingMode mode = TolerantMode)
Analiza input y devuelve el QUrl correspondiente. Se da por hecho que input está en formato codificado y contiene únicamente caracteres ASCII.
Analiza la URL utilizando mode. Consulte setUrl() para obtener más información sobre este parámetro. QUrl::DecodedMode no está permitido en este contexto.
Nota: En las versiones de Qt anteriores a la 6.7, esta función aceptaba un ` QByteArray`, no un ` QByteArrayView`. Si se producen errores de compilación, es porque el código está pasando objetos que son implícitamente convertibles a ` QByteArray`, pero no a ` QByteArrayView`. Envuelve el argumento correspondiente en ` QByteArray{~~~} ` para hacer explícita la conversión. Esto es compatible con versiones anteriores de Qt.
Véase también toEncoded() y setUrl().
[static] QUrl QUrl::fromLocalFile(const QString &localFile)
Devuelve una representación de tipo « QUrl » de « localFile », interpretada como un archivo local. Esta función admite rutas separadas por barras, así como el separador nativo de esta plataforma.
Esta función también acepta rutas con una barra inicial duplicada (o barra invertida) para indicar un archivo remoto, como en «//servername/path/to/file.txt». Ten en cuenta que solo algunas plataformas pueden abrir realmente este archivo utilizando QFile::open().
Un ` localFile ` vacío da lugar a una URL vacía (desde Qt 5.4).
qDebug() << QUrl::fromLocalFile("file.txt"); // QUrl("file:file.txt")
qDebug() << QUrl::fromLocalFile("/home/user/file.txt"); // QUrl("file:///home/user/file.txt")
qDebug() << QUrl::fromLocalFile("file:file.txt"); // doesn't make sense; expects path, not url with schemeEn la primera línea del fragmento de código anterior, se crea una URL de archivo a partir de una ruta relativa local. Una URL de archivo con una ruta relativa solo tiene sentido si existe una URL base con la que resolverla. Por ejemplo:
QUrl url = QUrl::fromLocalFile("file.txt");
QUrl baseUrl = QUrl("file:/home/user/");
// incorrecto: muestra QUrl("file:file.txt"), ya que url ya tiene un esquema
qDebug() << baseUrl.resolved(url);Para resolver una URL de este tipo, es necesario eliminar primero el esquema:
// correcto: muestra QUrl("file:///home/user/file.txt")
url.setScheme(QString());
qDebug() << baseUrl.resolved(url);Por este motivo, es mejor utilizar una URL relativa (es decir, sin esquema) para las rutas relativas a los archivos:
QUrl url = QUrl("file.txt");
QUrl baseUrl = QUrl("file:/home/user/");
// muestra QUrl("file:///home/user/file.txt")
qDebug() << baseUrl.resolved(url);Véase también toLocalFile(), isLocalFile() y QDir::toNativeSeparators().
[static] QUrl QUrl::fromNSURL(const NSURL *url)
Crea un objeto ` QUrl ` que contiene una copia del `NSURL` url.
[static] QString QUrl::fromPercentEncoding(const QByteArray &input)
Devuelve una copia descodificada de input. input se descodifica primero del formato de codificación porcentual y, a continuación, se convierte de UTF-8 a Unicode.
Nota: Si se introduce una entrada no válida (como una cadena que contenga la secuencia «%G5», que no es un número hexadecimal válido), la salida tampoco será válida. Por ejemplo: la secuencia «%G5» podría descodificarse como «W».
[static] QList<QUrl> QUrl::fromStringList(const QStringList &urls, QUrl::ParsingMode mode = TolerantMode)
Convierte una lista de cadenas que representan urls en una lista de direcciones URL, utilizando QUrl(str, mode). Ten en cuenta que esto significa que todas las cadenas deben ser direcciones URL, y no, por ejemplo, rutas locales.
[static] QUrl QUrl::fromUserInput(const QString &userInput, const QString &workingDirectory = QString(), QUrl::UserInputResolutionOptions options = DefaultResolution)
Devuelve una URL válida a partir de una cadena « userInput » proporcionada por el usuario, si es posible deducirla. En caso de que no sea posible, se devuelve un valor no válido « QUrl()».
Esto permite al usuario introducir una URL o una ruta de archivo local en forma de cadena de texto sin formato. Esta cadena puede escribirse manualmente en la barra de direcciones, obtenerse del portapapeles o pasarse mediante argumentos de línea de comandos.
Cuando la cadena no es ya una URL válida, se realiza una estimación, partiendo de diversas suposiciones.
En caso de que la cadena corresponda a una ruta de archivo válida en el sistema, se construye una URL de tipo «file://» utilizando QUrl::fromLocalFile().
Si no es así, se intenta convertir la cadena en una URL de tipo http:// o ftp://. Esta última, en el caso de que la cadena comience por «ftp». A continuación, el resultado se pasa por el analizador tolerante de QUrl y, en caso de éxito, se devuelve una URL válida de tipo QUrl; de lo contrario, se devuelve un QUrl().
Ejemplos:
- qt-project.org se convierte en http://qt-project.org
- ftp.qt-project.org se convierte en ftp://ftp.qt-project.org
- hostname se convierte en http://hostname
- /home/user/test.html se convierte en file:///home/user/test.html
Para poder gestionar rutas relativas, este método admite una ruta opcional « workingDirectory ». Esto resulta especialmente útil al gestionar argumentos de la línea de comandos. Si « workingDirectory » está vacío, no se gestionarán las rutas relativas.
Por defecto, una cadena de entrada que parezca una ruta relativa solo se tratará como tal si el archivo existe realmente en el directorio de trabajo indicado. Si la aplicación puede gestionar archivos que aún no existen, debe pasar el indicador AssumeLocalFile en options.
bool QUrl::hasFragment() const
Devuelve « true » si esta URL contiene un fragmento (es decir, si aparece el símbolo «#» en ella).
Véase también fragment() y setFragment().
bool QUrl::hasQuery() const
Devuelve « true » si esta URL contiene una consulta (es decir, si se ha detectado un «?» en ella).
Véase también setQuery(), query() y hasFragment().
QString QUrl::host(QUrl::ComponentFormattingOptions options = FullyDecoded) const
Devuelve el host de la URL si está definido; en caso contrario, se devuelve una cadena vacía.
El argumento « options » controla cómo se formateará el nombre de host. La opción QUrl::EncodeUnicode hace que esta función devuelva el nombre de host en formato ACE (ASCII-Compatible Encoding), adecuado para su uso en canales que no son compatibles con 8 bits o que requieren el nombre de host heredado (como en las solicitudes DNS o en los encabezados de las solicitudes HTTP). Si no se incluye esa opción, esta función devuelve el nombre de dominio internacional (IDN) en formato Unicode, de acuerdo con la lista de dominios de nivel superior permitidos (véase idnWhitelist()).
Se ignoran todos los demás indicadores. Los nombres de host no pueden contener caracteres de control ni el signo de porcentaje, por lo que el valor devuelto puede considerarse totalmente descodificado.
Véase también setHost(), idnWhitelist(), setIdnWhitelist() y authority().
[static] QStringList QUrl::idnWhitelist()
Devuelve la lista blanca actual de dominios de primer nivel a los que se les permite incluir caracteres no ASCII en su composición.
Consulte setIdnWhitelist() para conocer los motivos que justifican esta lista.
Véase también setIdnWhitelist() y AceProcessingOption.
bool QUrl::isEmpty() const
Devuelve true si la URL no contiene datos; en caso contrario, devuelve false.
Véase también clear().
bool QUrl::isLocalFile() const
Devuelve ` true ` si esta URL apunta a una ruta de archivo local. Una URL se considera una ruta de archivo local si el esquema es «file».
Ten en cuenta que esta función considera que las URL con nombres de host son rutas de archivo locales, incluso si la ruta de archivo resultante no se puede abrir con QFile::open().
Véanse también fromLocalFile() y toLocalFile().
bool QUrl::isParentOf(const QUrl &childUrl) const
Devuelve « true » si esta URL es la URL principal de « childUrl ». « childUrl » es una URL secundaria de esta URL si ambas comparten el mismo esquema y la misma autoridad, y la ruta de esta URL es la ruta principal de la ruta de « childUrl ».
bool QUrl::isRelative() const
Devuelve true si la URL es relativa; en caso contrario, devuelve false. Una URL es una referencia relativa si su esquema no está definido; por lo tanto, esta función equivale a llamar a scheme().isEmpty().
Las referencias relativas se definen en la sección 4.2 del RFC 3986.
Véase también Relative URLs vs Relative Paths.
bool QUrl::isValid() const
Devuelve « true » si la URL no está vacía y es válida; en caso contrario, devuelve « false ».
La URL se somete a una prueba de conformidad. Para que la URL se considere válida, todas sus partes deben cumplir las normas de codificación establecidas en el estándar URI.
bool checkUrl(const QUrl&url) {
if (!url.isValid()) {
qDebug("Invalid URL: %s", qUtf8Printable(url.toString()));
return false;
}
return true;
}bool QUrl::matches(const QUrl &url, QUrl::FormattingOptions options) const
Devuelve true si esta URL y la URL url son iguales tras aplicar options a ambas; en caso contrario, devuelve false.
Esto equivale a llamar a adjusted(options) en ambas URL y comparar las URL resultantes, pero es más rápido.
QString QUrl::password(QUrl::ComponentFormattingOptions options = FullyDecoded) const
Devuelve la contraseña de la URL si está definida; en caso contrario, se devuelve una cadena vacía.
El argumento ` options ` controla cómo dar formato al componente del nombre de usuario. Todos los valores producen un resultado inequívoco. Con ` QUrl::FullyDecoded`, todas las secuencias codificadas con el símbolo de porcentaje se descodifican; de lo contrario, el valor devuelto puede contener algunas secuencias codificadas con el símbolo de porcentaje para ciertas secuencias de control que no se pueden representar en forma descodificada en ` QString`.
Tenga en cuenta que « QUrl::FullyDecoded » puede provocar pérdida de datos si están presentes esas secuencias no representables. Se recomienda utilizar ese valor cuando el resultado se vaya a utilizar en un contexto ajeno a las URL, como al establecer « QAuthenticator » o al negociar un inicio de sesión.
Véase también setPassword().
QString QUrl::path(QUrl::ComponentFormattingOptions options = FullyDecoded) const
Devuelve la ruta de la URL.
qDebug() << QUrl("file:file.txt").path(); // "file.txt"
qDebug() << QUrl("/home/user/file.txt").path(); // "/home/user/file.txt"
qDebug() << QUrl("http://www.example.com/test/123").path(); // "/test/123"El argumento « options » controla cómo se formatea el componente de la ruta. Todos los valores producen un resultado inequívoco. Con « QUrl::FullyDecoded », todas las secuencias codificadas con el carácter «%» se descodifican; en caso contrario, el valor devuelto puede contener algunas secuencias codificadas con el carácter «%» para ciertas secuencias de control que no pueden representarse en forma descodificada en « QString ».
Ten en cuenta que « QUrl::FullyDecoded » puede provocar la pérdida de datos si están presentes esas secuencias no representables. Se recomienda utilizar ese valor cuando el resultado se vaya a utilizar en un contexto que no sea una URL, como al enviarlo a un servidor FTP.
Un ejemplo de pérdida de datos se da cuando hay secuencias codificadas en porcentaje que no son Unicode y se utiliza FullyDecoded (el valor por defecto):
En este ejemplo, se producirá cierto grado de pérdida de datos, ya que el « %FF » no se puede convertir.
La pérdida de datos también puede producirse cuando la ruta contiene subdelimitadores (como +):
Otros ejemplos de decodificación:
const QUrl url("/tmp/Mambo %235%3F.mp3");
qDebug() << url.path(QUrl::FullyDecoded); // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::PrettyDecoded); // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::FullyEncoded); // "/tmp/Mambo%20%235%3F.mp3"Véase también setPath().
int QUrl::port(int defaultPort = -1) const
Devuelve el puerto de la URL, o « defaultPort » si no se ha especificado ningún puerto.
Ejemplo:
QTcpSocket sock;
sock.connectToHost(url.host(), url.port(80));Véase también setPort().
QString QUrl::query(QUrl::ComponentFormattingOptions options = PrettyDecoded) const
Devuelve la cadena de consulta de la URL si existe, o un resultado vacío en caso contrario. Para determinar si la URL analizada contenía una cadena de consulta, utiliza hasQuery().
El argumento ` options ` controla cómo dar formato al componente de consulta. Todos los valores producen un resultado inequívoco. Con ` QUrl::FullyDecoded`, todas las secuencias codificadas con el carácter de porcentaje se descodifican; de lo contrario, el valor devuelto puede contener algunas secuencias codificadas con el carácter de porcentaje para ciertas secuencias de control que no se pueden representar en forma descodificada en ` QString`.
Ten en cuenta que no se recomienda el uso de ` QUrl::FullyDecoded ` en las consultas, ya que estas suelen contener datos que deben permanecer codificados con el símbolo de porcentaje, incluido el uso de la secuencia «%2B» para representar el carácter más («+»).
Véanse también setQuery() y hasQuery().
QUrl QUrl::resolved(const QUrl &relative) const
Devuelve el resultado de la fusión de esta URL con relative. Esta URL se utiliza como base para convertir relative en una URL absoluta.
Si relative no es una URL relativa, esta función devolverá directamente relative. En caso contrario, se fusionan las rutas de las dos URL y la nueva URL devuelta tiene el esquema y la autoridad de la URL base, pero con la ruta fusionada, como en el siguiente ejemplo:
QUrl baseUrl("http://qt.digia.com/Support/");
QUrl relativeUrl("../Product/Library/");
qDebug(qUtf8Printable(baseUrl.resolved(relativeUrl).toString()));
// imprime «http://qt.digia.com/Product/Library/»Al llamar a resolved() con «..», se devuelve un QUrl cuyo directorio se encuentra un nivel por encima del original. Del mismo modo, al llamar a resolved() con «../..», se eliminan dos niveles de la ruta. Si relative es «/», la ruta pasa a ser «/».
Véase también isRelative().
QString QUrl::scheme() const
Devuelve el esquema de la URL. Si se devuelve una cadena vacía, significa que el esquema no está definido y, por lo tanto, la URL es relativa.
El esquema solo puede contener letras o dígitos US-ASCII, lo que significa que no puede contener ningún carácter que, de otro modo, requiriera codificación. Además, los esquemas siempre se devuelven en minúsculas.
Véase también setScheme() y isRelative().
void QUrl::setAuthority(const QString &authority, QUrl::ParsingMode mode = TolerantMode)
Establece la autoridad de la URL en authority.
La autoridad de una URL es la combinación de la información de usuario, un nombre de host y un puerto. Todos estos elementos son opcionales; por lo tanto, una autoridad vacía es válida.
La información de usuario y el host se separan mediante un «@», y el host y el puerto se separan mediante un «:». Si la información de usuario está vacía, se debe omitir el «@»; aunque se permite un «:» aislado si el puerto está vacío.
El siguiente ejemplo muestra una cadena de autoridad válida:

Los datos « authority » se interpretan según mode: en StrictMode, cualquier carácter «%» debe ir seguido de exactamente dos caracteres hexadecimales y algunos caracteres (incluido el espacio) no están permitidos en forma sin decodificar. En TolerantMode (el valor por defecto), se aceptan todos los caracteres en forma sin codificar y el analizador tolerante corregirá los caracteres «%» aislados que no vayan seguidos de dos caracteres hexadecimales.
Esta función no permite que mode sea QUrl::DecodedMode. Para establecer datos totalmente decodificados, llama a setUserName(), setPassword(), setHost() y setPort() individualmente.
Véanse también authority(), setUserInfo(), setHost() y setPort().
void QUrl::setFragment(const QString &fragment, QUrl::ParsingMode mode = TolerantMode)
Establece el fragmento de la URL en fragment. El fragmento es la última parte de la URL, representada por un «#» seguido de una cadena de caracteres. Se suele utilizar en HTTP para hacer referencia a un enlace o punto concreto de una página:

En ocasiones, al fragmento también se le denomina «referencia» de la URL.
Si se pasa un argumento de tipo QString() (un QString nulo), se desactivará el fragmento. Si se pasa un argumento de tipo QString(«») (un QString vacío pero no nulo), se establecerá el fragmento como una cadena vacía (como si la URL original tuviera únicamente un «#»).
Los datos de fragment se interpretan según mode: en StrictMode, cualquier carácter «%» debe ir seguido exactamente de dos caracteres hexadecimales y algunos caracteres (incluido el espacio) no están permitidos en forma no codificada. En TolerantMode, se aceptan todos los caracteres en forma no codificada y el analizador tolerante corregirá los caracteres «%» aislados que no vayan seguidos de dos caracteres hexadecimales. En DecodedMode, los «%» representan a sí mismos y no se admiten caracteres codificados.
QUrl::DecodedMode Debe utilizarse al establecer el fragmento a partir de una fuente de datos que no sea una URL o con un fragmento obtenido al llamar a fragment() con la opción de formato QUrl::FullyDecoded.
Véanse también fragment() y hasFragment().
void QUrl::setHost(const QString &host, QUrl::ParsingMode mode = DecodedMode)
Establece el host de la URL en host. El host forma parte de la autoridad.
Los datos de host se interpretan según mode: en StrictMode, cualquier carácter «%» debe ir seguido exactamente de dos caracteres hexadecimales y algunos caracteres (incluido el espacio) no están permitidos en forma no codificada. En TolerantMode, se aceptan todos los caracteres en forma no codificada y el analizador tolerante corregirá los «%» aislados que no vayan seguidos de dos caracteres hexadecimales. En DecodedMode, los caracteres «%» representan a sí mismos y no se admiten caracteres codificados.
Tenga en cuenta que, en todos los casos, el resultado del análisis debe ser un nombre de host válido según las normas STD 3, modificadas por la especificación de Identificadores de Recursos Internacionalizados (RFC 3987). No se permiten nombres de host no válidos y provocarán que isValid() devuelva «false».
Véanse también host() y setAuthority().
[static] void QUrl::setIdnWhitelist(const QStringList &list)
Establece la lista blanca de dominios de primer nivel (TLD) a los que se les permite incluir caracteres no ASCII en sus dominios con el valor list.
Ten en cuenta que, si llamas a esta función, debes hacerlo antes de iniciar cualquier hilo que pueda acceder a idnWhitelist().
Qt incluye una lista predeterminada que contiene los dominios de nivel superior de Internet que han publicado su compatibilidad con los nombres de dominio internacionalizados (IDN) y las reglas para garantizar que no se produzcan confusiones entre caracteres de aspecto similar (como la letra minúscula latina « 'a' » y su equivalente cirílico, que en la mayoría de las fuentes son visualmente idénticos).
Esta lista se actualiza periódicamente, a medida que los registradores publican nuevas normas.
Esta función se proporciona para quienes necesiten manipular la lista, con el fin de añadir o eliminar un TLD. No se recomienda modificar su valor para fines distintos a las pruebas, ya que podría exponer a los usuarios a riesgos de seguridad.
Véase también idnWhitelist().
void QUrl::setPassword(const QString &password, QUrl::ParsingMode mode = DecodedMode)
Establece la contraseña de la URL en « password ». El « password » forma parte del elemento «user info» de la autoridad de la URL, tal y como se describe en setUserInfo().
Los datos de password se interpretan según mode: en StrictMode, cualquier carácter «%» debe ir seguido de exactamente dos caracteres hexadecimales y algunos caracteres (incluido el espacio) no están permitidos en su forma sin codificar. En TolerantMode, se aceptan todos los caracteres en su forma sin codificar y el analizador tolerante corregirá los caracteres «%» aislados que no vayan seguidos de dos caracteres hexadecimales. En DecodedMode, los caracteres «%» representan a sí mismos y no se admiten caracteres codificados.
QUrl::DecodedMode Debe utilizarse al establecer la contraseña desde una fuente de datos que no sea una URL, como un cuadro de diálogo de contraseña que se muestra al usuario o con una contraseña obtenida al llamar a password() con la opción de formato QUrl::FullyDecoded.
Véanse también password() y setUserInfo().
void QUrl::setPath(const QString &path, QUrl::ParsingMode mode = DecodedMode)
Establece la ruta de la URL en path. La ruta es la parte de la URL que viene después del dominio y antes de la cadena de consulta.

En el caso de los esquemas no jerárquicos, la ruta será todo lo que siga a la declaración del esquema, como en el siguiente ejemplo:

Los datos de path se interpretan según mode: en StrictMode, cualquier carácter «%» debe ir seguido de exactamente dos caracteres hexadecimales y algunos caracteres (incluido el espacio) no están permitidos en forma no codificada. En TolerantMode, se aceptan todos los caracteres en forma no codificada y el analizador tolerante corregirá los caracteres «%» aislados que no vayan seguidos de dos caracteres hexadecimales. En DecodedMode, los caracteres «%» representan a sí mismos y no se admiten caracteres codificados.
QUrl::DecodedMode Debe utilizarse al establecer la ruta desde una fuente de datos que no sea una URL, como un cuadro de diálogo que se muestra al usuario o con una ruta obtenida al llamar a path() con la opción de formato QUrl::FullyDecoded.
Véase también path().
void QUrl::setPort(int port)
Establece el puerto de la URL en port. El puerto forma parte de la autoridad de la URL, tal y como se describe en setAuthority().
port Debe estar comprendido entre 0 y 65535, ambos incluidos. Si se establece el puerto en -1, se indica que el puerto no está especificado.
Véase también port().
void QUrl::setQuery(const QString &query, QUrl::ParsingMode mode = TolerantMode)
Establece la cadena de consulta de la URL en query.
Esta función resulta útil si necesitas pasar una cadena de consulta que no se ajusta al patrón clave-valor, o que utiliza un esquema de codificación de caracteres especiales distinto al sugerido por QUrl.
Al pasar un valor de tipo QString() a query (un valor nulo QString), se elimina la consulta por completo. Sin embargo, al pasar un valor de tipo QString(«»), la consulta se establecerá en un valor vacío, como si la URL original contuviera únicamente un «?».
Los datos de query se interpretan según mode: en StrictMode, cualquier carácter «%» debe ir seguido exactamente de dos caracteres hexadecimales y algunos caracteres (incluido el espacio) no están permitidos en su forma sin codificar. En TolerantMode, se aceptan todos los caracteres en su forma sin codificar y el analizador tolerante corregirá los «%» aislados que no vayan seguidos de dos caracteres hexadecimales. En DecodedMode, los «%» representan a sí mismos y no se admiten caracteres codificados.
Las cadenas de consulta suelen contener secuencias codificadas con el signo de porcentaje, por lo que se desaconseja el uso de DecodedMode. Una secuencia especial a tener en cuenta es la del carácter más («+»). QUrl no convierte los espacios en caracteres más, aunque los formularios HTML enviados por los navegadores web sí lo hagan. Para representar un signo más real en una consulta, se suele utilizar la secuencia «%2B». Esta función dejará intactas las secuencias «%2B» en TolerantMode o StrictMode.
Véase también query() y hasQuery().
void QUrl::setQuery(const QUrlQuery &query)
Establece la cadena de consulta de la URL en query.
Esta función reconstruye la cadena de consulta a partir del objeto ` QUrlQuery ` y la asigna a este objeto ` QUrl `. Esta función no tiene parámetros de análisis porque el objeto ` QUrlQuery ` contiene datos que ya han sido analizados.
Se trata de una función sobrecargada.
Véase también query() y hasQuery().
void QUrl::setScheme(const QString &scheme)
Establece el esquema de la URL en scheme. Dado que un esquema solo puede contener caracteres ASCII, no se realiza ninguna conversión ni decodificación de la entrada. Además, debe comenzar con una letra ASCII.
El esquema describe el tipo (o protocolo) de la URL. Se representa mediante uno o varios caracteres ASCII al principio de la URL.
Un esquema cumple estrictamente con la norma RFC 3986: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
El siguiente ejemplo muestra una URL cuyo esquema es «ftp»:

Para establecer el esquema, se utiliza la siguiente llamada:
QUrl url;
url.setScheme("ftp");El esquema también puede estar vacío, en cuyo caso la URL se interpreta como relativa.
Véase también scheme() y isRelative().
void QUrl::setUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)
Analiza url y asigna ese valor a este objeto. QUrl codificará automáticamente con el símbolo de porcentaje todos los caracteres no permitidos en una URL y descodificará las secuencias codificadas con el símbolo de porcentaje que representen un carácter no reservado (letras, dígitos, guiones, guiones bajos, puntos y tildes). El resto de caracteres se mantienen en su forma original.
Analiza la URL url utilizando el modo de análisis parsingMode. En TolerantMode (el valor por defecto), QUrl corregirá ciertos errores, en particular la presencia de un carácter de porcentaje («%») no seguido de dos dígitos hexadecimales, y aceptará cualquier carácter en cualquier posición. En StrictMode, no se tolerarán errores de codificación y QUrl comprobará además que no haya ciertos caracteres prohibidos en forma no codificada. Si se detecta un error en StrictMode, isValid() devolverá «false». El modo de análisis sintáctico DecodedMode no está permitido en este contexto y generará una advertencia en tiempo de ejecución.
Véase también url() y toString().
void QUrl::setUserInfo(const QString &userInfo, QUrl::ParsingMode mode = TolerantMode)
Establece la información de usuario de la URL en userInfo. La información de usuario es una parte opcional de la autoridad de la URL, tal y como se describe en setAuthority().
La información de usuario consta de un nombre de usuario y, opcionalmente, una contraseña, separados por dos puntos «:». Si la contraseña está vacía, deben omitirse los dos puntos. El siguiente ejemplo muestra una cadena de información de usuario válida:

Los datos de userInfo se interpretan según lo establecido en mode: en StrictMode, cualquier carácter «%» debe ir seguido exactamente de dos caracteres hexadecimales, y algunos caracteres (incluido el espacio) no están permitidos en forma sin codificar. En TolerantMode (el valor por defecto), se aceptan todos los caracteres sin codificar y el analizador tolerante corregirá los caracteres «%» aislados que no vayan seguidos de dos caracteres hexadecimales.
Esta función no permite que mode sea QUrl::DecodedMode. Para establecer datos totalmente descodificados, llama a setUserName() y setPassword() por separado.
Véanse también userInfo(), setUserName(), setPassword() y setAuthority().
void QUrl::setUserName(const QString &userName, QUrl::ParsingMode mode = DecodedMode)
Establece el nombre de usuario de la URL como userName. El elemento « userName » forma parte del elemento «user info» en la autoridad de la URL, tal y como se describe en setUserInfo().
Los datos de userName se interpretan según lo establecido en mode: en StrictMode, cualquier carácter «%» debe ir seguido exactamente de dos caracteres hexadecimales, y algunos caracteres (incluido el espacio) no están permitidos sin codificar. En TolerantMode (el valor por defecto), se aceptan todos los caracteres sin codificar y el analizador tolerante corregirá los caracteres «%» aislados que no vayan seguidos de dos caracteres hexadecimales. En DecodedMode, los caracteres «%» representan a sí mismos y no se permiten caracteres codificados.
QUrl::DecodedMode Debe utilizarse al establecer el nombre de usuario a partir de una fuente de datos que no sea una URL, como un cuadro de diálogo de contraseña que se muestra al usuario o con un nombre de usuario obtenido al llamar a userName() con la opción de formato QUrl::FullyDecoded.
Véanse también userName() y setUserInfo().
[noexcept] void QUrl::swap(QUrl &other)
Sustituye esta URL por other. Esta operación es muy rápida y nunca falla.
[static, since 6.3] QByteArray QUrl::toAce(const QString &domain, QUrl::AceProcessingOptions options = {})
Devuelve la codificación compatible con ASCII del nombre de dominio proporcionado domain. El resultado se puede personalizar pasando parámetros con options. El resultado de esta función se considera equivalente a domain.
La codificación compatible con ASCII (ACE) está definida en los RFC 3490, RFC 3491 y RFC 3492, y actualizada por la Norma Técnica Unicode n.º 46. Forma parte de la especificación «Internationalizing Domain Names in Applications» (IDNA), que permite escribir nombres de dominio (como "example.com") utilizando caracteres que no pertenecen al estándar US-ASCII.
Esta función devuelve un QByteArray vacío si domain no es un nombre de host válido. Ten en cuenta, en particular, que los literales IPv6 no son nombres de dominio válidos.
Esta función se introdujo en Qt 6.3.
CFURLRef QUrl::toCFURL() const
Crea un CFURL a partir de una dirección QUrl.
El autor de la llamada es el propietario del CFURL y es responsable de liberarlo.
QString QUrl::toDisplayString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const
Devuelve una representación en forma de cadena legible para el usuario de la URL. La salida se puede personalizar pasando parámetros con options. La opción RemovePassword siempre está activada, ya que las contraseñas nunca deben mostrarse a los usuarios.
Con las opciones predeterminadas, el QString resultante se puede volver a pasar a un QUrl más adelante, pero cualquier contraseña que estuviera presente inicialmente se perderá.
Véase también FormattingOptions, toEncoded() y toString().
QByteArray QUrl::toEncoded(QUrl::FormattingOptions options = FullyEncoded) const
Devuelve la representación codificada de la URL si es válida; en caso contrario, se devuelve un objeto ` QByteArray ` vacío. La salida se puede personalizar pasando indicadores con ` options`.
La información del usuario, la ruta y el fragmento se convierten a UTF-8, y todos los caracteres no ASCII se codifican con el símbolo de porcentaje. El nombre del servidor se codifica utilizando Punycode.
QString QUrl::toLocalFile() const
Devuelve la ruta de esta URL con el formato de una ruta de archivo local. La ruta devuelta utilizará barras inclinadas hacia delante, incluso si se creó originalmente a partir de una con barras invertidas.
Si esta URL contiene un nombre de host no vacío, se codificará en el valor devuelto en el formato habitual en las redes SMB (por ejemplo, «//servername/path/to/file.txt»).
qDebug() << QUrl("file:file.txt").toLocalFile(); // «file.txt»
qDebug() << QUrl("file:/home/user/file.txt").toLocalFile(); // "/home/user/file.txt"
qDebug() << QUrl("file.txt").toLocalFile(); // ""; wasn't a local file as it had no schemeNota: si el componente de ruta de esta URL contiene una secuencia binaria que no sea UTF-8 (como %80), el comportamiento de esta función es indefinido.
Véanse también fromLocalFile() y isLocalFile().
NSURL *QUrl::toNSURL() const
Crea un objeto NSURL a partir de un objeto ` QUrl`.
El NSURL se libera automáticamente.
[static] QByteArray QUrl::toPercentEncoding(const QString &input, const QByteArray &exclude = QByteArray(), const QByteArray &include = QByteArray())
Devuelve una copia codificada de input. input se convierte primero a UTF-8, y todos los caracteres ASCII que no pertenecen al grupo de caracteres no reservados se codifican con el símbolo de porcentaje. Para evitar que los caracteres se codifiquen con el símbolo de porcentaje, pásalos a exclude. Para forzar la codificación de los caracteres con el símbolo de porcentaje, pásalos a include.
Se define como «no reservado»: ALPHA / DIGIT / "-" / "." / "_" / "~"
QByteArray ba = QUrl::toPercentEncoding("{una cadena sospechosa?}", "{}", "s");
qDebug(ba.constData());
// muestra «{a fi%73hy %73tring%3F}»QString QUrl::toString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const
Devuelve una representación en forma de cadena de la URL. La salida se puede personalizar pasando indicadores con options. La opción QUrl::FullyDecoded no está permitida en esta función, ya que generaría datos ambiguos.
La opción de formato predeterminada es PrettyDecoded.
Véase también FormattingOptions, url() y setUrl().
[static] QStringList QUrl::toStringList(const QList<QUrl> &urls, QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded))
Convierte una lista de objetos ` urls ` en una lista de objetos ` QString `, utilizando ` toString` (options).
QString QUrl::url(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const
Devuelve una representación en forma de cadena de la URL. La salida se puede personalizar pasando parámetros con ` options`. La opción ` QUrl::FullyDecoded ` no está permitida en esta función, ya que generaría datos ambiguos.
El resultado de ` QString ` se puede volver a pasar a un ` QUrl ` más adelante.
Sinónimo de ` toString(options)`.
Véanse también setUrl(), FormattingOptions, toEncoded() y toString().
QString QUrl::userInfo(QUrl::ComponentFormattingOptions options = PrettyDecoded) const
Devuelve la información del usuario de la URL, o una cadena vacía si dicha información no está definida.
Esta función devuelve un valor inequívoco, que puede contener caracteres aún codificados con el símbolo de porcentaje, además de algunas secuencias de control que no se pueden representar en forma descodificada en QString.
El argumento options controla cómo dar formato al componente de información de usuario. El valor de QUrl::FullyDecoded no está permitido en esta función. Si necesitas obtener datos totalmente decodificados, llama a userName() y password() por separado.
Véase también setUserInfo(), userName(), password() y authority().
QString QUrl::userName(QUrl::ComponentFormattingOptions options = FullyDecoded) const
Devuelve el nombre de usuario de la URL si está definido; en caso contrario, se devuelve una cadena vacía.
El argumento ` options ` controla cómo se formatea el componente del nombre de usuario. Todos los valores producen un resultado inequívoco. Con ` QUrl::FullyDecoded`, todas las secuencias codificadas con el símbolo de porcentaje se descodifican; de lo contrario, el valor devuelto puede contener algunas secuencias codificadas con el símbolo de porcentaje correspondientes a secuencias de control que no se pueden representar en forma descodificada en ` QString`.
Tenga en cuenta que « QUrl::FullyDecoded » puede provocar la pérdida de datos si están presentes esas secuencias no representables. Se recomienda utilizar ese valor cuando el resultado se vaya a utilizar en un contexto distinto al de las URL, como al establecer « QAuthenticator » o al negociar un inicio de sesión.
Véase también setUserName() y userInfo().
[noexcept] QUrl &QUrl::operator=(QUrl &&other)
Asigna « other » a esta instancia de « QUrl ». ».
QUrl &QUrl::operator=(const QString &url)
Asigna el « url » especificado a este objeto.
Este operador no está disponible cuando se define la macro « QT_NO_URL_CAST_FROM_STRING ».
[noexcept] QUrl &QUrl::operator=(const QUrl &url)
Asigna el « url » especificado a este objeto.
Elementos no miembros relacionados
[noexcept] bool operator!=(const QUrl &lhs, const QUrl &rhs)
Devuelve true si las URL lhs y rhs no son iguales; en caso contrario, devuelve false.
Véase también matches().
QDataStream &operator<<(QDataStream &out, const QUrl &url)
Escribe la URL url en el flujo out y devuelve una referencia al flujo.
Véase también el formato de los operadores de QDataStream.
[noexcept] bool operator==(const QUrl &lhs, const QUrl &rhs)
Devuelve true si las URL lhs y rhs son equivalentes; en caso contrario, devuelve false.
Véase también matches().
QDataStream &operator>>(QDataStream &in, QUrl &url)
Lee una URL en un objeto ` url ` a partir del flujo ` in ` y devuelve una referencia al flujo.
Véase también el formato de los operadores de QDataStream.
Documentación de macros
QT_NO_URL_CAST_FROM_STRING
Desactiva las conversiones automáticas de ` QString ` (o `char *`) a ` QUrl`.
Compilar el código con esta definición resulta útil cuando se dispone de una gran cantidad de código que utiliza QString para los nombres de archivo y se desea convertirlo para que utilice QUrl con el fin de garantizar la transparencia de la red. En cualquier código que utilice QUrl, puede ayudar a evitar que se omitan llamadas a QUrl::resolved() y otros usos incorrectos de las conversiones de QString a QUrl.
Por ejemplo, si tienes un código como
url = filename; // probably not what you wantpuedes reescribirlo como
Véase también QT_NO_CAST_FROM_ASCII.
© 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.