Avalonia Android 13+ 存储权限适配实践指南：从崩溃修复到合规迁移

Android 13（API 33）引入的分区存储机制彻底改变了应用访问文件的方式，导致大量Avalonia应用因权限问题频繁崩溃。本文将系统讲解如何为Avalonia.Android应用实现权限适配，通过Manifest声明优化、运行时权限请求和框架API迁移三种方案，彻底解决文件访问失败问题，确保应用在Android 13+设备上稳定运行。

存储权限变更深度解析

Android 13+对存储权限进行了根本性重构，传统的WRITE_EXTERNAL_STORAGE权限已被完全废弃，转而采用细粒度的媒体文件权限体系。这种变化直接影响所有涉及文件操作的Avalonia应用，特别是图片、音频和视频处理功能。

新旧权限机制对比

权限类型	适用Android版本	权限范围	申请方式
WRITE_EXTERNAL_STORAGE	Android 12及以下	所有外部存储文件	清单声明+运行时请求
READ_EXTERNAL_STORAGE	Android 12及以下	所有外部存储文件	清单声明+运行时请求
READ_MEDIA_IMAGES	Android 13+	仅图片文件	清单声明+运行时请求
READ_MEDIA_VIDEO	Android 13+	仅视频文件	清单声明+运行时请求
READ_MEDIA_AUDIO	Android 13+	仅音频文件	清单声明+运行时请求

未适配的应用在Android 13+设备上尝试访问媒体文件时，会触发SecurityException，典型错误日志如下：

java.lang.SecurityException: Permission Denial: opening provider 
com.android.externalstorage.ExternalStorageProvider from ProcessRecord

清单文件权限声明升级

第一步是更新AndroidManifest.xml文件，移除已废弃的权限声明，添加Android 13+要求的新权限组合。

操作步骤

1. 定位项目中的AndroidManifest.xml文件：[samples/ControlCatalog.Android/Properties/AndroidManifest.xml]

2. 移除旧权限声明：

<!-- 移除不再使用的旧权限 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

3. 添加Android 13+专用权限：

<!-- Android 13+媒体文件访问权限 -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

<!-- 保留对旧版本Android的兼容性 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" 
                 android:maxSdkVersion="32" />

注意：通过android:maxSdkVersion="32"属性，可以确保旧权限仅在Android 12及以下版本生效，避免在高版本系统中产生冲突。

运行时权限请求实现

Manifest声明仅完成了权限配置的第一步，还需要在应用运行时动态请求这些危险权限。Avalonia.Android应用需要在MainActivity中实现权限检查和请求逻辑。

完整实现代码

修改MainActivity.cs文件：[samples/ControlCatalog.Android/MainActivity.cs]

using Android;
using Android.App;
using Android.Content.PM;
using Android.OS;
using AndroidX.Core.App;
using AndroidX.Core.Content;

namespace ControlCatalog.Android
{
    [Activity(Label = "ControlCatalog.Android",
              Theme = "@style/MyTheme.NoActionBar",
              MainLauncher = true)]
    public class MainActivity : Avalonia.Android.Activity
    {
        // 权限请求码，用于在回调中识别请求
        private const int MediaPermissionsRequestCode = 1001;
        
        protected override async void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);
            
