QFileSelector 类

QFileSelector 为选择文件变体提供便捷方式。 更多...

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

公共函数

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 )

详细描述

QFileSelector 对于基于平台或设备特色,选择文件变体很方便。这允许在某些情况下更轻松开发和部署包含所有不同变体的代码库,譬如:当在部署步骤期间无法确定正确变体时。

使用 QFileSelector

若始终使用同一文件,则不需要使用 QFileSelector。

考虑以下范例用法,若希望在不同区域设置使用不同设置文件。可以在区域设置之间选择代码,像这样:

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

同样,若想要基于目标平台拾取不同数据文件,代码可能看起来像这样:

    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 provides a convenient alternative to writing such boilerplate code, and in the latter case it allows you to start using an platform-specific configuration without a recompile. QFileSelector also allows for chaining of multiple selectors in a convenient way, for example selecting a different file only on certain combinations of platform and locale. For example, to select based on platform and/or locale, the code is as follows:

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

要选择的文件放在的目录命名采用 '+' 和选择器名称。在以上范例中,通过将它们放置在以下位置选择平台配置:

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

To find selected files, QFileSelector looks in the same directory as the base file. If there are any directories of the form +<selector> with an active selector, QFileSelector will prefer a file with the same file name from that directory over the base file. These directories can be nested to check against multiple selectors, for example:

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

有了这些文件,可以在 Android 平台选择不同文件,但前提是语言环境为 en_GB。

对于不存在有效选择器的错误处理,推荐在基文件位置下存在默认文件或错误处理文件,即使期望所有部署都存在选择器。

在未来版本中,某些可能会被标记为部署时静态,并在部署步骤期间因优化而移动。由于选择器自带性能开销,推荐避免将它们用于涉及性能关键代码的情况。

添加选择器

选择器通常可用于的

  • 平台,在其中运行应用程序匹配下列字符串的任何平台 (列表不详尽):Android、iOS、OSX、Darwin、Mac、MacOS、Linux、QNX、Unix、Windows。在 Linux,若可以确定,还可以确定分发名称,像 Debian、Fedora 或 openSUSE。
  • 区域设置,如 QLocale().name()。

进一步,选择器将添加自 QT_FILE_SELECTORS 环境变量,设置时应该是以逗号分隔的一组选择器。注意,只会读取此变量一次;选择器可能不更新,若变量在应用程序运行时改变。仅在首次使用时,评估初始选择器集一次。

还可以在运行时,为自定义行为添加额外选择器。这些将用于任何将来调用 select ()。若额外选择器列表已改变,调用 select () 将使用新列表,且可能以不同方式返回。

当应用多个选择器时的冲突解决方案

当可以把多个选择器应用于同一文件时,选择第一匹配选择器。选择器的校验次序:

  1. 选择器集凭借 setExtraSelectors (),按它们在列表中的次序
  2. 选择器在 QT_FILE_SELECTORS 环境变量,从左到右
  3. 区域设置
  4. 平台

这里是涉及多个选择器的同时匹配范例。它使用平台选择器,加由应用程序基于用户证书设置的名为 admin 的额外选择器。范例有排序以便选取最低匹配文件,若所有选择器存在:

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

由于额外选择器的校验,先于平台 +admin/background.png 将在 Windows 被选取当有设置 admin 选择器时,和 +windows/background.png 将在 Windows 被选取当未设置 admin 选择器时。在 Linux, +admin/+linux/background.png 将被选取当有设置 admin 时,和 +linux/background.png 当不是它时。

成员函数文档编制

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

创建 QFileSelector 实例。此实例将拥有如其它 QFileSelector 实例的相同静态选择器,但它有自己的一组额外选择器。

若提供,它将拥有给定 QObject parent .

[virtual noexcept] QFileSelector:: ~QFileSelector ()

销毁此选择器实例。

QStringList QFileSelector:: allSelectors () const

返回用于此实例的完整、有序选择器列表

QStringList QFileSelector:: extraSelectors () const

返回以编程方式被添加到此实例的额外选择器列表。

另请参阅 setExtraSelectors ().

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

This function returns the selected version of the path, based on the conditions at runtime. If no selectable files are present, returns the original filePath .

If the original file does not exist, the original filePath is returned. This means that you must have a base file to fall back on, you cannot have only files in selectable sub-directories.

See the class overview for the selection algorithm.

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

This is a convenience version of select operating on QUrl objects. If the scheme is not file or qrc, filePath is returned immediately. Otherwise selection is applied to the path of filePath QUrl is returned with the selected path and other QUrl parts the same as filePath .

See the class overview for the selection algorithm.

void QFileSelector:: setExtraSelectors (const QStringList & list )

设置 list of extra selectors which have been added programmatically to this instance.

These selectors have priority over any which have been automatically picked up.

另请参阅 extraSelectors ().