Extensions in UWP Community Toolkit - Overview

概述

UWP Community Toolkit  中有一个 Extensions 的集合,它们可以帮助开发者实现很多基础功能,省去自己造轮子的过程,本篇我们先来看一下 Extensions 的功能都有哪些,再后面会针对每一种 Extensions 做详细的代码分析。

Extensions 集合涵盖了很多方面的扩展,我们先来看一下官方示例的截图:

下面我们分别来看一下每一种扩展的调用过程和展示效果。

 

调用示例

1. FrameworkElementExtensions

FrameworkElementExtensions 为任何 FrameworkElement 提供了一种简单的绑定实际尺寸的方式,扩展利用 EnableActualSizeBinding 来指定是否允许绑定实际尺寸中的 ActualWidth 和 ActualHeight。

来看一下简单的代码示例:

我们使用两个 TextBlock 来显示实际绑定尺寸的宽度和高度,图一是 EnableActualSizeBinding 为 True 时的显示,图二时为 False 时的错误信息显示。 

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <StackPanel Orientation="Vertical">
        <Rectangle x:Name="TargetObject" extensions:FrameworkElementExtensions.EnableActualSizeBinding="true" 
                   Width="300" Height="200" Fill="LightBlue"/>
        <TextBlock Text="{Binding ElementName=TargetObject, Path=(extensions:FrameworkElementExtensions.ActualWidth)}"/>
        <TextBlock Text="{Binding ElementName=TargetObject, Path=(extensions:FrameworkElementExtensions.ActualHeight)}"/>
    </StackPanel>
</Grid>

 

2. ListViewExtensions

ListViewExtensions 为每一种继承了 ListViewBase 类的控件提供了一种轻量级的方式来扩展它的附加属性。目前扩展的附加属性有 AlternateColor、AlternateItemTemplate 和 StretchItemContainerDirection;需要注意的是,扩展使用 ContainerContentChanging 事件来保证工作,如果控件的 ItemsPanel 被设置为 ItemsStackPanel 或 ItemsWrapGrid,那么扩展将不能正常工作。另外 StretchItemContainerDirection 有 Horizontal、Vertical 和 Both 三个选项。

来看一下简单的代码示例:

我们把 AlternateColor 设置为浅灰色,AlternateItemTemplate 中的文字前景色设置为橙色,StretchItemContainerDirection 设置为 Both;可以看到运行显示中 test01 test03 这些元素的显示和设置是一致的。

<Page.Resources>
    <DataTemplate x:Name="NormalTemplate">
        <TextBlock Text="{Binding Title}" Foreground="Green"></TextBlock>
    </DataTemplate>
    <DataTemplate x:Name="AlternateTemplate">
        <TextBlock Text="{Binding Title}" Foreground="Orange"></TextBlock>
    </DataTemplate>
</Page.Resources>

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <ListView x:Name="SampleListView" Margin="12"
                    ItemTemplate="{StaticResource NormalTemplate}"
                    extensions:ListViewExtensions.AlternateColor="LightGray"
                    extensions:ListViewExtensions.AlternateItemTemplate="{StaticResource AlternateTemplate}"
                    extensions:ListViewExtensions.StretchItemContainerDirection="Both">
    </ListView>
</Grid>

3. Mouse

Mouse.Cursor 附加属性让开发者可以轻松的修改指定 Framework element 鼠标悬浮时的显示。这非常实用,比如某个元素正在加载中,鼠标悬浮时可以显示 Wait 状态;比如某个元素处于不可用状态,鼠标悬浮时可以显示 UniversalNo 的状态;Mouse.Cursor 提供的鼠标状态来自 CoreCursorType。

我们来看一下简单的代码示例:

我们水平放置了两个按钮,Mouse.Cursor 分别设置为 UniversalNo 和 Wait,可以看到显示状态和设置的一致。

<StackPanel Orientation="Horizontal" Padding="20">
    <Button Content="Disabled" Width="200" extensions:Mouse.Cursor="UniversalNo"/>
    <Button Content="Loading" Width="200" extensions:Mouse.Cursor="Wait"/>
</StackPanel>

4. NavigationViewStyles

NavigationViewStyles 时一个样式的集合和扩展,可以重新定义 NavigationView 的外观和行为,类似 VSCode 中的 Activity Bar 和 Side Bar;我们需要使用 Activity Bar 的样式文件,在这里可以拿到:https://github.com/Microsoft/UWPCommunityToolkit/blob/master/Microsoft.Toolkit.Uwp.UI/Extensions/NavigationView/Styles/VSCodeActivityBarStyle.xaml

上面所说的是外观的改变,而行为的变化,可以使用两个附加属性:

  • NavigationViewExtensions.SelectedIndex - 以 Index 为基础来调整 NavigationView 的选中项,如果 Index 超过了有效范围,则不选中任何元素;
  • NavigationViewExtensions.CollapseOnClick - 修改 NavigationView 的行为,在用户点击一个已经选择的 Item 时,内容收起;

