Back to Qt.io
Contact Us Blog Download Qt
このページでは

QFileSelector Class

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 を使用すれば、このような定型コードを記述する手間を省くことができ、後者のケースでは、再コンパイルすることなくプラットフォーム固有の設定を使用できるようになります。 また、QFileSelector を使用すると、複数のセレクタを便利な方法で連鎖させることができます。たとえば、特定のプラットフォームとロケールの組み合わせの場合にのみ、別のファイルを選択することが可能です。プラットフォームおよび／またはロケールに基づいて選択する場合、コードは次のようになります:

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

選択対象のファイルは、'+' とセレクタ名を組み合わせた名前のディレクトリに配置されます。上記の例では、プラットフォーム設定を以下の場所に配置することで、それらを選択対象に指定できます：

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

選択されたファイルを検索する際、QFileSelector はベースファイルと同じディレクトリ内を検索します。 アクティブなセレクタを持つ「+<selector>」という形式のディレクトリが存在する場合、QFileSelectorはベースファイルよりも、そのディレクトリ内にある同じファイル名のファイルを優先します。これらのディレクトリはネストして、複数のセレクタに対してチェックを行うことができます。例えば：

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

これらのファイルが存在する場合、Androidプラットフォームでは、ロケールがen_GBである場合に限り、別のファイルが選択されます。

有効なセレクタが存在しない場合のエラー処理については、すべてのデプロイでセレクタが存在すると想定している場合でも、ベースファイルの場所にデフォルトファイルまたはエラー処理用ファイルを配置することを推奨します。

将来のバージョンでは、最適化の一環として、一部のセレクタが「デプロイ時の静的セレクタ」としてマークされ、デプロイステップ中に移動される可能性があります。セレクタにはパフォーマンス上のオーバーヘッドが伴うため、パフォーマンスが重要なコードを扱う状況では、その使用を避けることを推奨します。

セレクタの追加

通常利用可能なセレクタは以下の通りです。

  • platform、およびアプリケーションが実行されているプラットフォームに一致する以下の文字列のいずれか（このリストはすべてを網羅しているわけではありません）：android、harmonyos、ios、osx、darwin、mac、macos、linux、qnx、unix、windows。 Linux では、判別可能な場合、debian、fedora、opensuse などのディストリビューション名も指定できます。
  • locale：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

追加のセレクタはプラットフォームのセレクタよりも先にチェックされるため、Windows では「admin」セレクタが設定されている場合は+admin/background.png が選択され、設定されていない場合は+windows/background.png が選択されます。Linux では、「admin」が設定されている場合は+admin/+linux/background.png が選択され、設定されていない場合は+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

この関数は、実行時の条件に基づいて、パスから選択されたバージョンを返します。選択可能なファイルが存在しない場合は、元のfilePath を返します。

元のファイルが存在しない場合は、元のfilePath が返されます。つまり、フォールバック用のベースファイルが必要であり、選択可能なサブディレクトリ内のファイルのみでは不十分です。

選択アルゴリズムについては、クラスの概要を参照してください。

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

これは、QUrl オブジェクトに対してselectを適用する便利なバージョンです。スキームがfileまたはqrcでない場合、filePath が即座に返されます。それ以外の場合は、filePath のパスに対して選択が適用され、選択されたパスとその他のQUrl 部分を、filePath と同様に保持したQUrl が返されます。

選択アルゴリズムについては、クラスの概要を参照してください。

void QFileSelector::setExtraSelectors(const QStringList &list)

このインスタンスにプログラムによって追加された追加のセレクタのlist を設定します。

これらのセレクタは、自動的に検出されたセレクタよりも優先されます。

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.