プロジェクト構成とリソース
このガイドでは、QML のインポート方法、アプリケーションのディレクトリ構成、リソースパスでよくある問題を説明します。RinUI は Qt Quick のコンポーネントライブラリです。QML からモジュールをインポートし、Python 側では PySide6 を使って Qt アプリケーションを起動します。
RinUI のインポート
RinUI コントロールを使用する QML ファイルの先頭でモジュールをインポートします。
qml
import QtQuick
import QtQuick.Controls
import RinUI
Python パッケージをインストールした環境では、通常 QML から `import RinUI` を使用できます。イベントループが終了するまで、アプリケーションとウィンドウのオブジェクトを保持してください。
```python
import sys
from PySide6.QtWidgets import QApplication
from RinUI import RinUIWindow
app = QApplication(sys.argv)
window = RinUIWindow("main.qml")
sys.exit(app.exec())インストール済みパッケージではなくソースツリーから実行する場合は、リポジトリの Gallery やサンプルの起動方法に従ってください。任意の作業ディレクトリからローカルの RinUI モジュールを解決できるとは限りません。
推奨するアプリ構成
Python の起動コード、QML ページ、静的リソースを役割ごとに分けます。
text
my-app/
├── main.py
├── main.qml
├── pages/
│ └── HomePage.qml
└── assets/
├── images/
└── fonts/アプリ固有のページや画像はアプリのプロジェクト内に配置します。RinUI のコントロールは import RinUI で使用できるため、各ページへコンポーネントのソースをコピーする必要はありません。
リソースパス
QML の相対 URL は通常、その URL を宣言した QML ファイルを基準に解決されます。プロジェクト内のリソースには相対パスまたは Qt リソース URL を使用し、パッケージ設定にも対象ファイルを含めてください。
qml
Image {
source: "assets/images/logo.png"
}
サブディレクトリ内のページでは、そのページの場所からの相対パスを指定します。安定して配布するリソースは Qt リソースコレクションに含め、起動時の作業ディレクトリに依存しない `qrc:/...` URL で参照できます。
## QML モジュールとコンポーネント
ページは独立した `.qml` ファイルに分け、親ページで組み合わせます。アプリ固有のページと再利用可能なコンポーネントを分離してください。コンポーネント名とプロパティはドキュメントおよびインストール済みバージョンのソースを確認します。API は開発中に変更される場合があります。
インポートの問題を調査するときは、次の点を確認してください。
1. 使用中の Python インタープリターに RinUI と依存関係がインストールされている。
2. QML に大文字小文字を正しく指定した `import RinUI` がある。
3. 起動コードが想定した QML ファイルを読み込んでいる。
4. 独自 QML モジュールのディレクトリと `qmldir` がインポートパスに含まれている。
## HiDPI のサイズ指定
Qt Quick の `width`、`height`、`font.pixelSize` は論理ピクセル単位です。設計上のサイズをそのまま使用してください。デバイスピクセル比をさらに掛けると二重に拡大されます。ウィンドウを異なるサイズに対応させるには、物理ピクセルに直接結び付けるのではなく、アンカー、レイアウト、適切な最小・最大サイズを利用します。
グローバルテーマや補助 API については、[テーマ](/ja/core/theme) と [ユーティリティ](/ja/core/utils) を参照してください。