我们来看一下简单的代码示例:

我们引用了 VSCode 的 Activity Bar 的样式,大家可以和 VSCode 对比一下;另外设置了 SelectedIndex 和 CollapseOnClick,可以看到默认选中是第一个元素,而在选中时点击会收起。

<NavigationView x:Name="NavMenu"
                Style="{StaticResource VSCodeActivityBarStyle}"
                MenuItemContainerStyle="{StaticResource LargeIconNavigationViewItemStyle}"
                ex:NavigationViewExtensions.SelectedIndex="0"
                ex:NavigationViewExtensions.CollapseOnClick="True">
    <NavigationView.MenuItems>
        <NavigationViewItem Content="Explorer" Tag="Some Text">
            <NavigationViewItem.Icon>
                <FontIcon Glyph="&#xE8C8;"/>
            </NavigationViewItem.Icon>
        </NavigationViewItem>
        ...
    </NavigationView.MenuItems>

    <Grid x:Name="ContentGrid" .../>
</NavigationView>

5. ScrollViewerExtensions

ScrollViewerExtensions 提供了一种简单的方式去管理任何容器中的任何 ScrollBar 的 Margin;通过设置 ScrollViewerEx.VerticalScrollBarMargin 或 ScrollViewerEx.HorizontalScrollBarMargin,它是 Thickness 类型。

我们来看一下简单的代码示例:

创建了一个纵向滚动的 ListView,所以我们设置 ScrollViewerEx.VerticalScrollBarMargin 为 0,100,50,0,可以看到下图中的滚动条位置和设置的一致。

<ListView Name="listView"
        extensions:ScrollViewerEx.VerticalScrollBarMargin="0,100,50,0">
    <ListView.ItemTemplate>
        <DataTemplate>
            <Grid MinHeight="100">
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="Auto" />
                    <ColumnDefinition Width="*" />
                </Grid.ColumnDefinitions>
                <TextBlock Grid.Column="0" VerticalAlignment="Center" Text="{Binding Title}" TextTrimming="CharacterEllipsis" />
                <Image x:Name="ToolkitLogo" Stretch="UniformToFill" Grid.Column="1" 
Width
="200" Height="100" Margin="10,0,0,0" Source="{Binding Thumbnail}" /> </Grid> </DataTemplate> </ListView.ItemTemplate> </ListView>

6. StringExtensions

开发者可以使用 StringExtensions 类来对字符串做很多通用场景的校验工作,比如字符串是否为有效的邮件,数字等等。

目前支持的场景如下:

我们来看一下简单的代码示例:

使用 StringExtensions,需要引入 using Microsoft.Toolkit.Extensions; 我们需要校验两个字符串,分别是一个有效的邮箱,和一个无效的数字,结果和预想一致。

using Microsoft.Toolkit.Extensions;

string str1 = "shaomeng@laihua.com";
Debug.WriteLine("shaomeng@laihua.com is Email: " + str1.IsEmail());       //Returns true
string str2 = "123=888";
Debug.WriteLine("123=888 is Decimal: " + str2.IsDecimal());     //Returns false

7. SurfaceDialTextbox

SurfaceDialTextboxHelper 通过 XAML Property 把 Surface Dial 的控制特性加入进来,让用户可以直接使用 Dial 方便的进行数字类型的值切换。 当 TextBox 获得焦点时,Dial 的操作默认就是 SurfaceDialTextbox 的值切换操作,通过旋转 Dial 来切换值,用户可以通过点按 Dial 来切换其他操作。

我们来看一下简单的代码示例:

我们设置一个 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"/>

 

8. TextBoxMask

TextBoxMask 允许用户更简单的输入我们想要的数据格式,比如手机号码等;开发者可以添加这个 mask 属性来防止用户输入指定格式之外的文字;

TextBox Mask 支持三种类型的变量字符:1. [a-Z] 大小写字母;2. [0-9] 数字;3. * 表示前两种都可以;除此之外,还可以支持固定字符,如 ‘-’ 这种不允许修改的占位符;

具体的 mask 书写还需要开发者根据业务需要去制定,我们来看一个简单的例子,mask 是 “9a9a-a9a*”,来看运行截图:图一是清空后的 mask,图二和图三是完整输入后的图,当输入完整后,就不能继续输入字符,而中途错误类型的字符也不能输入。

<TextBox Name="AlphaTextBox" HeaderTemplate="{StaticResource HeaderTemplate}"
        HorizontalAlignment="Center" VerticalAlignment="Center"
        extensions:TextBoxMask.Mask="9a9a-a9a*"
        Header="Text box with Mask 9a9a-a9a* (9 allows from 0 to 9, a allow from a to Z and * allows both a and 9)"
        Text="TextBoxMask" />

  

9. TextBoxRegex

TextBoxRegex 允许按照使用正则表达式或内建的校验类型来做文本校验,和 TextBoxMask 比较类似,一个是输入完成后触发校验,输出校验结果;一个是输入中只能按照正确的结果输入;

