.NET MAUI项目iOS模拟器中实现图片圆角的问题

问题重现 #

在.NET MAUI项目的iOS模拟器中尝试实现带圆角的矩形图片效果，两次尝试均未达到预期：

• 尝试1：用Border包裹Image并设置RoundRectangle形状，仅Border显示圆角，内部图片未被裁剪
• 尝试2：改用ImageButton，按钮自身圆角正常，但内部图片仍为直角

尝试1 XAML代码 #

<Border Stroke="Black" StrokeThickness="2" Padding="0">
    <Border.Shape>
        <RoundRectangle CornerRadius="20"/>
    </Border.Shape>
    <Image Source="test_image.jpg" Aspect="AspectFill"/>
</Border>

尝试2 XAML代码 #

<ImageButton Source="test_image.jpg" CornerRadius="20" Aspect="AspectFill" BackgroundColor="Transparent"/>

问题原因 #

• iOS平台上，Border的Shape属性仅控制自身的外观裁剪，不会影响内部子控件的显示
• ImageButton的CornerRadius仅作用于按钮容器，其内部的UIImageView默认不会自动开启裁剪（MasksToBounds未设置为true）

解决方案 #

方案1：给Image设置Clip属性 #

直接通过Image.Clip指定圆角裁剪区域，确保图片被裁剪：

<Image Source="test_image.jpg" Aspect="AspectFill">
    <Image.Clip>
        <RoundRectangleGeometry CornerRadius="20" Rect="0,0,200,200"/>
    </Image.Clip>
</Image>

注意：Rect的宽高需与Image的实际显示尺寸一致，若使用自适应布局，可在代码后台根据Image的最终尺寸动态设置Rect值。

方案2：自定义ImageHandler（全局复用推荐） #

针对iOS平台自定义Image的Handler，通过原生控件属性开启裁剪：

1. 在项目Platforms/iOS目录下创建自定义Handler：

using Microsoft.Maui.Handlers;
using UIKit;

namespace YourAppNamespace.Platforms.iOS;

public class RoundedImageHandler : ImageHandler
{
    protected override void ConnectHandler(UIImageView platformView)
    {
        base.ConnectHandler(platformView);
        UpdateCornerRadius();
    }

    protected override void DisconnectHandler(UIImageView platformView)
    {
        platformView.Layer.CornerRadius = 0;
        platformView.Layer.MasksToBounds = false;
        base.DisconnectHandler(platformView);
    }

    public static void MapCornerRadius(IImageHandler handler, IImage image)
    {
        if (handler.PlatformView is UIImageView imageView && image is IRoundedImage roundedImage)
        {
            imageView.Layer.CornerRadius = (nfloat)roundedImage.CornerRadius;
            imageView.Layer.MasksToBounds = true;
        }
    }
}

public interface IRoundedImage : IImage
{
    double CornerRadius { get; }
}

2. 在共享项目中创建自定义RoundedImage控件：

using Microsoft.Maui.Controls;

namespace YourAppNamespace;

public class RoundedImage : Image, IRoundedImage
{
    public static readonly BindableProperty CornerRadiusProperty =
        BindableProperty.Create(nameof(CornerRadius), typeof(double), typeof(RoundedImage), 0.0);

    public double CornerRadius
    {
        get => (double)GetValue(CornerRadiusProperty);
        set => SetValue(CornerRadiusProperty, value);
    }
}

3. 在MauiProgram.cs中注册Handler：

builder.ConfigureMauiHandlers(handlers =>
{
#if IOS
    handlers.AddHandler<RoundedImage, RoundedImageHandler>();
#endif
});

4. XAML中使用自定义控件：

<local:RoundedImage Source="test_image.jpg" Aspect="AspectFill" CornerRadius="20"/>

方案3：修复ImageButton的图片圆角 #

若需继续使用ImageButton，可自定义其Handler开启裁剪：

1. 在Platforms/iOS目录下创建RoundedImageButtonHandler：

using Microsoft.Maui.Handlers;
using UIKit;

namespace YourAppNamespace.Platforms.iOS;

public class RoundedImageButtonHandler : ImageButtonHandler
{
    protected override void ConnectHandler(UIButton platformView)
    {
        base.ConnectHandler(platformView);
        UpdateCornerRadius();
    }

    protected override void DisconnectHandler(UIButton platformView)
    {
        platformView.Layer.CornerRadius = 0;
        platformView.Layer.MasksToBounds = false;
        base.DisconnectHandler(platformView);
    }

    public static void MapCornerRadius(IButtonHandler handler, IButton button)
    {
        if (handler.PlatformView is UIButton btn)
        {
            btn.Layer.CornerRadius = (nfloat)button.CornerRadius;
            btn.Layer.MasksToBounds = true;
            btn.SetBackgroundImage(UIImage.FromImage(null), UIControlState.Normal);
        }
    }
}

2. 在MauiProgram.cs注册：

builder.ConfigureMauiHandlers(handlers =>
{
#if IOS
    handlers.AddHandler<ImageButton, RoundedImageButtonHandler>();
#endif
});

3. XAML中使用ImageButton即可实现图片圆角：

<ImageButton Source="test_image.jpg" CornerRadius="20" Aspect="AspectFill" BackgroundColor="Transparent"/>

内容的提问来源于stack exchange，提问作者Gratzy