C# MAUI XAML 文件格式与控件规范文档

目录

MAUI XAML 文件格式

基本结构

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2022/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MyApp.MainPage"
             Title="Main Page">

    <!-- 页面内容 -->
    <VerticalStackLayout>
        <!-- 控件声明 -->
    </VerticalStackLayout>
</ContentPage>

关键命名空间

  • http://schemas.microsoft.com/dotnet/2022/maui - MAUI核心命名空间
  • http://schemas.microsoft.com/winfx/2009/xaml - XAML扩展功能
  • x:Class - 关联的后台代码类

核心布局控件

1. StackLayout - 线性布局

<StackLayout Orientation="Vertical" Spacing="10">
    <Label Text="顶部标签"/>
    <Button Text="按钮"/>
    <Entry Placeholder="输入文本"/>
</StackLayout>

2. Grid - 网格布局

<Grid RowDefinitions="Auto, *, Auto"
      ColumnDefinitions="*, *, *"
      RowSpacing="10"
      ColumnSpacing="10">

    <Label Text="标题" Grid.Row="0" Grid.ColumnSpan="3"/>
    <Button Text="按钮1" Grid.Row="1" Grid.Column="0"/>
    <Button Text="按钮2" Grid.Row="1" Grid.Column="1"/>
</Grid>

3. FlexLayout - 弹性布局

<FlexLayout Direction="Row"
            JustifyContent="SpaceAround"
            AlignItems="Center"
            Wrap="Wrap">
    <Button Text="按钮1"/>
    <Button Text="按钮2"/>
</FlexLayout>

4. AbsoluteLayout - 绝对布局

<AbsoluteLayout>
    <BoxView Color="Red"
             AbsoluteLayout.LayoutBounds="0,0,100,100"
             AbsoluteLayout.LayoutFlags="None"/>
</AbsoluteLayout>

5. ScrollView - 滚动视图

<ScrollView>
    <VerticalStackLayout>
        <!-- 可能超出屏幕的内容 -->
    </VerticalStackLayout>
</ScrollView>

常用功能控件

1. Label - 文本显示

<Label Text="Hello MAUI!"
       FontSize="20"
       TextColor="Blue"
       HorizontalOptions="Center"
       VerticalOptions="Center"/>

2. Button - 按钮

<Button Text="点击我"
        Clicked="OnButtonClicked"
        BackgroundColor="#2196F3"
        TextColor="White"
        CornerRadius="10"/>

3. Entry/Editor - 文本输入

<Entry Placeholder="单行输入"
       Text="{Binding UserName}"
       Keyboard="Email"/>

<Editor Placeholder="多行文本"
        AutoSize="TextChanges"/>

4. Image - 图片显示

<Image Source="logo.png"
       Aspect="AspectFit"
       HeightRequest="100"/>

5. CollectionView/ListView - 列表

<CollectionView ItemsSource="{Binding Items}">
    <CollectionView.ItemTemplate>
        <DataTemplate>
            <VerticalStackLayout>
                <Label Text="{Binding Name}"/>
                <Label Text="{Binding Description}"/>
            </VerticalStackLayout>
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

数据绑定

基本绑定

<Label Text="{Binding UserName}"/>
<Entry Text="{Binding Email, Mode=TwoWay}"/>

值转换器

<Label Text="{Binding IsActive, Converter={StaticResource BoolToStringConverter}}"/>

样式和资源

样式定义

<ContentPage.Resources>
    <ResourceDictionary>
        <Style x:Key="TitleStyle" TargetType="Label">
            <Setter Property="FontSize" Value="24"/>
            <Setter Property="FontAttributes" Value="Bold"/>
            <Setter Property="HorizontalOptions" Value="Center"/>
        </Style>
    </ResourceDictionary>
</ContentPage.Resources>

样式应用

<Label Text="标题" Style="{StaticResource TitleStyle}"/>

事件处理

<Button Text="保存"
        Clicked="OnSaveClicked"
        Pressed="OnButtonPressed"
        Released="OnButtonReleased"/>

后台代码：

private void OnSaveClicked(object sender, EventArgs e)
{
    // 处理点击事件
}

平台特定设置

<Button Text="点击">
    <Button.OnPlatform>
        <OnPlatform x:TypeArguments="Thickness">
            <On Platform="iOS" Value="0,20,0,0"/>
            <On Platform="Android" Value="0,10,0,0"/>
        </OnPlatform>
    </Button.OnPlatform>
</Button>

完整示例

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2022/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MyApp.LoginPage"
             Title="登录">

    <ScrollView>
        <VerticalStackLayout Spacing="20" Padding="30">

            <!-- 标题 -->
            <Label Text="用户登录"
                   FontSize="28"
                   FontAttributes="Bold"
                   HorizontalOptions="Center"/>

            <!-- 表单 -->
            <VerticalStackLayout Spacing="15">
                <Label Text="用户名"/>
                <Entry Placeholder="请输入用户名"
                       Text="{Binding UserName}"
                       Keyboard="Default"/>

                <Label Text="密码"/>
                <Entry Placeholder="请输入密码"
                       Text="{Binding Password}"
                       IsPassword="True"/>

                <!-- 记住我 -->
                <HorizontalStackLayout>
                    <CheckBox IsChecked="{Binding RememberMe}"/>
                    <Label Text="记住我"/>
                </HorizontalStackLayout>
            </VerticalStackLayout>

            <!-- 按钮区域 -->
            <VerticalStackLayout Spacing="10">
                <Button Text="登录"
                        Clicked="OnLoginClicked"
                        BackgroundColor="#007AFF"
                        TextColor="White"/>

                <Button Text="注册账号"
                        Clicked="OnRegisterClicked"
                        TextColor="#007AFF"/>
            </VerticalStackLayout>

        </VerticalStackLayout>
    </ScrollView>

</ContentPage>

最佳实践

  1. 使用MVVM模式：分离UI逻辑和业务逻辑
  2. 资源重用：将样式、颜色等定义为资源
  3. 响应式设计：使用自适应布局
  4. 性能优化：
  5. 避免嵌套过深
  6. 使用数据绑定虚拟化
  7. 合理使用图片资源
  8. 平台适配：考虑不同平台的UI差异

文档版本：1.0
最后更新：2023年
适用版本：.NET MAUI 7.0+