开发者设置正则表达式或内建校验类型后,有两种校验模式:1. 保留用户输入,但提示用户输入无效;2. 输入无效时,当textBox 失去焦点,直接把输入清空;

这里的内建的校验类型包括 Email, Decimal, Phone Number, Character or Number。我们直接来看代码示例:

我们创建了三个需要校验的 TextBox,为了直观我们都是用了内建的校验类型。第一个是 PhoneNumber,Forced 模式;第二个是 Email,Normal 模式;第三个是 Decimal,Forced 模式;

第一张图是全部填写符合校验的情况;第二张图是全部不符合校验的情况,可以看到 Email 为 Normal 模式,所以文本不会清空,而剩余两个都是 Forced 模式,失去焦点时文本清空;

<StackPanel Orientation="Vertical" VerticalAlignment="Center" HorizontalAlignment="Center" Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <TextBox extensions:TextBoxRegex.ValidationMode="Forced" extensions:TextBoxRegex.ValidationType="PhoneNumber" 
                    x:Name="PhoneNumberValidator" Text="+61616161611" />
    <StackPanel Orientation="Horizontal">
        <TextBlock Text="PhoneNumber Is Valid: " />
        <TextBlock Text="{Binding (extensions:TextBoxRegex.IsValid), ElementName=PhoneNumberValidator}" />
    </StackPanel>
    <TextBox extensions:TextBoxRegex.ValidationType="Email" x:Name="EmailValidator"/>
    <StackPanel Orientation="Horizontal">
        <TextBlock Text="Email Is Valid: " />
        <TextBlock Text="{Binding (extensions:TextBoxRegex.IsValid), ElementName=EmailValidator}" />
    </StackPanel>
    <TextBox extensions:TextBoxRegex.ValidationMode="Forced" extensions:TextBoxRegex.ValidationType="Decimal" x:Name="DecimalValidator"/>
    <StackPanel Orientation="Horizontal">
        <TextBlock Text="Decimal Is Valid: " />
        <TextBlock Text="{Binding (extensions:TextBoxRegex.IsValid), ElementName=DecimalValidator}" />
    </StackPanel>
</StackPanel>

  

10. ViewExtensions

ViewExtensions 包括 ApplicationViewExtensions, StatusBarExtensions 和 TitleBarExtensions,可以在 XAML 中定制 App 的 AppView,StatusBar 和 TitleBar 的样式;这么功能很方便,因为很多时候我们需要在 App 中对这些部分做定制;这个功能比较简单直观,我们直接来看代码示例吧:

我们定制了 AppView 的 Title,StatusBar 和 TitleBar 的样式,看到运行图和设置的一致;

<Page
    x:Class="CommunityToolkitSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:extensions="using:Microsoft.Toolkit.Uwp.UI.Extensions"
    extensions:ApplicationViewExtensions.Title="View Extensions"
    extensions:StatusBarExtensions.BackgroundColor="Blue"
    extensions:StatusBarExtensions.BackgroundOpacity="0.8"
    extensions:StatusBarExtensions.ForegroundColor="White"
    extensions:StatusBarExtensions.IsVisible="True"
    extensions:TitleBarExtensions.BackgroundColor="Blue"
    extensions:TitleBarExtensions.ForegroundColor="White"
    mc:Ignorable="d">

11. Visual Extensions

通过组件的附加属性,让开发者可以直接在 XAML 中修改可视元素的通用属性。支持修改的属性包括 AnchorPoint,CenterPoint,Offset,Opacity,RotationAngle,RotationAngleInDegrees,RotationAxis,Scale,Size 和 NormalizedCenterPoint。这个功能的使用也非常简单,来看看代码示例:

我们给 Border 设置了 Visual Extensions,包括缩放,旋转,透明度等,可以看到运行图中和设置一致;

<Border Height="100"
    Width="100"
    Background="Purple"
    extensions:VisualExtensions.CenterPoint="50,50,0"
    extensions:VisualExtensions.Opacity="0.5"
    extensions:VisualExtensions.RotationAngleInDegrees="80"
    extensions:VisualExtensions.Scale="2, 0.5, 1"
    extensions:VisualExtensions.NormalizedCenterPoint="0.5, 0.5, 0" />

 

总结

到这里我们就把 UWP Community Toolkit 中的 Extensions 的种类和简单的代码调用讲解完成了,希望这些扩展对大家开发 UWP 应用有所帮助,如果大家有更好用的扩展类,也欢迎大家给 UWPCommunityToolkit 做 PR,贡献自己的代码,欢迎大家多多交流!

而在后面,我会针对每种 Extensions 做详细的代码分析和讲解,谢谢大家支持!

最后,再跟大家安利一下 UWPCommunityToolkit 的官方微博:https://weibo.com/u/6506046490大家可以通过微博关注最新动态。

衷心感谢 UWPCommunityToolkit 的作者们杰出的工作,Thank you so much, UWPCommunityToolkit authors!!!

转载于:https://www.cnblogs.com/shaomeng/p/Extensions.html

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值