Extensions in UWP Community Toolkit - SurfaceDialTextbox

概述

UWP Community Toolkit Extensions 中有一個為TextBox 提供的 SurfaceDial 擴展 - SurfaceDialTextbox，本篇我們結合代碼詳細講解 SurfaceDialTextbox 的實現。

SurfaceDialTextbox 為 TextBox 提供了一種簡單的 Surface Dial 的菜單和操作方式，支持設置 TextBox 操作在 Dial 中的圓形菜單，選擇後旋轉 Dial 可以方便的對 TextBox 中的數值進行調整，調整方式類似於 NumericUpdown，可以設置數值上限和下限，以及步長；旋轉 Dial 可以選擇有震動反饋，超過界限後也會有反饋提示，點按 Dial 可以選擇 Focus 到下一個 Element。接下來看看官方示例的截圖：

Source: https://github.com/Microsoft/UWPCommunityToolkit/tree/master/Microsoft.Toolkit.Uwp.UI/Extensions/SurfaceDialTextbox

Doc: https://docs.microsoft.com/zh-cn/windows/uwpcommunitytoolkit/extensions/surfacedialtextboxhelper

Namespace: Microsoft.Toolkit.Uwp.UI.Extensions; Nuget: Microsoft.Toolkit.Uwp.UI;

開發過程

代碼分析

SurfaceDialTextbox 的處理在類 SurfaceDialTextbox.cs 中，我們先來看看類的結構：

可以看到類中定義瞭如下的依賴屬性：

• ForceMenuItem - 標誌是否強制在 Surface Dial 上下文菜單中加入 SurfaceDialTextbox 對應的菜單，如果應用中沒有其他控制器，則需要設置為 True；如果有，則設置一致即可；
• Icon - SurfaceDialTextbox 在 Surface Dial 上下文菜單中顯示的 Icon，類型是 RadialControllerMenuKnownIcon，枚舉類型；預設為 Ruler；
• StepValue - 標誌了旋轉 Surface Dial 時，每旋轉一次對應的數值變化步長；變化時觸發 StepValueChanged 事件；
• EnableHapticFeedback - 標誌了是否允許在旋轉 Surface Dial 時的震動反饋；
• MinValue - 數值變化的最小值；預設為 -100；
• MaxValue - 數值變化的最大值；預設為 100；
• EnableTapToNextControl - 標誌是否在點擊 Surface Dial 時，將 Focus 移動到下一個 Item；適用於表單類場景，需要切換多個 TextBox；
• EnableMinMaxValue - 標誌是否為 SurfaceDialTextbox 設置數值最小值和最大值；

然後我們看幾個全局靜態變數：

• _controller - RadialController 類型，是 Surface Dial controller 實例； 
• Controller - _controller 對應的 public 類型，支持在調用代碼中獲取 Surface Dial controller 實例，用於 SurfaceDialTextbox 之外的控制項上；
• _stepTextMenuItem - RadialControllerMenuItem 類型，在 Surface Dial 上下文菜單中顯示的菜單項；
• _textBox - SurfaceDialTextbox 對應的 textBox 控制項；

接下來看幾個 SurfaceDialTextbox 對應的主要處理方法：

1. Controller_RotationChanged(sender, args)

Surface Dial 旋轉時觸發的事件處理方法，根據當前顯示的 Text，獲取對應的 double 類型值；根據當前 Dial 旋轉角度和 StepValue 來判斷數值的變化，如果允許最大最小值區間限制，則判斷是否越界後設置數值；如果 Text 不是數值，則設置預設值 0.0；

private static void Controller_RotationChanged(RadialController sender, RadialControllerRotationChangedEventArgs args)
{
    if (_textBox == null)
    {
        return;
    }

    string t = _textBox.Text;
    double nr;

    if (double.TryParse(t, out nr))
    {
        nr += args.RotationDeltaInDegrees * GetStepValue(_textBox);
        if (GetEnableMinMaxValue(_textBox))
        {
            if (nr < GetMinValue(_textBox))
            {
                nr = GetMinValue(_textBox);
            }

            if (nr > GetMaxValue(_textBox))
            {
                nr = GetMaxValue(_textBox);
            }
        }
    }
    else
    {
        // default to zero if content is not a number
        nr = 0.0d;
    }

    _textBox.Text = nr.ToString("0.00");
}

