.NET MAUI 新手开发助手

# .NET MAUI 页面布局入门：构建响应式界面

## 任务概述
本次任务目标是帮助新手开发者掌握 .NET MAUI 中的基础页面布局技术，使用 XAML 构建一个适配不同屏幕尺寸的响应式界面。我们将从创建项目开始，逐步使用 `VerticalStackLayout`、`HorizontalStackLayout` 和 `Grid` 等核心布局控件，最终实现一个包含标题、输入框和按钮的简单用户界面。

## 分步指南

### 1. 创建 .NET MAUI 项目并配置基础页面结构
```xml
<!-- 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"
             x:Class="MyMauiApp.MainPage"
             Title="布局示例">

    <ScrollView>
        <VerticalStackLayout 
            Padding="20"
            Spacing="15">
            <!-- 内容将在此添加 -->
        </VerticalStackLayout>
    </ScrollView>

</ContentPage>
```
**注意事项**：
- 使用 `ScrollView` 包裹内容，确保在小屏幕设备上可滚动查看全部内容。
- `Padding="20"` 为整个布局添加内边距，避免内容紧贴屏幕边缘。
- 所有 .NET MAUI 项目默认支持 Android、iOS、Windows 和 macOS，无需额外配置即可跨平台运行。

### 2. 添加标题和文本输入区域
```xml
<!-- 在 VerticalStackLayout 内添加以下内容 -->
<Label 
    Text="欢迎使用 .NET MAUI"
    FontSize="24"
    FontAttributes="Bold"
    HorizontalOptions="Center" />

<Entry 
    Placeholder="请输入您的姓名"
    Text="{Binding UserName}"
    HorizontalOptions="Fill" />

<Label 
    Text="选择您的偏好："
    FontSize="18"
    Margin="0,10,0,0" />
```
**注意事项**：
- `HorizontalOptions="Fill"` 确保 `Entry` 控件在不同屏幕宽度下自动拉伸。
- `Margin="0,10,0,0"` 为标签添加上边距，控制元素间距。
- 此处使用了简单数据绑定 `{Binding UserName}`，后续可连接 ViewModel（本阶段可先忽略绑定逻辑，仅用于展示结构）。

### 3. 使用 Grid 布局实现多列按钮
```xml
<!-- 在 VerticalStackLayout 底部添加 -->
<Grid 
    ColumnDefinitions="*,*"
    RowDefinitions="Auto"
    ColumnSpacing="10">
    
    <Button 
        Text="确认"
        Grid.Column="0"
        BackgroundColor="LightGreen"
        Clicked="OnConfirmClicked" />
        
    <Button 
        Text="取消"
        Grid.Column="1"
        BackgroundColor="LightCoral"
        Clicked="OnCancelClicked" />
        
</Grid>
```
**注意事项**：
- `ColumnDefinitions="*,*"` 表示两列等宽（`*` 代表剩余空间均分）。
- `ColumnSpacing="10"` 在按钮之间添加 10 像素间距，提升视觉体验。
- iOS 设备会自动处理安全区域（如刘海屏），但建议在真实设备或模拟器上测试布局效果。

### 4. 添加平台特定适配（可选但推荐）
```xml
<!-- 在 ContentPage 标签内添加 -->
<ContentPage.Padding>
    <OnPlatform x:TypeArguments="Thickness">
        <On Platform="iOS" Value="0,40,0,0" />
        <On Platform="Android" Value="0,20,0,0" />
    </OnPlatform>
</ContentPage.Padding>
```
**注意事项**：
- iOS 状态栏高度通常为 40pt，Android 为 20dp，此设置可避免内容被状态栏遮挡。
- 使用 `OnPlatform` 可针对不同平台微调 UI，但应尽量保持设计一致性。

## 完整示例

**MainPage.xaml**
```xml
<?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"
             x:Class="MyMauiApp.MainPage"
             Title="布局示例">

    <ContentPage.Padding>
        <OnPlatform x:TypeArguments="Thickness">
            <On Platform="iOS" Value="0,40,0,0" />
            <On Platform="Android" Value="0,20,0,0" />
        </OnPlatform>
    </ContentPage.Padding>

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

            <Label 
                Text="欢迎使用 .NET MAUI"
                FontSize="24"
                FontAttributes="Bold"
                HorizontalOptions="Center" />

            <Entry 
                Placeholder="请输入您的姓名"
                HorizontalOptions="Fill" />

            <Label 
                Text="选择您的偏好："
                FontSize="18"
                Margin="0,10,0,0" />

            <Grid 
                ColumnDefinitions="*,*"
                RowDefinitions="Auto"
                ColumnSpacing="10">
                <Button 
                    Text="确认"
                    Grid.Column="0"
                    BackgroundColor="LightGreen" />
                <Button 
                    Text="取消"
                    Grid.Column="1"
                    BackgroundColor="LightCoral" />
            </Grid>

        </VerticalStackLayout>
    </ScrollView>

</ContentPage>
```

