En esta página

QFileSelector Class

QFileSelector ofrece una forma cómoda de seleccionar variantes de archivos. Más...

Encabezado: #include <QFileSelector>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Heredan: QObject

Funciones públicas

QFileSelector(QObject *parent = nullptr)
virtual ~QFileSelector()
QStringList allSelectors() const
QStringList extraSelectors() const
QString select(const QString &filePath) const
QUrl select(const QUrl &filePath) const
void setExtraSelectors(const QStringList &list)

Descripción detallada

QFileSelector es una herramienta que facilita la selección de variantes de archivos en función de las características de la plataforma o del dispositivo. Esto permite desarrollar e implementar más fácilmente un único código base que contenga todas las variantes diferentes en determinadas circunstancias, como cuando no se puede determinar la variante correcta durante la fase de implementación.

Uso de QFileSelector

Si siempre utilizas el mismo archivo, no es necesario que utilices QFileSelector.

Considera el siguiente ejemplo de uso, en el que deseas utilizar diferentes archivos de configuración en diferentes configuraciones regionales. Podrías seleccionar el código entre configuraciones regionales de la siguiente manera:

QString defaultsBasePath = "data/";
QString defaultsPath = defaultsBasePath + "defaults.conf";
QString localizedPath = defaultsBasePath
        + QString("%1/defaults.conf").arg(QLocale().name());
if (QFile::exists(localizedPath))
    defaultsPath = localizedPath;
QFile defaults(defaultsPath);

Del mismo modo, si desea elegir un archivo de datos diferente en función de la plataforma de destino, su código podría tener un aspecto similar a este:

    QString defaultsPath = "data/defaults.conf";
#if defined(Q_OS_ANDROID)
    defaultsPath = "data/android/defaults.conf";
#elif defined(Q_OS_IOS)
    defaultsPath = "data/ios/defaults.conf";
#endif
    QFile defaults(defaultsPath);

QFileSelector ofrece una alternativa práctica a escribir ese código repetitivo y, en el último caso, te permite empezar a utilizar una configuración específica para cada plataforma sin necesidad de recompilar. QFileSelector también permite encadenar varios selectores de forma cómoda, por ejemplo, para seleccionar un archivo diferente solo en determinadas combinaciones de plataforma y configuración regional. Por ejemplo, para seleccionar en función de la plataforma y/o la configuración regional, el código es el siguiente:

QFileSelector selector;
QFile defaultsFile(selector.select("data/defaults.conf"));

Los archivos que se van a seleccionar se colocan en directorios cuyo nombre contiene una « '+' » y un nombre de selector. En el ejemplo anterior, podrías seleccionar las configuraciones de plataforma colocándolas en las siguientes ubicaciones:

data/defaults.conf
data/+android/defaults.conf
data/+ios/+en_GB/defaults.conf

Para encontrar los archivos seleccionados, QFileSelector busca en el mismo directorio que el archivo base. Si hay algún directorio con el formato +<selector> y un selector activo, QFileSelector dará prioridad a un archivo con el mismo nombre de ese directorio frente al archivo base. Estos directorios pueden anidarse para comprobar varios selectores, por ejemplo:

images/background.png
images/+android/+en_GB/background.png

Con esos archivos disponibles, se seleccionaría un archivo diferente en la plataforma Android, pero solo si la configuración regional fuera en_GB.

Para la gestión de errores en caso de que no haya selectores válidos, se recomienda disponer de un archivo predeterminado o de gestión de errores en la ubicación del archivo base, incluso si se espera que haya selectores para todas las implementaciones.

En una versión futura, algunos podrían marcarse como estáticos en el momento de la implementación y trasladarse durante el paso de implementación como medida de optimización. Dado que los selectores conllevan un coste de rendimiento, se recomienda evitar su uso en circunstancias que impliquen código crítico para el rendimiento.

Añadir selectores

Los selectores normalmente disponibles son

  • «platform», cualquiera de las siguientes cadenas que coincidan con la plataforma en la que se ejecuta la aplicación (la lista no es exhaustiva): android, harmonyos, ios, osx, darwin, mac, macos, linux, qnx, unix, windows. En Linux, si se puede determinar, también el nombre de la distribución, como debian, fedora u opensuse.
  • locale, igual que QLocale().name().

