.NET MAUI 螢幕持續恆亮

當在進行行動裝 App 開發的時候，有時候會需要讓裝置的螢幕持續恆亮，例如，正在進行大量檔案上傳或者下載、需要大量呼叫不同的遠端 Web API等等，不會因為裝置的自動關閉螢幕的時間有多少，而受到影響。這時候，就可以使用 .NET MAUI 內建的 平台功能 內的 [裝置顯示資訊] 功能來做到控制螢幕是否要維持恆亮，此時，可以透過 DeviceDisplay.Current.KeepScreenOn 這個屬性來控制裝置的螢幕是否持續恆亮。

建立採用 Prism 開發框架的 MAUI 專案

• 打開 Visual Studio 2022 IDE 應用程式

• 從 [Visual Studio 2022] 對話窗中，點選右下方的 [建立新的專案] 按鈕

• 在 [建立新專案] 對話窗右半部

  • 切換 [所有語言 (L)] 下拉選單控制項為 [C#]
  • 切換 [所有專案類型 (T)] 下拉選單控制項為 [MAUI]

• 在中間的專案範本清單中，找到並且點選 [Vulcan Custom Prism .NET MAUI App] 專案範本選項

  若沒有看到這個專案範本，請參考 使用 Vulcan.Maui.Template 專案範本來進行 MAUI for Prism 專案開發 文章，進行安裝這個專案範本到 Visual Studio 2022 內

• 點選右下角的 [下一步] 按鈕

• 在 [設定新的專案] 對話窗

• 在 [專案名稱] 欄位內輸入 mauiSwitchScreenAlwaysOn 做為這個專案名稱

• 請點選右下角的 [建立] 按鈕

• 此時，將會建立一個可以用於 MAUI 開發的專案

修正 MainPage 之 View & ViewModel & CodeBehind

• 打開 [Views] 資料夾下的 [MainPage.xaml] 檔案
• 使用底下標記宣告替換掉這個原有檔案內容

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             Title="{Binding Title}"
             x:Class="mauiSwitchScreenAlwaysOn.Views.MainPage"
             xmlns:viewModel="clr-namespace:mauiSwitchScreenAlwaysOn.ViewModels"
             x:DataType="viewModel:MainPageViewModel">

  <ScrollView>
    <VerticalStackLayout
            Spacing="25"
            Padding="30,0"
            VerticalOptions="Center">

      <Label Text="螢幕是否恆亮"
             FontSize="32"
             HorizontalOptions="Center" />

      <Label Text="{Binding AlwaysScreenOn}"
             FontSize="18"
             HorizontalOptions="Center" />

            <Button Text="切換螢幕恆亮"
              Command="{Binding SwitchScreenAlwaysOnCommand}"
              HorizontalOptions="Center" />

    </VerticalStackLayout>
  </ScrollView>

</ContentPage>

在這裡的 XAML 宣告標記中，我們使用了 Button 控制項，並且設定了 Command 屬性為 SwitchScreenAlwaysOnCommand 這個命令，這個命令是在 ViewModel 內所定義的，當該按鈕被觸發之後，將會切換 [AlwaysScreenOn] 這個可綁定屬性質，接著，便會呼叫讓螢幕是否恆亮的 API。

• 打開 [ViewModels] 資料夾下的 MainPageViewModel.cs 檔案
• 使用底下程式碼替換掉這個原有檔案內容

using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

namespace mauiSwitchScreenAlwaysOn.ViewModels;

public partial class MainPageViewModel : ObservableObject, INavigatedAware
{
    #region Field Member
    private int _count;
    private readonly INavigationService navigationService;

    #endregion

    #region Property Member
    [ObservableProperty]
    string title = "Main Page";

    [ObservableProperty]
    string text = "Click me";

    [ObservableProperty]
    bool alwaysScreenOn = false;
    #endregion

    #region Constructor
    public MainPageViewModel(INavigationService navigationService)
    {
        this.navigationService = navigationService;
    }
    #endregion

    #region Method Member
    #region Command Method
    [RelayCommand]
    void SwitchScreenAlwaysOn()
    {
        AlwaysScreenOn = !AlwaysScreenOn;
        MainThread.BeginInvokeOnMainThread(() =>
        {
            DeviceDisplay.Current.KeepScreenOn = AlwaysScreenOn;
        });
        
    }
    #endregion

    #region Navigation Event
    public void OnNavigatedFrom(INavigationParameters parameters)
    {
    }

    public void OnNavigatedTo(INavigationParameters parameters)
    {
    }
    #endregion

    #region Other Method
    #endregion
    #endregion
}

在這裡的 ViewModel 內，我們定義了一個 SwitchScreenAlwaysOn 這個命令，當這個命令被觸發之後，將會切換 [AlwaysScreenOn] 這個可綁定屬性值，接著，便會呼叫 DeviceDisplay.Current.KeepScreenOn = AlwaysScreenOn; 讓螢幕是否恆亮的 API。這裡注意到的是，我們使用了 MainThread.BeginInvokeOnMainThread 這個方法，這是因為我們需要在主執行緒上執行這個 API。

執行與確認結果

• 底下是在 Android 模擬器內執行的結果

點選 [] 按鈕之後的結果將會是，裝置的螢幕將會維持恆亮，不會因為該裝置設定的自動關閉螢幕的時間有多少，而受到影響。

 

.NET MAUI 軟體鍵盤的隱藏控制

當在進行 .NET MAUI 專案開發的時候，若使用者點選了 Entry 或者 Editor 控制項，軟體鍵盤會自動彈出來，這時候，若使用者點選了畫面上的其他地方，軟體鍵盤會自動隱藏。這個功能是由 .NET MAUI 內建的功能所提供的。但是，這樣的功能需要能夠同時在 Android & iOS 平台下能夠運作。這個範例將會示範如何透過程式碼來控制軟體鍵盤的隱藏。

想要控制軟體鍵盤可以自動的隱藏起來，這裡將會需要用到 ContentPage.HideSoftInputOnTapped 屬性。這個屬性是一個布林值，當這個屬性設定為 true 的時候，軟體鍵盤會自動隱藏起來。

建立採用 Prism 開發框架的 MAUI 專案

• 打開 Visual Studio 2022 IDE 應用程式

• 從 [Visual Studio 2022] 對話窗中，點選右下方的 [建立新的專案] 按鈕

• 在 [建立新專案] 對話窗右半部

  • 切換 [所有語言 (L)] 下拉選單控制項為 [C#]
  • 切換 [所有專案類型 (T)] 下拉選單控制項為 [MAUI]

• 在中間的專案範本清單中，找到並且點選 [Vulcan Custom Prism .NET MAUI App] 專案範本選項

  若沒有看到這個專案範本，請參考 使用 Vulcan.Maui.Template 專案範本來進行 MAUI for Prism 專案開發 文章，進行安裝這個專案範本到 Visual Studio 2022 內

• 點選右下角的 [下一步] 按鈕

• 在 [設定新的專案] 對話窗

• 在 [專案名稱] 欄位內輸入 mauiSoftKeyboardVisibility 做為這個專案名稱

• 請點選右下角的 [建立] 按鈕

• 此時，將會建立一個可以用於 MAUI 開發的專案

修正 MainPage 之 View & ViewModel & CodeBehind

• 打開 [Views] 資料夾下的 [MainPage.xaml] 檔案
• 使用底下標記宣告替換掉這個原有檔案內容

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             Title="{Binding Title}"
             x:Class="mauiSoftKeyboardVisibility.Views.MainPage"
             xmlns:viewModel="clr-namespace:mauiSoftKeyboardVisibility.ViewModels"
             x:DataType="viewModel:MainPageViewModel"
             >
    <Grid x:Name="ThisGrid" BackgroundColor="LightYellow">
        <Rectangle Fill="LightBlue" HorizontalOptions="Fill" VerticalOptions="Fill"
                    InputTransparent="True" >
            <Rectangle.GestureRecognizers>
                <TapGestureRecognizer Command="{Binding HiddenSoftKeyboardCommand}" />
            </Rectangle.GestureRecognizers>
        </Rectangle>
        <ScrollView>
            <VerticalStackLayout
            Spacing="25"
            Padding="30,0"
            VerticalOptions="Center">

                <Label Text="Hello, World!"
             SemanticProperties.HeadingLevel="Level1"
             FontSize="32"
             HorizontalOptions="Center" >
                    <Label.GestureRecognizers>
                        <TapGestureRecognizer Command="{Binding HiddenSoftKeyboardCommand}" />
                    </Label.GestureRecognizers>

                </Label>

                <Entry />

                <Entry />

                <Label Text="Welcome to Prism for .NET MAUI"
             SemanticProperties.HeadingLevel="Level2"
             SemanticProperties.Description="Welcome to Prism for dot net Multi platform App U I"
             FontSize="18"
             HorizontalOptions="Center" />

                <Entry />

                <Button Text="{Binding Text}"
              SemanticProperties.Hint="Counts the number of times you click"
              Command="{Binding CountCommand}"
              HorizontalOptions="Center" />

            </VerticalStackLayout>
        </ScrollView>
    </Grid>

</ContentPage>

在這個 [MainPage.xaml] 頁面的標記宣告中，在最底層宣告了一個 [Rectangle] 控制項，這個控制項的作用是當使用者點選了這個控制項的時候(也就是點選螢幕非文字輸入的其他地方，此時，就會觸發 [TapGestureRecognizer] 這個手勢操作，也就是會去執行 [HiddenSoftKeyboardCommand] 這個命令。

另外，在這個頁面上，也宣告了三個 Entry 控制項，讓使用者點選這些控制項之後，將會自動彈出軟體鍵盤出來。

• 打開 [Views] 資料夾下的 [MainPage.xaml.cs] 檔案
• 使用底下程式碼替換掉這個原有檔案內容

using mauiSoftKeyboardVisibility.ViewModels;

namespace mauiSoftKeyboardVisibility.Views;

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();

        this.Focused += (s, e) =>
        {
            this.HideSoftInputOnTapped = true;
        };
    }

    protected override void OnAppearing()
    {
        MainPageViewModel MainPageViewModel = this.BindingContext as MainPageViewModel;
        MainPageViewModel.HiddenSoftKeyboardHandle = HiddenSoftKeyboard;
        base.OnAppearing();
    }

    public void HiddenSoftKeyboard()
    {
        this.HideSoftInputOnTapped = true;
    }
}

在這個 [MainPage.xaml.cs] 檔案中，透過 this.Focused 事件，當這個頁面被 Focus 之後，就會將這個頁面的 [HideSoftInputOnTapped] 屬性設定為 true，使得軟體鍵盤就會自動隱藏起來。

接著，在 [OnAppearing] 方法中，透過 [BindingContext] 屬性來取得這個頁面的 ViewModel 物件，其型別為 [MainPageViewModel]，並且將這個 ViewModel 的 [HiddenSoftKeyboardHandle] 這個Action 代理人物件 (封裝具有單一參數的方法，並且不會傳回值)，設定為這個頁面的 [HiddenSoftKeyboard] 方法。如此，便可以在 ViewModel 內，執行該 [ContentPage] 內 CodeBehind 內的程式碼了。

• 打開 [ViewModels] 資料夾下的 MainPageViewModel.cs 檔案
• 使用底下程式碼替換掉這個原有檔案內容

using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

namespace mauiSoftKeyboardVisibility.ViewModels;

public partial class MainPageViewModel : ObservableObject, INavigatedAware
{
    #region Field Member
    private int _count;
    private readonly INavigationService navigationService;
    public Action HiddenSoftKeyboardHandle { get; set; }
    #endregion

    #region Property Member
    [ObservableProperty]
    string title = "Main Page";

    [ObservableProperty]
    string text = "Click me";
    #endregion

    #region Constructor
    public MainPageViewModel(INavigationService navigationService)
    {
        this.navigationService = navigationService;
    }
    #endregion

    #region Method Member
    #region Command Method
    [RelayCommand]
    void HiddenSoftKeyboard()
    {
        HiddenSoftKeyboardHandle?.Invoke();
    }
    [RelayCommand]
    private void Count()
    {
        _count++;
        if (_count == 1)
            Text = "Clicked 1 time";
        else if (_count > 1)
            Text = $"Clicked {_count} times";
    }
    #endregion

    #region Navigation Event
    public void OnNavigatedFrom(INavigationParameters parameters)
    {
    }

    public void OnNavigatedTo(INavigationParameters parameters)
    {
    }
    #endregion

    #region Other Method
    #endregion
    #endregion
}

在這個 [MainPageViewModel.cs] 檔案中，宣告了一個 Action 類型的 HiddenSoftKeyboardHandle 屬性 (public Action HiddenSoftKeyboardHandle { get; set; })，這個屬性是用來存放一個方法的參考，當這個方法被執行的時候，就會去執行這個方法。

這裡也設計一個 [RelayCommand] 類型的方法 HiddenSoftKeyboard，這個方法是用來執行這個 HiddenSoftKeyboardHandle 方法的。這樣，當這個方法被執行的時候，就會去執行這個 HiddenSoftKeyboardHandle 方法，這裡使用了 HiddenSoftKeyboardHandle?.Invoke(); 這個敘述來執行委派實際的方法。

執行與確認結果

• 底下是在 Android 模擬器內執行的結果

此時，將會看到這個頁面上有三個 Entry 文字輸入盒控制項，請隨便點選一個文字輸入盒控制項，軟體鍵盤就會自動彈出來。

接著，點選螢幕上的其他地方，軟體鍵盤就會自動隱藏起來。