2.  StepValueChanged(d, e)

StepValue 屬性改變時觸發事件的處理邏，為 textBox 設置 GotFocus 和 LostFocus 事件綁定，我們來看看這兩個事件的處理：

TextBox_GotFocus(sender, e) 處理邏輯：獲取 Radial Controller，如果需要添加 MenuItem，則根據設置添加對應的 MenuItem；設置轉動時的震動反饋，旋轉的步長，旋轉變化事件；如果允許點擊 Focus 到下一個控制項，則設置 Radial Controller 的 點擊事件；

private static void TextBox_GotFocus(object sender, RoutedEventArgs e)
{
    _textBox = sender as TextBox;

    if (_textBox == null)
    {
        return;
    }

    if (!IsSupported)
    {
        return;
    }

    _controller = _controller ?? RadialController.CreateForCurrentView();

    if (GetForceMenuItem(_textBox))
    {
        _stepTextMenuItem = RadialControllerMenuItem.CreateFromKnownIcon("Step Text Box", GetIcon(_textBox));
        _controller.Menu.Items.Add(_stepTextMenuItem);
        _controller.Menu.SelectMenuItem(_stepTextMenuItem);
    }

    _controller.UseAutomaticHapticFeedback = GetEnableHapticFeedback(_textBox);
    _controller.RotationResolutionInDegrees = 1;
    _controller.RotationChanged += Controller_RotationChanged;
    if (GetEnableTapToNextControl(_textBox))
    {
        _controller.ButtonClicked += Controller_ButtonClicked;
    }
}

TextBox_LostFocus(sender, e)  GotFocus 事件對應的相反處理，作用是在 Radial Controller menu 中去掉對應的 MenuItem；解除 RotationChanged 和 Controller_ButtonClicked 事件的綁定；

private static void TextBox_LostFocus(object sender, RoutedEventArgs e)
{
    if (_textBox == null)
    {
        return;
    }

    if (GetForceMenuItem(_textBox))
    {
        _controller.Menu.Items.Remove(_stepTextMenuItem);
    }

    _controller.RotationChanged -= Controller_RotationChanged;
    if (GetEnableTapToNextControl(_textBox))
    {
        _controller.ButtonClicked -= Controller_ButtonClicked;
    }

    _textBox = null;
}

調用示例

我們設置一個 SurfaceDialTextbox，預設值為 0，每次變化為 1，區間是 0～100；來看第一張圖中，點按 Dial 時會出現 SurfaceDialTextbox 的菜單，菜單圖標是尺子；點按後可以通過旋轉來改變 textbox 的值；如果初始時不點按 Dial，直接旋轉也是一樣改變 textbox 的值；在值超出 0～100 區間時，Dial 會有震動反饋；

<TextBox HorizontalAlignment="Left" 
        VerticalAlignment="Top" 
        Margin="0,0,0,10"
        Text="0" 
        Width="250" Height="50" FontSize="20"
        extensions:SurfaceDialTextbox.StepValue="1"
        extensions:SurfaceDialTextbox.ForceMenuItem="True"
        extensions:SurfaceDialTextbox.EnableHapticFeedback="True"
        extensions:SurfaceDialTextbox.EnableMinMaxValue="True"
        extensions:SurfaceDialTextbox.MinValue="0"
        extensions:SurfaceDialTextbox.MaxValue="100"
        extensions:SurfaceDialTextbox.Icon="Ruler"
     extensions:SurfaceDialTextbox.EnableTapToNextControl="True"/>

總結

到這裡我們就把 UWP Community Toolkit Extensions 中的 SurfaceDialTextbox 的源代碼實現過程和簡單的調用示例講解完成了，希望能對大家更好的理解和使用這個擴展有所幫助。歡迎大家多多交流，謝謝！

最後，再跟大家安利一下 UWPCommunityToolkit 的官方微博：https://weibo.com/u/6506046490, 大家可以通過微博關註最新動態。

衷心感謝 UWPCommunityToolkit 的作者們傑出的工作，Thank you so much, UWPCommunityToolkit authors!!!