Se añadirán más selectores a partir de la variable de entorno ` QT_FILE_SELECTORS `, que, cuando se configure, deberá contener un conjunto de selectores separados por comas. Ten en cuenta que esta variable solo se leerá una vez; es posible que los selectores no se actualicen si la variable cambia mientras la aplicación está en ejecución. El conjunto inicial de selectores se evalúa solo una vez, en el primer uso.

También se pueden añadir selectores adicionales en tiempo de ejecución para personalizar el comportamiento. Estos se utilizarán en cualquier llamada futura a ` select()`. Si se ha modificado la lista de selectores adicionales, las llamadas a ` select()` utilizarán la nueva lista y pueden devolver resultados diferentes.

Resolución de conflictos cuando se aplican varios selectores

Cuando se pueden aplicar varios selectores al mismo archivo, se elige el primer selector que coincida. El orden en que se comprueban los selectores es el siguiente:

  1. Los selectores establecidos mediante setExtraSelectors(), en el orden en que aparecen en la lista
  2. Los selectores de la variable de entorno ` QT_FILE_SELECTORS `, de izquierda a derecha
  3. Configuración regional
  4. Plataforma

A continuación se muestra un ejemplo en el que coinciden varios selectores al mismo tiempo. Utiliza selectores de plataforma, además de un selector adicional denominado «admin» que establece la aplicación en función de las credenciales del usuario. El ejemplo está ordenado de tal forma que, si estuvieran presentes todos los selectores, se elegiría el archivo que cumpliera con el menor número de condiciones:

images/background.png
images/+linux/background.png
images/+windows/background.png
images/+admin/background.png
images/+admin/+linux/background.png

Dado que los selectores adicionales se comprueban antes que los de plataforma, se elegirá +admin/background.png en Windows cuando el selector «admin» esté establecido, y +windows/background.png en Windows cuando dicho selector no lo esté. En Linux, se elegirá +admin/+linux/background.png cuando «admin» esté establecido, y +linux/background.png cuando no lo esté.

Documentación de la función miembro

[explicit] QFileSelector::QFileSelector(QObject *parent = nullptr)

Crea una instancia de QFileSelector. Esta instancia contará con los mismos selectores estáticos que otras instancias de QFileSelector, pero también tendrá su propio conjunto de selectores adicionales.

Si se proporciona, contará con los « QObject » y « parent » indicados.

[virtual noexcept] QFileSelector::~QFileSelector()

Elimina esta instancia del selector.

QStringList QFileSelector::allSelectors() const

Devuelve la lista completa y ordenada de los selectores utilizados por esta instancia.

QStringList QFileSelector::extraSelectors() const

Devuelve la lista de selectores adicionales que se han añadido mediante código a esta instancia.

Véase también ` setExtraSelectors()`.

QString QFileSelector::select(const QString &filePath) const

Esta función devuelve la versión seleccionada de la ruta, en función de las condiciones en tiempo de ejecución. Si no hay ningún archivo seleccionable, devuelve el original filePath.

Si el archivo original no existe, se devuelve el filePath original. Esto significa que debes disponer de un archivo base al que recurrir; no puedes tener únicamente archivos en subdirectorios seleccionables.

Consulte la descripción general de la clase para conocer el algoritmo de selección.

QUrl QFileSelector::select(const QUrl &filePath) const

Esta es una versión simplificada de la función «select» que opera sobre objetos « QUrl ». Si el esquema no es «file» o «qrc», se devuelve inmediatamente « filePath ». En caso contrario, la selección se aplica a la ruta de « filePath » y se devuelve un « QUrl » con la ruta seleccionada y el resto de partes de « QUrl » iguales a las de « filePath ».

Consulta la descripción general de la clase para conocer el algoritmo de selección.

void QFileSelector::setExtraSelectors(const QStringList &list)

Establece el ` list ` de los selectores adicionales que se han añadido mediante código a esta instancia.

Estos selectores tienen prioridad sobre cualquier otro que se haya seleccionado automáticamente.

Véase también extraSelectors().

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