Androidプラットフォームに関する注意事項

このページには、Android 上で Qt アプリケーションをビルドおよび実行する際の具体的な情報が記載されています。サポートされている Androidバージョンおよび API レベルについては、「サポートされている Androidバージョン」を参照してください。

プラグインとインポートに関する特別な注意事項

アプリケーションが他のモジュールに依存するプラグインを使用する場合、それらのモジュールはアプリケーションの依存関係にリストアップする必要があります。詳細については、「依存関係の検出」を参照してください。

Qt GUI 依存関係

Androidアプリには通常GUI要素が含まれるため、Qt for Androidプラグインは主にGUIを提供するために構築されており、さまざまなQPA抽象化を実装しています。その結果、Qt for Androidアプリのデプロイには、 Qt GUIへの依存関係が生じることが想定されます。さらに、Qt Creator はGradleによるビルドおよびデプロイのみをサポートしており、コマンドラインやシェルからの実行は標準ではサポートされていない点に留意してください。

戻るキーと戻るジェスチャー

Android では、戻るジェスチャー（Android 13 以降）およびシステムの戻るキーの押下は、ウィンドウの閉じ操作ではなく、ナビゲーション要求として扱われます。戻るキーの押下を処理する項目がない場合、その操作によりアプリケーションはバックグラウンドに移行します。アプリケーションは終了するのではなく、状態を維持したまま、中断した箇所から再開します。

Qt 6.12以降、戻るキーの押下はActivity.moveTaskToBack() を使用してアプリケーションをバックグラウンドに移行させ、閉じるイベントを配信しなくなりました。つまり、ユーザーが戻るキーを押しても、QWidget::closeEvent() およびWindow.onClosing シグナルはトリガーされません。アプリケーションがこれらのシグナルに依存して戻るボタンの押下をインターセプトしている場合は、以下に示すShortcut のアプローチを採用する必要があります。

代わりに、StackView からページを表示するなど、アプリケーション内でナビゲーションを行う場合は、戻るキーを処理してイベントを受け入れてください。イベントを受け入れることで、Qt がアプリケーションをバックグラウンドに送るのを防ぐことができます。推奨される方法は、Back キーシーケンスにバインドされたウィンドウレベルのショートカットを使用することです。これにより、どのアイテムにフォーカスが当たっていてもイベントが発生します。

Shortcut {
    sequences: ["Back"]
    enabled: Qt.platform.os === "android" && stack.depth > 1
    onActivated: stack.pop()
}

Androidでは、StandardKey.Back ではなく、"Back" のキーシーケンスを使用してください。標準キーには、ハードウェアキーボードで押された際に発動するBackspace およびAlt+Left もバインドされています。

スタックの最上層では、enabled はfalse に変換されるため、戻る操作がそのまま透過され、Qt XMLはアプリケーションをバックグラウンドに送ります。未保存の変更があることを事前に警告するには、変更が保留中の間にショートカットを有効にし、onActivated からプロンプトを表示します。変更の処理が完了すると、ショートカットは無効になり、次に「戻る」が押されるとアプリケーションはバックグラウンドに送られます。

フォーカスされているアイテムも、`Keys.onBackPressed` を通じて `Qt::Key_Back ` を処理できますが、それはアクティブなフォーカスを保持している間のみです。タッチ操作によるインターフェースでは、フォーカスされているアイテムが存在しないことが多いため、戻る操作がそのアイテムに到達することはありません。ウィンドウレベルのショートカットはフォーカスに関係なく一致するため、より安全な選択肢となります。

OpenGL に関する特別な考慮事項

最近のデバイスでは、2.0に加えてOpenGL ES 3.0または3.1をサポートしていることがよくあります。適切なOpenGLコンテキストを取得するには、QSurfaceFormat::setVersion() を使用して要求するバージョンを設定してください。

既知の問題

Qt Creator デバッグに関する問題

詳細については、「Qt Creator の既知の問題」を参照してください。

予測入力

一部のデバイスにおけるバグのため、ImhNoPredictiveText で予測入力をオフにしても、このプロパティは無視され、予測入力は有効なままになります。この問題を回避するには、環境変数QT_ANDROID_ENABLE_WORKAROUND_TO_DISABLE_PREDICTIVE_TEXT を1 に設定してください。ただし、この環境変数の設定は、Gboardなどの他のキーボードで問題を引き起こす可能性があるという副作用があります。 日本語などの言語を使用する場合、GboardではQWERTYキーボードしか表示されません。この環境変数はキーボードが表示されるたびに確認されるため、必要に応じてこの回避策をオン/オフに切り替えることが可能です。

テキストグリフのキャッシュ

一部のOpenGLドライバに存在するバグのため、Qtがテキストグリフをキャッシュするために使用するメカニズムが、すべてのAndroidデバイスで期待通りに動作せず、テキストが乱れて表示されることがあります。これを修正するための回避策が導入されていますが、これによりメモリ消費量が増加し、テキストのレンダリングパフォーマンスにも影響を与える可能性があります。現在、この回避策はすべてのデバイスでデフォルトで使用されています。

環境変数 `QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND ` を1またはtrue に設定することで、この回避策を無効にできます。ただし、対象となるすべてのデバイスでテキストが正しく表示されることを確認した上で、この設定を行うようにしてください。

制限事項

一部の Qt モジュールやツールには、Android でサポートされていない機能や制限がある場合があります。プラットフォームに関する制限については、各モジュールのドキュメントを参照してください。