💡
HarmonyOS開発実践：HarmonyOSアプリケーション開発におけるページ管理ツールクラスの詳細解説

2025/06/30に公開
 HarmonyOS開発実践：HarmonyOSアプリケーション開発におけるページ管理ツールクラスの詳細解説一、まえがき
HarmonyOSアプリケーション開発の道のりにおいて、いかに効率的にページレイアウトと表示を管理し、ユーザーが没入型のエクスペリエンスやパーソナライズされたステータスバーの色など、インターフェース特性のニーズを満たすかは、常に開発者が注目する焦点でした。このため、私は特別に実用的な「ページ管理ツールクラス」を設計しました。これは強力な機能を備えており、開発者がさまざまなページ管理の課題に簡単に対応できるようにします。
二、ページ管理ツールクラス：あなたのインターフェースを掌握する強力なツール
ページ管理ツールクラスは、インターフェースを掌握する強力なツールのようなもので、開発者に一連の専門的な静的属性とメソッドを提供します。これらの機能を活用することで、開発者はページの重要な情報、例えばトップセーフティエリアの高さ（ステータスバーの高さ）、ボトムセーフティエリアの高さ、フルスクリーン開発ステータス、ステータスバーの色など、を簡単に取得することができます。このツールクラスは、HarmonyOSアプリケーション開発において欠かせない部分です。
三、コアプロパティの詳細な解説
トップセーフティエリアの高さ（ステータスバーの高さ）
変数名：static statusBarHeight: number = 0
解説：このプロパティは、開発者がトップセーフティエリアの高さ、つまりステータスバーの高さをすばやく取得するのに役立ちます。ステータスバーが占めるスクリーンスペースを把握することで、開発者はページコンテンツをより正確にレイアウトし、コンテンツが隠れることを防ぐことができます。
ボトムセーフティエリアの高さ
変数名：static navigationBarHeight: number = 0
解説：このプロパティは、ボトムセーフティエリアの高さを表しており、通常ナビゲーションバーの高さに相当します。この値を知ることで、開発者はページコンテンツがナビゲーションバーと重ならないようにし、ユーザー エクスペリエンスを向上させることができます。
フルスクリーン開発ステータス
変数名：static isFullScreenLayout: boolean
解説：このプロパティは、アプリがフルスクリーン開発ステータスかどうかを判断するために使います。trueに設定すると、アプリはシステムUI要素を無視し、真正的なフルスクリーン効果を実現します。falseに設定すると、アプリはこれらのUI要素の存在を考慮します。
現在のステータスバーのコンテンツの色
変数名：static statusBarContentColor: string
解説：開発者はこのプロパティを通じて、現在のステータスバーのコンテンツの色を取得または設定することができます。これにより、ステータスバーがアプリ全体のスタイルと一致し、アプリの視覚効果とユーザー エクスペリエンスが向上します。
アプリのメインウィンドウ
変数名：static appMainWindow: window.Window
解説：このプロパティは、アプリのメインウィンドウへの参照を提供し、開発者がメインウィンドウの various properties と methods に直接アクセスすることができ、ウィンドウを正確に制御し管理することができます。
四、初期化メソッド：あなたのインターフェースを掌握する旅を簡単に開始する
ページ管理ツールクラスは、初期化メソッドを提供しています。開発者は、適切なパラメーターを渡すことで、このツールクラスを簡単に開始することができます。初期化プロセスでは、ツールクラスは自動的にメインウィンドウオブジェクトを取得し、フルスクリーン開発ステータスを設定し、トップとボトムセーフティエリアの高さを計算し、後のページレイアウトと管理のための基本データを提供します。
五、実用メソッドの集錦
ページ管理ツールクラスは、ステータスバーの透明度を設定したり、ナビゲーションバーのスタイルを調整するなど、一連の実用的なメソッドも提供しています。これらのメソッドは、機能が強力で使いやすく、開発者がさまざまなインターフェース効果を素早く実現するのに役立ちます。
六、機能の要点分析
setWindowLayoutFullScreen(fullScreen: boolean):
このメソッドは、アプリウィンドウがフルスクリーン表示かどうかを制御します。

appMainWindowが存在する場合、そのsetWindowLayoutFullScreenメソッドを呼び出し、fullScreenパラメーターを渡します。
setStatusBarLightContent と setStatusBarDarkContent:
これらの2つのメソッドは、ステータスバーの文字色をそれぞれ白色と黑色に素早く設定するために使います。
実際には、setStatusBarContentColorメソッドを呼び出し、適切な色の値を渡します。
setStatusBarContentColor(color: string):
このメソッドは、ステータスバーの文字色を設定します。
最初に、渡されたcolorが現在のstatusBarContentColorと同じかどうかを確認し、同じであれば、不要な操作を避けるために直接戻ります。
色が異なる場合、statusBarContentColorの値を更新し、appMainWindowのsetWindowSystemBarPropertiesメソッドを呼び出してステータスバーの文字色を設定します。
setStatusBarColor(color: string):
このメソッドは、ステータスバーの背景色を設定します。