**MainPage.xaml.cs**（保持默认即可）
```csharp
namespace MyMauiApp;

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

## 常见问题

1. **布局在小屏幕上显示不全？**  
   **原因**：未使用 `ScrollView` 包裹内容。  
   **解决**：始终将主布局容器放入 `ScrollView` 中，尤其当内容可能超出屏幕高度时。

2. **控件在 iOS 上被刘海或状态栏遮挡？**  
   **原因**：未处理 iOS 安全区域。  
   **解决**：使用 `OnPlatform` 设置 `ContentPage.Padding` 的顶部值，或在 App.xaml 中全局配置 `Page.UseSafeArea="True"`。

3. **Grid 列宽不均或按钮挤压？**  
   **原因**：错误使用固定像素值（如 `WidthRequest="100"`）而非比例定义。  
   **解决**：优先使用 `*`（比例）或 `Auto`（内容自适应）定义列宽，避免硬编码尺寸。

# 数据绑定实现：列表展示

## 任务概述
本任务目标是使用 .NET MAUI 的数据绑定机制，在界面上展示一个动态列表（如商品列表、新闻标题等）。我们将采用 MVVM 模式，通过 `CollectionView` 控件绑定一个可观察集合（`ObservableCollection<T>`），实现数据变更时 UI 自动更新。

---

## 分步指南

### 1. 创建基础项目结构并定义数据模型

**关键代码（C#）**：
```csharp
// Models/Item.cs
public class Item
{
    public string Title { get; set; }
    public string Description { get; set; }
}
```

**注意事项**：
- 数据模型无需继承特殊基类，但若需支持单个属性变更通知（如编辑某一项），应实现 `INotifyPropertyChanged`。
- 此处仅用于只读列表展示，故使用简单 POCO 类即可。

---

### 2. 创建 ViewModel 并初始化可观察集合

**关键代码（C#）**：
```csharp
// ViewModels/MainViewModel.cs
using System.Collections.ObjectModel;

public class MainViewModel
{
    public ObservableCollection<Item> Items { get; } = new();

    public MainViewModel()
    {
        // 初始化示例数据
        Items.Add(new Item { Title = "苹果", Description = "红富士" });
        Items.Add(new Item { Title = "香蕉", Description = "进口香蕉" });
        Items.Add(new Item { Title = "橙子", Description = "赣南脐橙" });
    }
}
```

**注意事项**：
- 必须使用 `ObservableCollection<T>` 而非 `List<T>`，否则新增/删除项不会触发 UI 更新。
- 避免在构造函数中执行耗时操作（如网络请求），应移至异步初始化方法。

---

### 3. 在 XAML 中设置数据绑定上下文并绑定列表

**关键代码（XAML）**：
```xml
<!-- 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"
             xmlns:local="clr-namespace:YourNamespace"
             x:Class="YourNamespace.MainPage">

    <ContentPage.BindingContext>
        <local:MainViewModel />
    </ContentPage.BindingContext>

    <CollectionView ItemsSource="{Binding Items}">
        <CollectionView.ItemTemplate>
            <DataTemplate>
                <VerticalStackLayout Padding="16" Spacing="4">
                    <Label Text="{Binding Title}" FontAttributes="Bold" FontSize="18" />
                    <Label Text="{Binding Description}" TextColor="Gray" />
                    <BoxView HeightRequest="1" Color="#E0E0E0" Margin="0,8" />
                </VerticalStackLayout>
            </DataTemplate>
        </CollectionView.ItemTemplate>
    </CollectionView>
