QStandardPaths Class
La clase QStandardPaths proporciona métodos para acceder a las rutas estándar. Más...
| Cabecera: | #include <QStandardPaths> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
Tipos públicos
| enum | LocateOption { LocateFile, LocateDirectory } |
| flags | LocateOptions |
| enum | StandardLocation { DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation, MusicLocation, …, GenericStateLocation } |
Miembros públicos estáticos
| QString | displayName(QStandardPaths::StandardLocation type) |
| QString | findExecutable(const QString &executableName, const QStringList &paths = QStringList()) |
| QString | locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile) |
| QStringList | locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile) |
| void | setTestModeEnabled(bool testMode) |
| QStringList | standardLocations(QStandardPaths::StandardLocation type) |
| QString | writableLocation(QStandardPaths::StandardLocation type) |
Descripción Detallada
Esta clase contiene funciones para consultar ubicaciones estándar en el sistema de archivos local, para tareas comunes como directorios específicos del usuario o directorios de configuración de todo el sistema.
Documentación de tipos de miembros
enum QStandardPaths::LocateOption
flags QStandardPaths::LocateOptions
Este enum describe los diferentes flags que pueden utilizarse para controlar el comportamiento de QStandardPaths::locate y QStandardPaths::locateAll.
| Constante | Valor | Descripción |
|---|---|---|
QStandardPaths::LocateFile | 0x0 | devuelve sólo archivos |
QStandardPaths::LocateDirectory | 0x1 | devolver sólo directorios |
El tipo LocateOptions es un typedef para QFlags<LocateOption>. Almacena una combinación OR de valores LocateOption.
enum QStandardPaths::StandardLocation
Este enum describe las diferentes ubicaciones que pueden consultarse utilizando métodos como QStandardPaths::writableLocation, QStandardPaths::standardLocations y QStandardPaths::displayName.
Algunos de los valores de este enum representan una configuración de usuario. Tales valores enum devolverán las mismas rutas en diferentes aplicaciones, por lo que podrían utilizarse para compartir datos con otras aplicaciones. Otros valores son específicos de esta aplicación. Cada valor enum de la siguiente tabla describe si es específico de la aplicación o genérico.
Debe asumirse que los directorios específicos de una aplicación son inaccesibles para otras aplicaciones. Por lo tanto, los archivos colocados allí podrían no ser legibles por otras aplicaciones, incluso si son ejecutadas por el mismo usuario. Por otro lado, los directorios genéricos deben ser accesibles para todas las aplicaciones ejecutadas por este usuario, pero también se debe suponer que son inalcanzables para las aplicaciones de otros usuarios.
El intercambio de datos con otros usuarios queda fuera del alcance de QStandardPaths.
| Constante | Valor | Descripción |
|---|---|---|
QStandardPaths::DesktopLocation | 0 | Devuelve el directorio de escritorio del usuario. Este es un valor genérico. En sistemas sin concepto de escritorio, es lo mismo que QStandardPaths::HomeLocation. |
QStandardPaths::DocumentsLocation | 1 | Devuelve el directorio que contiene los archivos de documentos del usuario. Se trata de un valor genérico. La ruta devuelta nunca está vacía. |
QStandardPaths::FontsLocation | 2 | Devuelve el directorio que contiene las fuentes del usuario. Este es un valor genérico. Tenga en cuenta que la instalación de fuentes puede requerir operaciones adicionales específicas de la plataforma. |
QStandardPaths::ApplicationsLocation | 3 | Devuelve el directorio que contiene las aplicaciones del usuario (ya sean ejecutables, paquetes de aplicaciones o accesos directos a ellas). Se trata de un valor genérico. Tenga en cuenta que la instalación de aplicaciones puede requerir operaciones adicionales específicas de la plataforma. Los archivos, carpetas o accesos directos de este directorio son específicos de cada plataforma. |
QStandardPaths::MusicLocation | 4 | Devuelve el directorio que contiene la música del usuario u otros archivos de audio. Se trata de un valor genérico. Si no existe un directorio específico para archivos de música, se devuelve un directorio alternativo adecuado para almacenar los documentos del usuario. |
QStandardPaths::MoviesLocation | 5 | Devuelve el directorio que contiene las películas y vídeos del usuario. Se trata de un valor genérico. Si no existe un directorio específico para los archivos de películas, se devuelve una alternativa razonable para almacenar los documentos del usuario. |
QStandardPaths::PicturesLocation | 6 | Devuelve el directorio que contiene las imágenes o fotos del usuario. Se trata de un valor genérico. Si no existe un directorio específico para archivos de imágenes, se devuelve una alternativa razonable para almacenar los documentos del usuario. |
QStandardPaths::TempLocation | 7 | Devuelve un directorio donde se pueden almacenar archivos temporales. El valor devuelto puede ser específico de la aplicación, compartido entre otras aplicaciones para este usuario, o incluso para todo el sistema. La ruta devuelta nunca está vacía. |
QStandardPaths::HomeLocation | 8 | Devuelve el directorio principal del usuario (igual que QDir::homePath()). En sistemas Unix, es igual a la variable de entorno HOME. Este valor puede ser genérico o específico de la aplicación, pero la ruta devuelta nunca está vacía. |
QStandardPaths::AppLocalDataLocation | 9 | Devuelve la ruta de configuración local en el sistema operativo Windows. En el resto de plataformas, devuelve el mismo valor que AppDataLocation. Este valor enum se añadió en Qt 5.4. |
QStandardPaths::CacheLocation | 10 | Devuelve una ubicación de directorio donde deben escribirse los datos no esenciales (en caché) específicos del usuario. Se trata de un directorio específico de la aplicación. La ruta devuelta nunca está vacía. |
QStandardPaths::GenericCacheLocation | 15 | Devuelve una ubicación de directorio donde deben escribirse los datos no esenciales (en caché) específicos del usuario, compartidos entre aplicaciones. Se trata de un valor genérico. Tenga en cuenta que la ruta devuelta puede estar vacía si el sistema no tiene el concepto de caché compartida. |
QStandardPaths::GenericDataLocation | 11 | Devuelve una ubicación de directorio donde pueden almacenarse los datos persistentes compartidos entre aplicaciones. Se trata de un valor genérico. La ruta devuelta nunca está vacía. |
QStandardPaths::RuntimeLocation | 12 | Devuelve una ubicación de directorio donde deben escribirse los archivos de comunicación en tiempo de ejecución, como los sockets locales de Unix. Se trata de un valor genérico. La ruta devuelta puede estar vacía en algunos sistemas. |
QStandardPaths::ConfigLocation | 13 | Devuelve una ubicación de directorio donde deben escribirse los archivos de configuración específicos del usuario. Puede ser un valor genérico o específico de la aplicación, y la ruta devuelta nunca está vacía. |
QStandardPaths::DownloadLocation | 14 | Devuelve un directorio para los archivos descargados del usuario. Se trata de un valor genérico. Si no existe un directorio específico para las descargas, se devuelve una alternativa razonable para almacenar los documentos del usuario. |
QStandardPaths::GenericConfigLocation | 16 | Devuelve una ubicación de directorio donde deben escribirse los archivos de configuración específicos del usuario compartidos entre varias aplicaciones. Se trata de un valor genérico y la ruta devuelta nunca está vacía. |
QStandardPaths::AppDataLocation | 17 | Devuelve una ubicación de directorio donde se pueden almacenar los datos persistentes de la aplicación. Se trata de un directorio específico de la aplicación. Para obtener una ruta para almacenar datos que se compartirán con otras aplicaciones, utilice QStandardPaths::GenericDataLocation. La ruta devuelta nunca está vacía. En el sistema operativo Windows, devuelve la ruta de itinerancia. Este valor enum se añadió en Qt 5.4. |
QStandardPaths::AppConfigLocation | 18 | Devuelve una ubicación de directorio donde deben escribirse los archivos de configuración específicos del usuario. Se trata de un directorio específico de la aplicación, y la ruta devuelta nunca está vacía. Este valor enum se añadió en Qt 5.5. |
QStandardPaths::PublicShareLocation | 19 | Devuelve una ubicación de directorio donde se pueden almacenar archivos y directorios compartidos públicamente específicos del usuario. Se trata de un valor genérico. Tenga en cuenta que la ruta devuelta puede estar vacía si el sistema no tiene ningún concepto de ubicación compartida públicamente. Este valor enum se añadió en Qt 6.4. |
QStandardPaths::TemplatesLocation | 20 | Devuelve una ubicación de directorio donde se pueden almacenar archivos de plantilla específicos del usuario. Este es un valor genérico. Tenga en cuenta que la ruta devuelta puede estar vacía si el sistema no tiene un concepto de ubicación de plantillas. Este valor enum se añadió en Qt 6.4. |
QStandardPaths::StateLocation (since Qt 6.7) | 21 | Devuelve una ubicación de directorio donde deben escribirse los archivos de datos de estado de la aplicación específicos del usuario. Este es un directorio específico de la aplicación, y la ruta devuelta nunca está vacía. |
QStandardPaths::GenericStateLocation (since Qt 6.7) | 22 | Devuelve una ubicación de directorio donde deben escribirse los archivos de datos de estado compartidos entre aplicaciones. Este valor puede ser genérico o específico de la aplicación, pero la ruta devuelta nunca está vacía. |
La siguiente tabla muestra ejemplos de rutas en diferentes sistemas operativos. La primera ruta es la ruta de escritura (a menos que se indique lo contrario). Otras rutas adicionales, si las hay, representan ubicaciones no escribibles.
| Tipo de ruta | macOS | Windows |
|---|---|---|
| Ubicación del escritorio | "~/Escritorio | "C:/Usuarios/<USUARIO>/Escritorio" |
| Ubicación de documentos | "~/Documentos | "C:/Usuarios/<USUARIO>/Documentos" |
| FontsLocation | "/Sistema/Librería/Fonts" (no se puede escribir en él) | "C:/Windows/Fonts" (no se puede escribir en él) |
| Ubicación de las aplicaciones | "/Aplicaciones" (no se puede escribir en ella) | "C:/Usuarios/<USUARIO>/AppData/Roaming/Microsoft/Windows/Menú Inicio/Programas". |
| MusicLocation | "~/Música | "C:/Usuarios/<USUARIO>/Música" |
| Ubicación de películas | "~/Películas | "C:/Usuarios/<Usuario>/Vídeos". |
| Ubicación de imágenes | "~/Fotos | "C:/Usuarios/<USUARIO>/Fotos" |
| TempLocation | generada aleatoriamente por el SO | "C:/Usuarios/<USUARIO>/AppData/Local/Temp" |
| HomeLocation | "~" | "C:/Usuarios/<USUARIO>" |
| AppLocalDataLocation | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>". "<APPDIR>/../Recursos" | "C:/Usuarios/<USUARIO>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data", "<APPDIR>/data/<APPNAME>". |
| Ubicación de la caché | "~/Library/Caches/<APPNAME>", "/Library/Caches/<APPNAME>" | "C:/Usuarios/<USUARIO>/AppData/Local/<APPNAME>/cache" |
| StateLocation | "~/Librería/Preferencias/<APPNAME>/Estado" | "C:/Usuarios/<USUARIO>/AppData/Local/<APPNAME>/State", "C:/ProgramData/<APPNAME>/State" |
| GenericDataLocation | "~/Library/Application Support", "/Library/Application Support". | "C:/Usuarios/<USUARIO>/AppData/Local", "C:/ProgramData", "<APPDIR>", "<APPDIR>/data" |
| Ubicación en tiempo de ejecución | "~/Librería/Application Support | "C:/Usuarios/<USUARIO>" |
| ConfigLocation | "~/Biblioteca/Preferencias | "C:/Usuarios/<USUARIO>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| GenericConfigLocation | "~/Librería/Preferencias | "C:/Usuarios/<USUARIO>/AppData/Local", "C:/ProgramData" |
| DownloadLocation | "~/Descargas | "C:/Usuarios/<USUARIO>/Descargas". |
| GenericCacheLocation | "~/Library/Caches", "/Library/Caches" | "C:/Usuarios/<USUARIO>/AppData/Local/cache" |
| GenericStateLocation | "~/Librería/Preferencias/Estado" | "C:/Usuarios/<USUARIO>/AppData/Local/State", "C:/ProgramData/State" |
| AppDataLocation | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>". "<APPDIR>/../Recursos" | "C:/Usuarios/<USUARIO>/AppData/Roaming/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data", "<APPDIR>/data/<APPNAME>". |
| AppConfigLocation | "~/Library/Preferences/<APPNAME>" | "C:/Usuarios/<USUARIO>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| PublicShareLocation | "~/Público | "C:/Usuarios/Público" |
| TemplatesLocation | "~/Plantillas | "C:/Usuarios/<USUARIO>/AppData/Roaming/Microsoft/Windows/Templates" |
| Tipo de ruta | Linux y otros sistemas operativos UNIX |
|---|---|
| Ubicación del escritorio | "~/Escritorio |
| Ubicación de documentos | "~/Documentos |
| Ubicación de fuentes | "~/.fonts", "~/.local/share/fonts", "/usr/local/share/fonts", "/usr/share/fonts" |
| Ubicación de aplicaciones | "~/.local/share/applications", "/usr/local/share/applications", "/usr/share/applications" |
| Ubicación de la música | "~/Música |
| Ubicación de películas | "~/Vídeos |
| Ubicación de imágenes | "~/Fotos |
| UbicaciónTemporal | "/tmp |
| Ubicación de la casa | "~" |
| AppLocalDataLocation | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| CacheLocation | "~/.cache/<APPNAME>" |
| StateLocation | "~/.local/state/<APPNAME>" |
| GenericDataLocation | "~/.local/share", "/usr/local/share", "/usr/share" |
| RuntimeLocation | "/run/usuario/<USUARIO>" |
| ConfigLocation | "~/.config, /etc/xdg |
| GenericConfigLocation | "~/.config", "/etc/xdg" |
| Ubicación de descargas | "~/Descargas |
| GenericCacheLocation | "~/.cache |
| GenericStateLocation | "~/.local/state |
| AppDataLocation | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| AppConfigLocation | "~/.config/<APPNAME>", "/etc/xdg/<APPNAME>" |
| PublicShareLocation | "~/Público |
| TemplatesLocation | "~/Plantillas |
| Tipo de ruta | Android | iOS |
|---|---|---|
| DesktopLocation | "<APPROOT>/files" | "<APPROOT>/Documents/Desktop" |
| Ubicación de documentos | "<USUARIO>/Documentos" [*], "<USUARIO>/<APPNAME>/Documentos" | "<APPROOT>/Documentos" |
| FontsLocation | "/system/fonts" (no se puede escribir en él) | "<APPROOT>/Librería/Fonts" (no se puede escribir) |
| Ubicación de las aplicaciones | no compatible (directorio no legible) | no compatible |
| Ubicación de la música | "<USUARIO>/Música" [*], "<USUARIO>/<APNOMBRE>/Música" | "<APPROOT>/Documentos/Música". |
| Ubicación de películas | "<USUARIO>/Películas" [*], "<USUARIO>/<APNOMBRE_APP>/Películas" | "<APPROOT>/Documentos/Películas" |
| PicturesLocation | "<USUARIO>/Fotos" [*], "<USUARIO>/<NOMBREAPP>/Fotos" | "<APPROOT>/Documents/Pictures", "assets-library://" |
| TempLocation | "<APPROOT>/cache" | "<APPROOT>/tmp" |
| Ubicación de inicio | "<APPROOT>/files" | definido por el sistema |
| AppLocalDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Librería/Application Support". |
| Ubicación de la caché | "<APPROOT>/cache", "<USER>/<APPNAME>/cache" | "<APPROOT>/Librería/Caches" |
| StateLocation | "<APPROOT>/files/state" | |
| GenericStateLocation (hay estado compartido) | "<APPROOT>/files/state" | |
| GenericDataLocation | "<USER>" [*] o "<USER>/<APPNAME>/files" | "<APPROOT>/Librería/Application Support" |
| RuntimeLocation | "<APPROOT>/cache" | no soportado |
| ConfigLocation | "<APPROOT>/files/settings" | "<APPROOT>/Library/Preferences" |
| GenericConfigLocation | "<APPROOT>/files/settings" (no hay configuración compartida) | "<APPROOT>/Librería/Preferencias" |
| DownloadLocation | "<USUARIO>/Descargas" [*], "<USUARIO>/<APPNAME>/Descargas" | "<APPROOT>/Documentos/Descargas" |
| GenericCacheLocation | "<APPROOT>/cache" (no hay caché compartida) | "<APPROOT>/Library/Caches" (no hay caché compartida) |
| AppDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Librería/Application Support" (Soporte de aplicaciones) |
| AppConfigLocation | "<APPROOT>/files/settings" | "<APPROOT>/Library/Preferences/<APPNAME>" |
| PublicShareLocation | no admitido | no compatible |
| TemplatesLocation | no soportado | no compatible |
En la tabla anterior, <APPNAME> es normalmente el nombre de la organización, el nombre de la aplicación, o ambos, o un nombre único generado en el empaquetado. Del mismo modo, <APPROOT> es la ubicación donde se instala esta aplicación (a menudo un sandbox). <APPDIR> es el directorio que contiene el ejecutable de la aplicación.
No se debe confiar en las rutas anteriores, ya que pueden cambiar según la configuración del sistema operativo, la configuración regional, o pueden cambiar en futuras versiones de Qt.
Nota: En Android, las aplicaciones con archivos abiertos en el almacenamiento externo (ubicaciones <USER>), serán eliminadas si el almacenamiento externo es desmontado.
Nota: En Android 6.0 (API 23) o superior, el permiso "WRITE_EXTERNAL_STORAGE" debe ser solicitado en tiempo de ejecución cuando se utiliza QStandardPaths::writableLocation o QStandardPaths::standardLocations.
Nota: En Android, la lectura/escritura en GenericDataLocation necesita que se conceda el permiso READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE.
Nota : [*] En Android 11 y posteriores, los directorios públicos ya no son accesibles directamente en el modo de almacenamiento con alcance. Por lo tanto, las rutas de la forma "<USER>/DirName" no se devuelven. En su lugar, puede utilizar QFileDialog, que utiliza Storage Access Framework (SAF) para acceder a dichos directorios.
Nota: En iOS, si pasa QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last() como argumento a QFileDialog::setDirectory(), se utilizará un cuadro de diálogo nativo de selección de imágenes para acceder al álbum de fotos del usuario. El nombre de archivo devuelto puede cargarse utilizando QFile y APIs relacionadas. Esta característica se añadió en Qt 5.5.
Véase también writableLocation(), standardLocations(), displayName(), locate(), y locateAll().
Documentación de las funciones miembro
[static] QString QStandardPaths::displayName(QStandardPaths::StandardLocation type)
Devuelve un nombre de pantalla localizado para la ubicación dada type o un QString vacío si no se encuentra ninguna ubicación relevante.
[static] QString QStandardPaths::findExecutable(const QString &executableName, const QStringList &paths = QStringList())
Busca el ejecutable llamado executableName en la ruta especificada paths, o en la ruta del sistema si paths está vacía.
En la mayoría de los sistemas operativos, la ruta del sistema viene determinada por la variable de entorno PATH. Los directorios donde buscar el ejecutable pueden establecerse en el argumento rutas. Para buscar tanto en las rutas propias como en las del sistema, llame a findExecutable dos veces, una con las rutas establecidas y otra con las rutas vacías. Los enlaces simbólicos no se resuelven para preservar el comportamiento en el caso de ejecutables cuyo comportamiento depende del nombre con el que se invocan.
Nota: En Windows, las extensiones habituales de los ejecutables (de la variable de entorno PATHEXT) se añaden automáticamente. Por ejemplo, la llamada findExecutable("foo") encuentra foo.exe o foo.bat si están presentes.
Devuelve la ruta absoluta al archivo ejecutable, o una cadena vacía si no se encuentra.
Si el executableName dado es una ruta absoluta que apunta a un ejecutable, se devuelve su ruta limpia.
[static] QString QStandardPaths::locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
Busca un archivo o directorio llamado fileName en las ubicaciones estándar para type.
El indicador options permite especificar si se deben buscar archivos o directorios. Por defecto, esta opción está definida como LocateFile.
Devuelve la ruta absoluta al primer archivo o directorio encontrado; en caso contrario, devuelve una cadena vacía.
[static] QStringList QStandardPaths::locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
Busca todos los archivos o directorios con el nombre, fileName, en las ubicaciones estándar para type.
El indicador options permite especificar si se deben buscar archivos o directorios. Por defecto, esta opción está definida como LocateFile.
Devuelve la lista de todos los archivos encontrados.
[static] void QStandardPaths::setTestModeEnabled(bool testMode)
Si testMode es true, esto habilita un "modo de prueba" especial en QStandardPaths, que cambia las ubicaciones de escritura para que apunten a directorios de prueba. Esto impide que las pruebas automáticas lean o escriban en la configuración del usuario actual.
Afecta a las ubicaciones en las que los programas de prueba podrían escribir archivos: GenericDataLocation, AppDataLocation, ConfigLocation, GenericConfigLocation, AppConfigLocation, StateLocation, GenericStateLocation, GenericCacheLocation, y CacheLocation. Las demás ubicaciones no se ven afectadas.
En Unix, XDG_DATA_HOME va a ~/.qttest/share, XDG_CONFIG_HOME va a ~/.qttest/config, XDG_STATE_HOME va a ~/.qttest/state y XDG_CACHE_HOME va a ~/.qttest/cache.
En macOS, los datos van a ~/.qttest/Application Support, la caché a ~/.qttest/Cache y la configuración a ~/.qttest/Preferences.
En Windows, todo va a un directorio "qttest" en %APPDATA%.
[static] QStringList QStandardPaths::standardLocations(QStandardPaths::StandardLocation type)
Devuelve todos los directorios a los que pertenecen los archivos de type.
La lista de directorios se ordena de mayor a menor prioridad, empezando por writableLocation() si se puede determinar. La lista está vacía si no se han definido ubicaciones para el tipo.
Véase también writableLocation().
[static] QString QStandardPaths::writableLocation(QStandardPaths::StandardLocation type)
Devuelve el directorio en el que se deben escribir los archivos de type, o una cadena vacía si no se puede determinar la ubicación.
Nota: El almacén devuelto puede no existir; es decir, puede ser necesario que lo cree el sistema o el usuario.
© 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.