appMainWindowが存在する場合、そのsetWindowSystemBarPropertiesメソッドを呼び出し、ステータスバーの背景色を渡します。
showStatusBar と hideStatusBar:
これらの2つのメソッドは、それぞれステータスバーを表示したり隠したりするために使います。

appMainWindowのsetWindowSystemBarEnableメソッドを呼び出し、適切なパラメーターを渡して、ステータスバーの表示と隠しを制御します。
七、全体コードの展示
import window from '@ohos.window'
import { display } from '@kit.ArkUI'
import { UIUtil } from './UIUtil'

/**
 * ページステータスバーなどについて
 */
export class LibWindowHelper {
  // トップステータスバーの高さ
  static statusBarHeight: number = 0;

  // ボトムナビゲーションバーの高さ
  static navigationBarHeight: number = 0;

  // フルスクリーンレイアウトを有効にするかどうか
  static isFullScreenLayout: boolean;

  // 現在のステータスバーのコンテンツの色
  static statusBarContentColor: string;

  // アプリのメインウィンドウオブジェクト
  static appMainWindow: window.Window;

  // 初期化メソッド
  static initialize(windowStage: window.WindowStage, isFullScreen: boolean) {
    // アプリのメインウィンドウオブジェクトを取得する
    LibWindowHelper.appMainWindow = windowStage.getMainWindowSync();

    // フルスクリーンレイアウトステータスを設定する
    LibWindowHelper.isFullScreenLayout = isFullScreen;

    // フルスクリーンレイアウトが有効の場合、ウィンドウをフルスクリーンモードに設定する
    if (LibWindowHelper.isFullScreenLayout) {
      LibWindowHelper.appMainWindow.setWindowLayoutFullScreen(isFullScreen);
    }

    // トップステータスバー領域を取得し、高さを計算する
    let avoidAreaTop = LibWindowHelper.appMainWindow.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);
    LibWindowHelper.statusBarHeight = Number(UIUtil.px2vp(avoidAreaTop.topRect.height).toPrecision(5));

    // ボトムナビゲーションバー領域を取得し、高さを計算する
    let avoidAreaBottom = LibWindowHelper.appMainWindow.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR);
    LibWindowHelper.navigationBarHeight = Number(UIUtil.px2vp(avoidAreaBottom.bottomRect.height).toPrecision(5));

    // フォルダブル画面のステータスを監視する
    LibWindowHelper.listenDisplayFoldStatus();
  }

  /**
   * アプリウィンドウのフルスクリーンレイアウトを設定する
   *
   * @param fullScreen フルスクリーン表示するかどうか
   */
  static setWindowLayoutFullScreen(fullScreen: boolean) {
    if (LibWindowHelper.appMainWindow) {
      LibWindowHelper.appMainWindow.setWindowLayoutFullScreen(fullScreen);
    }
  }

  /**
   * ステータスバーの文字色を白色に設定する
   */
  static setStatusBarLightContent() {
    LibWindowHelper.setStatusBarContentColor('#ffffff');
  }

  /**
   * ステータスバーの文字色を黑色に設定する
   */
  static setStatusBarDarkContent() {
    LibWindowHelper.setStatusBarContentColor('#000000');
  }

  /**
   * ステータスバーの文字色を設定する
   *
   * @param color ステータスバーの文字色
   */
  static setStatusBarContentColor(color: string) {
    // 色が変更されていない場合は、不要な操作を避けるために直接戻る
    if (color === LibWindowHelper.statusBarContentColor) {
      return;
    }
    LibWindowHelper.statusBarContentColor = color;
    if (LibWindowHelper.appMainWindow) {
      LibWindowHelper.appMainWindow.setWindowSystemBarProperties({
        statusBarContentColor: LibWindowHelper.statusBarContentColor
      });
    }
  }

  /**
   * ステータスバーの背景色を設定する
   *
   * @param color ステータスバーの背景色
   */
  static setStatusBarColor(color: string) {
    if (LibWindowHelper.appMainWindow) {
      LibWindowHelper.appMainWindow.setWindowSystemBarProperties({
        statusBarColor: color
      });
    }
  }

  /**
   * ステータスバーを表示する
   */
  static showStatusBar() {
    if (LibWindowHelper.appMainWindow) {
      LibWindowHelper.appMainWindow.setWindowSystemBarEnable(['status', 'navigation']);
    }
  }

  /**
   * ステータスバーを隠す
   */
  static hideStatusBar() {
    if (LibWindowHelper.appMainWindow) {
      LibWindowHelper.appMainWindow.setWindowSystemBarEnable(['navigation']);
    }
  }
  
}
八、ツールクラスの使用説明と注意点
使用説明
EntryAbility.tsファイルで、ページレイアウトと表示を管理するためにLibWindowHelperツールクラスを使用するには、以下の手順に従ってください。
1. ウィンドウヘルパーツールの初期化
ウィンドウステージ（windowStage）が作成された後、LibWindowHelperを初期化する必要があります。onWindowStageCreateメソッドを呼び出し、windowStageパラメーターを渡すことで、メインウィンドウの参照を取得し、LibWindowHelper.initializeメソッドを使用して初期化することができます。
例のコード：
onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.getMainWindow((err, mainWindow) => {
        if (err) {
            // メインウィンドウを取得する際に発生したエラーを処理する
            console.error('メインウィンドウの取得に失敗しました：', err);
        } else {
            // ウィンドウヘルパーツールを初期化し、フルスクリーン表示モードをtrueに設定する
            LibWindowHelper.initialize(mainWindow, true);
        }
    });
}
2. フルスクリーン表示を有効化または無効化する
LibWindowHelper.setWindowLayoutFullScreenメソッドを呼び出すことで、アプリのフルスクリーン表示モードを簡単に有効化または無効化することができます。trueを渡すとフルスクリーン表示が有効になり、falseを渡すと無効になります。
例のコード：
// フルスクリーン表示を有効化する
LibWindowHelper.setWindowLayoutFullScreen(true);