            // 检查Android版本，仅在Android 13+上请求新权限
            if (Build.VERSION.SdkInt >= BuildVersionCodes.Tiramisu)
            {
                await RequestMediaPermissionsAsync();
            }
            else if (Build.VERSION.SdkInt >= BuildVersionCodes.M)
            {
                // 处理Android 6.0-12的权限请求
                await RequestLegacyStoragePermissionsAsync();
            }
            else
            {
                // Android 6.0以下无需运行时请求
                InitializeFileOperations();
            }
        }
        
        // 请求Android 13+媒体权限
        private async Task RequestMediaPermissionsAsync()
        {
            // 检查权限是否已授予
            var isImagesGranted = ContextCompat.CheckSelfPermission(
                this, Manifest.Permission.ReadMediaImages) == Permission.Granted;
            var isVideosGranted = ContextCompat.CheckSelfPermission(
                this, Manifest.Permission.ReadMediaVideo) == Permission.Granted;
            var isAudioGranted = ContextCompat.CheckSelfPermission(
                this, Manifest.Permission.ReadMediaAudio) == Permission.Granted;
            
            if (isImagesGranted && isVideosGranted && isAudioGranted)
            {
                // 所有权限已授予，初始化文件操作
                InitializeFileOperations();
                return;
            }
            
            // 请求缺失的权限
            ActivityCompat.RequestPermissions(this, new[] {
                Manifest.Permission.ReadMediaImages,
                Manifest.Permission.ReadMediaVideo,
                Manifest.Permission.ReadMediaAudio
            }, MediaPermissionsRequestCode);
        }
        
        // 处理权限请求结果
        public override void OnRequestPermissionsResult(
            int requestCode, string[] permissions, Permission[] grantResults)
        {
            base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
            
            if (requestCode == MediaPermissionsRequestCode)
            {
                bool allGranted = true;
                foreach (var result in grantResults)
                {
                    if (result != Permission.Granted)
                    {
                        allGranted = false;
                        break;
                    }
                }
                
                if (allGranted)
                {
                    InitializeFileOperations();
                }
                else
                {
                    // 权限被拒绝，显示功能受限提示
                    ShowPermissionDeniedDialog();
                }
            }
        }
        
        // 初始化文件操作功能
        private void InitializeFileOperations()
        {
            // 在这里初始化需要文件访问权限的功能模块
            // 例如：注册文件选择器服务、初始化媒体库访问等
        }
        
        // 显示权限被拒提示
        private void ShowPermissionDeniedDialog()
        {
            new AlertDialog.Builder(this)
                .SetTitle("权限被拒绝")
                .SetMessage("应用需要媒体文件访问权限才能正常工作。请在设置中启用权限。")
                .SetPositiveButton("前往设置", (sender, args) =>
                {
                    // 引导用户前往应用设置页面
                    var intent = new Android.Content.Intent(
                        Android.Provider.Settings.ActionApplicationDetailsSettings,
                        Android.Net.Uri.FromParts("package", PackageName, null));
                    StartActivity(intent);
                })
                .SetNegativeButton("取消", (sender, args) => { })
                .Show();
        }
    }
}

权限请求流程图

sequenceDiagram
    participant 应用 as Avalonia应用
    participant 系统 as Android系统
    participant 用户 as 用户
    
    应用->>系统: 检查Android版本
    alt Android 13+
        系统-->>应用: 返回Android 13+版本信息
        应用->>系统: 查询媒体权限状态
        alt 权限未授予
            应用->>用户: 显示权限请求对话框
            用户->>系统: 允许/拒绝权限
            系统-->>应用: 返回权限状态
            alt 权限已授予
                应用->>应用: 初始化文件操作功能
            else 权限被拒绝
                应用->>用户: 显示功能受限提示
            end
        else 权限已授予
            应用->>应用: 直接初始化文件操作功能
        end
    else Android 6.0-12
        系统-->>应用: 返回Android 6.0-12版本信息
        应用->>系统: 请求READ_EXTERNAL_STORAGE权限
    else Android 6.0以下
        系统-->>应用: 返回Android 6.0以下版本信息
        应用->>应用: 直接初始化文件操作功能
    end

使用Avalonia存储API（推荐方案）

Avalonia框架提供了跨平台的IStorageProvider接口，该接口会自动适配不同平台的权限要求，是处理存储访问的最佳实践。

IStorageProvider接口优势

• 跨平台兼容性：同一套代码可在Windows、macOS、Linux和Android上运行
• 自动权限管理：在需要时自动请求必要的权限
• 符合平台规范：遵循各平台的文件访问最佳实践
• 简化代码：无需编写平台特定的权限处理逻辑