</ContentPage>
```

**注意事项**：
- 确保 `xmlns:local` 的命名空间与项目实际命名空间一致（替换 `YourNamespace`）。
- `CollectionView` 是 .NET MAUI 推荐的列表控件，支持横向/纵向滚动、分组、空视图等高级功能。
- 在 Android 上默认有 16dp 内边距，iOS 需注意安全区域，可包裹在 `ScrollView` 或使用 `Padding` 适配。

---

### 4. （可选）支持动态更新：添加新项测试绑定

**关键代码（C#）**：
```csharp
// 在 MainViewModel 中添加方法
private int _counter = 3;
public void AddNewItem()
{
    Items.Add(new Item 
    { 
        Title = $"水果 {_counter + 1}", 
        Description = "新添加的水果" 
    });
    _counter++;
}
```

并在页面添加按钮触发（XAML）：
```xml
<Button Text="添加水果" Clicked="OnAddClicked" />
```

后台代码（MainPage.xaml.cs）：
```csharp
private void OnAddClicked(object sender, EventArgs e)
{
    var vm = (MainViewModel)BindingContext;
    vm.AddNewItem();
}
```

**注意事项**：
- 不要直接替换 `Items` 引用（如 `Items = new ObservableCollection<...>()`），这会破坏绑定。应清空后逐项添加，或使用 `Clear()` + `Add()`。
- 所有对 `ObservableCollection` 的修改必须在主线程执行，否则在 iOS 上可能崩溃。

---

## 完整示例

**MainPage.xaml.cs**：
```csharp
namespace YourNamespace;

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

    private void OnAddClicked(object sender, EventArgs e)
    {
        var vm = (MainViewModel)BindingContext;
        vm.AddNewItem();
    }
}
```

**App.xaml.cs（确保命名空间正确）**：
```csharp
namespace YourNamespace;
public partial class App : Application
{
    public App()
    {
        InitializeComponent();
        MainPage = new AppShell();
    }
}
```

> 项目结构建议：
> ```
> /Models
>   └── Item.cs
> /ViewModels
>   └── MainViewModel.cs
> /Views
>   └── MainPage.xaml & MainPage.xaml.cs
> ```

---

## 常见问题

1. **列表不显示数据？**
   - 检查 `BindingContext` 是否正确设置（XAML 中或代码中）。
   - 确认 `ItemsSource` 绑定的属性名与 ViewModel 中一致（区分大小写）。
   - 确保 `ObservableCollection` 在页面加载前已初始化（避免 null 引用）。

2. **新增数据后 UI 未刷新？**
   - 确认使用的是 `ObservableCollection<T>` 而非 `List<T>`。
   - 检查是否在非 UI 线程修改集合（如从 `Task.Run` 中直接操作），应使用 `MainThread.InvokeOnMainThreadAsync` 包裹。

3. **XAML 报“类型未找到”错误？**
   - 检查 `xmlns:local` 命名空间是否与项目实际根命名空间匹配。
   - 确保 ViewModel 类为 `public`，且无参数构造函数（XAML 实例化需要）。

# .NET MAUI 页面导航开发指南

## 任务概述
本任务目标是掌握在 .NET MAUI 应用中实现页面跳转（导航）的核心方法，包括使用 `Shell` 导航和 `Navigation` 栈管理两种主流方式。你将学会如何从主页跳转到详情页、传递参数、返回上一页，并理解不同导航模式的适用场景。

---

## 分步指南

### 1. 创建基础页面结构

首先创建两个页面：`MainPage.xaml`（起始页）和 `DetailPage.xaml`（目标页）。

**关键代码（MainPage.xaml）**
```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"
             x:Class="MyApp.MainPage"
             Title="主页">

    <VerticalStackLayout Padding="20" Spacing="20">
        <Label Text="欢迎来到主页！" FontSize="24" HorizontalOptions="Center" />
        
        <Button Text="跳转到详情页"
                Clicked="OnNavigateToDetailClicked"
                HorizontalOptions="Center" />
    </VerticalStackLayout>
</ContentPage>
```

**关键代码（DetailPage.xaml）**
```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"
             x:Class="MyApp.DetailPage"
             Title="详情页">

    <VerticalStackLayout Padding="20" Spacing="20">
        <Label x:Name="MessageLabel" FontSize="18" />
        
        <Button Text="返回主页"
                Clicked="OnGoBackClicked"
                HorizontalOptions="Center" />
    </VerticalStackLayout>
</ContentPage>
```

> **注意事项**：
> - 确保两个页面都已在 `App.xaml.cs` 中注册（若使用传统导航）。
> - `Title` 属性将显示在导航栏（如果启用）。

---

### 2. 实现传统页面导航（Navigation Stack）

使用 `Navigation.PushAsync()` 和 `PopAsync()` 实现页面入栈与出栈。

**关键代码（MainPage.xaml.cs）**
```csharp
private async void OnNavigateToDetailClicked(object sender, EventArgs e)
{
    // 跳转到详情页（入栈）
    await Navigation.PushAsync(new DetailPage());
}
```

**关键代码（DetailPage.xaml.cs）**
```csharp
public partial class DetailPage : ContentPage
{
    public DetailPage()
    {
        InitializeComponent();
        MessageLabel.Text = "这是通过传统导航打开的页面。";
    }