// フルスクリーン表示を無効化する
LibWindowHelper.setWindowLayoutFullScreen(false);
3. ステータスバーの文字色を設定する
ステータスバーの背景がダークカラーの場合、ステータスバーの文字色をダークカラーに設定して可読性を高める必要がある場合があります。LibWindowHelper.setStatusBarDarkContentメソッドを使用することで、これを実現できます。
例のコード：
// ステータスバーの文字色をダークカラーに設定する
LibWindowHelper.setStatusBarDarkContent();
4. ステータスバーの背景色をカスタマイズする
LibWindowHelperは、setStatusBarColorメソッドを使用してステータスバーの背景色をカスタマイズできる機能を提供します。16進数の色コード文字列を渡すだけです。
例のコード：
// ステータスバーの背景色をダークグレーに設定する
LibWindowHelper.setStatusBarColor('#333333');
5. ステータスバーの表示と非表示を制御する
LibWindowHelperが提供するshowStatusBarとhideStatusBarメソッドを使用して、ステータスバーの表示と非表示を制御できます。
ステータスバーを表示する例のコード：
// ステータスバーを表示する
LibWindowHelper.showStatusBar();
ステータスバーを非表示にする例のコード：
// ステータスバーを非表示にする
LibWindowHelper.hideStatusBar();
注意事項

LibWindowHelperのメソッドを呼び出す前に、そのクラスが正しくインポートされ、プロジェクトで使用可能であることを確認してください。
メソッドを呼び出す際は、渡すパラメーターが正しいかを確認し、LibWindowHelperのドキュメントに従ってください。
メソッドを呼び出す際にエラーが発生した場合は、コンソールに表示されるエラー情報を注意深く確認し、エラー情報をもとにデバッグや修正を行ってください。
フルスクリーン表示モードは、アプリのレイアウトやユーザー エクスペリエンスに影響を与える可能性があるため、使用する際は慎重に検討してください。
ステータスバーのスタイルや色を変更すると、アプリの全体的な視覚効果に影響を与える可能性があるため、アプリのテーマと一貫性があるように設計することをお勧めします。
九、おわりに
ページ管理ツールクラスは、HarmonyOSアプリケーション開発における実用的なツールであり、開発者がページレイアウトと表示を効果的に管理できる強力な機能を提供します。このツールクラスのコアプロパティとメソッドを理解することで、開発者はさまざまなページ管理の課題に簡単に立ち向かい、ユーザーにより優れた、パーソナライズされたインターフェース エクスペリエンスを提供することができます。この記事があなたがページ管理ツールクラスをよりよく理解し、使用するのに役立ち、HarmonyOSアプリケーション開発の旅にさらに多くの支援をもたらすことを願っています。
HarmonyOS開発実践：HarmonyOSアプリケーション開発におけるページ管理ツールクラスの詳細解説

Discussion