实现代码示例

using Avalonia.Platform.Storage;
using Avalonia.Controls;

public class MediaFileHandler
{
    private readonly TopLevel _topLevel;
    
    public MediaFileHandler(Control control)
    {
        // 获取TopLevel实例，通常从当前窗口或控件获取
        _topLevel = TopLevel.GetTopLevel(control);
    }
    
    // 打开图片选择器并处理选中的图片
    public async Task ProcessImageFileAsync()
    {
        if (_topLevel?.StorageProvider == null)
            throw new InvalidOperationException("存储提供器不可用");
            
        try
        {
            // 配置文件选择器选项
            var options = new FilePickerOpenOptions
            {
                Title = "选择图片",
                // 仅允许选择图片文件
                FileTypeFilter = new[] { FilePickerFileTypes.Images },
                // 允许选择多个文件
                AllowMultiple = false
            };
            
            // 打开文件选择器，Avalonia会自动处理权限请求
            var files = await _topLevel.StorageProvider.OpenFilePickerAsync(options);
            
            if (files.Any())
            {
                var selectedFile = files[0];
                // 读取文件内容
                using var stream = await selectedFile.OpenReadAsync();
                // 处理图片流（例如显示图片、上传等）
                await ProcessImageStreamAsync(stream);
            }
        }
        catch (Exception ex)
        {
            // 处理异常（如权限被拒、用户取消选择等）
            Console.WriteLine($"文件处理错误: {ex.Message}");
        }
    }
    
    private async Task ProcessImageStreamAsync(Stream stream)
    {
        // 实现图片处理逻辑
        // ...
    }
}

存储API工作原理

Avalonia的IStorageProvider在Android平台上的实现位于[TizenStorageProvider.cs]，它封装了Android的存储访问框架(SAF)，自动处理权限请求和文件访问。当调用OpenFilePickerAsync方法时，系统会显示标准的文件选择器，用户选择文件后，应用会获得该文件的临时访问权限，无需直接请求存储权限。

Avalonia应用使用IStorageProvider API选择媒体文件示例

适配checklist与最佳实践

完成存储权限适配后，请使用以下checklist验证适配效果：

• [ ] 已更新AndroidManifest.xml，移除旧权限并添加新权限
• [ ] 实现了基于Android版本的条件权限请求逻辑
• [ ] 添加了权限被拒时的友好提示和引导
• [ ] 迁移到IStorageProvider API处理文件访问
• [ ] 在Android 13+设备上测试媒体文件读取功能
• [ ] 在Android 12及以下设备上验证向后兼容性
• [ ] 测试权限被拒情况下的应用稳定性

最佳实践建议

1. 最小权限原则：仅请求应用必需的权限，例如仅处理图片的应用无需请求音频权限
2. 权限请求时机：在用户需要使用相关功能时才请求权限，避免应用启动时集中请求
3. 提供清晰说明：在请求权限前，向用户解释为什么需要该权限以及如何使用
4. 优雅降级：当权限被拒时，确保应用仍能正常运行，只是功能受限
5. 测试覆盖：至少在Android 12和Android 13设备上进行测试

未来展望

Avalonia框架正在不断改进跨平台权限处理机制。未来版本可能会提供更统一的权限请求API，进一步简化开发者的适配工作。建议关注Avalonia官方仓库和更新日志，及时了解权限处理的新特性和最佳实践。

随着Android系统安全性的不断提升，权限管理将更加精细化。采用IStorageProvider等框架API是长期可持续的解决方案，能够自动适应未来的平台变化，减少维护成本。

要获取最新的Avalonia项目代码，可通过以下命令克隆仓库：

git clone https://gitcode.com/GitHub_Trending/ava/Avalonia

通过本文介绍的三种适配方案，你的Avalonia应用将能够平稳过渡到Android 13+的存储权限体系，提供更可靠的用户体验并避免权限相关的崩溃问题。