    private async void OnGoBackClicked(object sender, EventArgs e)
    {
        // 返回上一页（出栈）
        await Navigation.PopAsync();
    }
}
```

> **注意事项**：
> - 传统导航要求起始页面必须是 `NavigationPage` 的根页面。
> - 在 `App.xaml.cs` 中初始化时需包装：  
>   `MainPage = new NavigationPage(new MainPage());`

---

### 3. 使用 Shell 导航（推荐方式）

Shell 提供更现代、声明式的导航体验，支持 URI 路由和参数传递。

**关键代码（AppShell.xaml）**
```xaml
<?xml version="1.0" encoding="utf-8" ?>
<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
       xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
       xmlns:local="clr-namespace:MyApp"
       x:Class="MyApp.AppShell">

    <!-- 注册路由 -->
    <ShellContent Title="主页" ContentTemplate="{DataTemplate local:MainPage}" Route="main" />
    <ShellContent ContentTemplate="{DataTemplate local:DetailPage}" Route="detail" />

</Shell>
```

**关键代码（MainPage.xaml.cs - Shell 跳转）**
```csharp
private async void OnNavigateToDetailClicked(object sender, EventArgs e)
{
    // 使用 Shell.Current.GoToAsync 跳转
    await Shell.Current.GoToAsync("//detail");
}
```

**关键代码（DetailPage.xaml.cs - Shell 返回）**
```csharp
private async void OnGoBackClicked(object sender, EventArgs e)
{
    // Shell 自动维护导航栈，返回上一页
    await Shell.Current.GoToAsync("..");
}
```

> **注意事项**：
> - Shell 导航无需手动包装 `NavigationPage`。
> - 使用 `//` 表示绝对路径，避免嵌套路由问题。
> - `..` 表示返回上一级，适用于大多数场景。

---

### 4. 页面间传递参数

通过 Shell 路由传递简单参数（如 ID 或名称）。

**关键代码（MainPage.xaml.cs - 传递参数）**
```csharp
private async void OnNavigateToDetailClicked(object sender, EventArgs e)
{
    // 传递参数 user=张三
    await Shell.Current.GoToAsync("detail?name=张三");
}
```

**关键代码（DetailPage.xaml.cs - 接收参数）**
```csharp
[QueryProperty(nameof(Name), "name")]
public partial class DetailPage : ContentPage
{
    private string name;

    public string Name
    {
        get => name;
        set
        {
            name = value;
            OnPropertyChanged(); // 支持数据绑定更新
        }
    }

    protected override void OnNavigatedTo(NavigatedToEventArgs args)
    {
        base.OnNavigatedTo(args);
        MessageLabel.Text = $"你好，{Name}！";
    }
}
```

> **注意事项**：
> - 必须使用 `[QueryProperty]` 特性绑定查询参数。
> - 参数名必须与 URI 中的键名一致（如 `name`）。
> - 复杂对象应序列化为 JSON 字符串或使用全局服务传递。

---

## 完整示例

**App.xaml.cs**
```csharp
public partial class App : Application
{
    public App()
    {
        InitializeComponent();
        MainPage = new AppShell(); // 使用 Shell 作为主页面
    }
}
```

**AppShell.xaml.cs**
```csharp
public partial class AppShell : Shell
{
    public AppShell()
    {
        InitializeComponent();
    }
}
```

其余页面代码如上所示。此结构支持跨平台（iOS/Android/Windows/macOS）一致导航体验。

---

## 常见问题

1. **问题：点击按钮无反应，页面未跳转**  
   **原因**：未将起始页包装在 `NavigationPage` 中（传统导航），或未在 `AppShell` 中注册路由（Shell 导航）。  
   **解决**：  
   - 传统导航：`MainPage = new NavigationPage(new MainPage());`  
   - Shell 导航：确保 `AppShell.xaml` 中包含 `<ShellContent Route="xxx" ... />`

2. **问题：Shell 导航后无法返回，或返回到错误页面**  
   **原因**：使用了相对路径（如 `"detail"`）而非绝对路径（`"//detail"`），导致路由嵌套。  
   **解决**：跳转到新“层级”时使用 `//` 前缀清除当前栈，例如 `await Shell.Current.GoToAsync("//detail");`

3. **问题：传递的参数在 DetailPage 中为 null**  
   **原因**：未正确使用 `[QueryProperty]`，或属性未触发 UI 更新。  
   **解决**：确保属性有 `set` 逻辑，并在 `OnNavigatedTo` 中使用值；属性名与 URI 参数名严格一致。