简介本资源是一个面向C#跨平台移动开发者的Xamarin.Forms相机功能实战示例聚焦解决在iOS、Android统一代码中调用原生设备相机并处理照片的核心难题适用于具备基础XAML和C#能力的中级开发者快速掌握平台桥接与权限适配。压缩包共83个文件含23个核心C#逻辑文件如ICameraService接口及各平台实现、3个XAML界面布局文件、31张PNG/JPG截图与示意图、4个CSProj项目配置及Info.plist等平台配置文件整体仅286KB轻量易导入目录结构清晰呈现Src/主项目分层。已有307人学习下载资源提供完整可运行解决方案涵盖DependencyService接口定义、iOS的UIImagePickerController调用、Android的MediaStore Intent实现、运行时权限申请逻辑、照片流转换与Image控件绑定、以及基础错误提示与降级方案如相册备选是理解Xamarin.Forms平台服务集成机制的典型教学范例。1. Xamarin.Forms 相机功能不是“调个 API 就完事”它本质是跨平台原生能力桥接的黑匣子不搞清 CameraView 生命周期和权限链90% 的闪退都发生在用户第一次点拍照按钮的 0.3 秒内你写好一个 Xamarin.Forms 页面拖进CameraView绑好CaptureCommand编译运行——结果 iOS 上白屏、Android 上 Permission Denied、UWP 根本没反应。这不是你代码写错了而是你把CameraView当成了 WinForms 里的 PictureBox它不渲染画面不管理权限不处理后台挂起甚至不保证预览帧率稳定。这个示例项目真正价值是把 Xamarin.Forms 中最脆弱的一环——设备相机——拆成可调试、可拦截、可降级的模块它用MediaPicker.Default.CapturePhotoAsync()做兜底用CameraView做实时预览用INotifyPropertyChanged暴露对焦状态用DependencyService注入平台专属的闪光灯控制。适合正在维护老 Xamarin.Forms 项目、需要快速上线扫码/证件照/AR 贴纸功能的 C# 工程师也适合刚从 .NET MAUI 迁移回来、发现旧项目里CameraView行为和文档对不上的开发者。它不教你怎么写 MVVM但每行代码都在告诉你Xamarin.Forms 的相机是三套原生 SDK 在背后打架你写的 C# 只是裁判哨声。2. CameraView 的底层逻辑为什么必须用xamarin.essentialsxamarin.forms双栈协同而不是只靠MediaPicker2.1 CameraView 不是控件是平台能力的“翻译器”它的源码里藏着三套原生实现CameraView是 Xamarin.Forms 社区贡献的第三方控件非官方Microsoft.Maui.Controls.CameraView其核心逻辑在Xamarin.CommunityToolkit中。它本身不直接调用 Android 的Camera2 API或 iOS 的AVCaptureSession而是通过Custom Renderer机制在各平台创建对应原生视图Android继承ViewGroup内部创建TextureViewCameraCaptureSession监听onSurfaceTextureAvailable后启动预览流iOS继承UIView内部封装AVCaptureVideoPreviewLayer通过AVCaptureDeviceInput绑定摄像头UWP使用MediaCapture类依赖CaptureElementXAML 元素。这意味着CameraView的IsVisible属性变更会触发三套完全不同的生命周期回调。你在 ViewModel 里IsCameraVisible trueAndroid 端可能刚初始化TextureView就被 GC 回收iOS 端可能因AVCaptureSession未 start 就收到LayoutUpdated导致预览黑屏。项目示例中MainPage.xaml.cs第 47 行强制调用cameraView.ForceLayout()就是为绕过 Xamarin.Forms 渲染器的异步布局队列——这是血泪经验不手动触发iOS 首次加载 30% 概率黑屏。2.2 MediaPicker 是“后悔药”但只能救拍照不能救预览它的适用边界必须划清MediaPicker.Default.CapturePhotoAsync()是 Xamarin.Essentials 提供的跨平台拍照 API它本质是调用各平台原生相册/相机 AppAndroid 调Intent.ACTION_IMAGE_CAPTUREiOS 调UIImagePickerController。它解决的是「拍一张图存本地」但无法提供实时预览、无法控制对焦区域、无法设置曝光补偿、无法获取原始 YUV 数据。示例项目中TakePhotoCommand同时支持两种路径// MainPageViewModel.cs 第 89 行 private async Task TakePhotoAsync() { if (UseCameraView) // 走 CameraView 实时流 { var photo await cameraView.CaptureAsync(); // 返回 Stream需手动转 BitmapImage PhotoSource ImageSource.FromStream(() photo.AsStream()); } else // 走 MediaPicker 兜底 { var result await MediaPicker.CapturePhotoAsync(); if (result ! null) { PhotoSource ImageSource.FromFile(result.FullPath); // 直接读文件路径 } } }关键区别在于返回值CameraView.CaptureAsync()返回TaskMediaFile含AsStream()方法而MediaPicker.CapturePhotoAsync()返回TaskPhotoResult含FullPath字符串。前者适合做实时滤镜处理如灰度化后立即显示后者适合纯拍照存档。我一般会在生产环境默认启用MediaPicker仅在检测到CameraView.IsPreviewing true且cameraView.CameraState CameraState.Running时才切回CameraView——避免用户在低端 Android 设备上因CameraView初始化失败导致整个页面卡死。2.3 权限链不是“申请一次就完事”Android 的CAMERA和READ_EXTERNAL_STORAGE必须分阶段请求Xamarin.Forms 的权限模型是“声明式 运行时双重校验”。AndroidManifest.xml中声明uses-permission android:nameandroid.permission.CAMERA /仅是第一步。真正的坑在运行时Android 6.0API 23CAMERA权限属于危险权限组必须在Activity.OnResume()中调用ActivityCompat.RequestPermissions()且需监听OnRequestPermissionsResult回调Android 10API 29READ_EXTERNAL_STORAGE权限被废弃改用Scoped StorageMediaPicker保存照片时自动使用MediaStore但CameraView.CaptureAsync()返回的MediaFile流仍需写入Application.Context.CacheDiriOS 14Info.plist必须添加NSCameraUsageDescription且首次调用AVCaptureSession.StartRunning()时系统弹窗若用户拒绝后续所有CameraView操作均静默失败无异常抛出。示例项目中PermissionsHelper.cs第 23 行做了分阶段检查// PermissionsHelper.cs public static async Taskbool EnsureCameraPermissionAsync() { var status await Permissions.CheckStatusAsyncPermissions.Camera(); if (status PermissionStatus.Granted) return true; if (status PermissionStatus.Denied DeviceInfo.Platform DevicePlatform.Android) { // Android 需二次确认用户曾点击“不再询问” status await Permissions.RequestAsyncPermissions.Camera(); return status PermissionStatus.Granted; } // iOS 拒绝后无法再次弹窗只能跳转设置页 if (DeviceInfo.Platform DevicePlatform.iOS status PermissionStatus.Denied) { await Launcher.OpenAsync(new Uri(app-settings:)); return false; } return false; }注意Permissions.RequestAsyncT()在 iOS 上只会弹一次窗之后再调用直接返回Denied。所以示例中MainPage.xaml.cs第 62 行加了if (!await PermissionsHelper.EnsureCameraPermissionAsync()) return;——这是硬性守门员没过就别碰CameraView。3. CameraView 的四大避坑指南从黑屏、闪退到对焦失效每一条都是线上事故复盘3.1 现象iOS 首次启动CameraView黑屏但IsPreviewing为true原因AVCaptureSession已启动但AVCaptureVideoPreviewLayer的frame未正确设置或UIView.Layer.ContentsGravity未设为kCAGravityResizeAspectFill导致视频帧被裁剪为 0×0。解决在 iOS 自定义渲染器CameraViewRenderer.cs中重写OnElementPropertyChanged监听IsVisibleProperty变更后强制刷新 layer frame// iOS CameraViewRenderer.cs protected override void OnElementPropertyChanged(object sender, PropertyChangedEventArgs e) { base.OnElementPropertyChanged(sender, e); if (e.PropertyName VisualElement.IsVisibleProperty.PropertyName Element.IsVisible) { // 强制重置 previewLayer frame if (previewLayer ! null) { previewLayer.Frame Control.Bounds; previewLayer.ContentsGravity CALayer.GravityResizeAspectFill; } } }3.2 现象Android 8.0 设备上CameraView预览卡顿CPU 占用 95%原因CameraView默认使用TextureView其SurfaceTexture在低内存设备上频繁 GC且TextureView.SurfaceTextureListener.OnSurfaceTextureAvailable回调未做防抖导致CameraCaptureSession被反复重建。解决在 Android 渲染器CameraViewRenderer.cs中禁用TextureView改用SurfaceView需重写OnElementChanged// Android CameraViewRenderer.cs protected override void OnElementChanged(ElementChangedEventArgsCameraView e) { base.OnElementChanged(e); if (Control null) { // 替换为 SurfaceView var surfaceView new SurfaceView(Context); surfaceView.LayoutParameters new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MatchParent, ViewGroup.LayoutParams.MatchParent); SetNativeControl(surfaceView); } }提示SurfaceView不支持Opacity动画若你的 UI 有透明度渐变需求必须改用TextureView并在OnSurfaceTextureAvailable中加Interlocked.CompareExchange(ref isInitializing, 1, 0) 0防重入。3.3 现象CameraView.CaptureAsync()返回空流MediaFile的AsStream()抛ObjectDisposedException原因CameraView内部MediaFile对象在CaptureAsync()完成后被立即释放但AsStream()是延迟执行的FuncStream当 ViewModel 尝试.AsStream().Result时对象已销毁。解决必须用await获取流并立即复制到内存流// 正确写法MainPageViewModel.cs 第 95 行 var mediaFile await cameraView.CaptureAsync(); using var stream mediaFile.AsStream(); var memoryStream new MemoryStream(); await stream.CopyToAsync(memoryStream); memoryStream.Position 0; PhotoSource ImageSource.FromStream(() memoryStream);3.4 现象切换前后摄像头时iOS 上AVCaptureDeviceInput切换失败报AVErrorNotAuthorized原因iOS 的AVCaptureDevice.DiscoverySession默认只扫描当前授权的摄像头类型若用户只授权了后置摄像头切换前置时AVCaptureDevice.Default返回null。解决在 iOS 渲染器中预加载所有可用设备并缓存设备列表// iOS CameraViewRenderer.cs private ListAVCaptureDevice _availableDevices; private async Task LoadAvailableDevicesAsync() { _availableDevices new ListAVCaptureDevice(); var discoverySession new AVCaptureDeviceDiscoverySession( deviceTypes: new[] { AVMediaType.Video }, mediaType: AVMediaType.Video, position: AVCaptureDevicePosition.Unspecified); // 关键Unspecified 才能扫到所有设备 if (discoverySession?.Devices?.Length 0) { foreach (var device in discoverySession.Devices) { if (device.HasMediaType(AVMediaType.Video)) _availableDevices.Add(device); } } }4. CameraView 参数深度解析从CameraOptions到FlashMode每个属性背后的原生映射4.1CameraOptions不是配置项是平台能力开关表PreferredAspect如何影响预览分辨率CameraView.CameraOptions.PreferredAspect设置的是预览画面的宽高比如Aspect.Ratio4x3但它不直接控制传感器输出分辨率而是告诉AVCaptureSession.Preset或CameraCharacteristics.SENSOR_INFO_ACTIVE_ARRAY_SIZE选择哪个预设档位PreferredAspectiOSAVCaptureSession.PresetAndroidCameraCharacteristics输出尺寸档位实际效果Ratio4x3AVCaptureSessionPresetPhotoSENSOR_INFO_PIXEL_ARRAY_SIZE中 4:3 档位高像素但帧率低30fpsRatio16x9AVCaptureSessionPresetHighSENSOR_INFO_PIXEL_ARRAY_SIZE中 16:9 档位低像素但帧率高60fpsRatioFullAVCaptureSessionPresetInputPrioritySENSOR_INFO_PIXEL_ARRAY_SIZE最大尺寸可能触发硬件缩放画质下降示例项目中MainPage.xaml第 32 行设为Ratio16x9是为了在低端 Android 设备上优先保帧率。但要注意Ratio16x9在 iPhone SE第一代上会强制使用AVCaptureSessionPresetMedium1280×720而非High1920×1080——这是 Apple 的硬件限制代码无法绕过。4.2FlashMode的三态陷阱Auto在暗光环境下可能永远不闪On在 iOS 上需手动AVCaptureDevice.SetTorchModeOnLevel()CameraView.FlashMode映射关系如下FlashModeiOS 原生调用Android 原生调用注意事项Offdevice.TorchMode AVCaptureTorchMode.Offparameters.FlashMode FlashMode.Off安全Ondevice.SetTorchModeOnLevel(1.0f, out error)parameters.FlashMode FlashMode.OniOS 必须先LockForConfiguration()否则静默失败Autodevice.AutoFocusSystem AVCaptureAutoFocusSystem.Continuousparameters.FocusMode FocusMode.AutoAndroid 上 Auto 仅对焦不闪灯iOS 上 Auto 仅在AVCaptureMetadataOutput检测到低光时才触发示例项目中ToggleFlashCommand第 121 行做了 iOS 特判// MainPageViewModel.cs private async Task ToggleFlashAsync() { if (DeviceInfo.Platform DevicePlatform.iOS) { var device AVCaptureDevice.DefaultDeviceWithMediaType(AVMediaTypes.Video); if (device.HasTorch) { try { device.LockForConfiguration(out NSError error); if (error null) { device.TorchMode FlashMode FlashMode.On ? AVCaptureTorchMode.On : AVCaptureTorchMode.Off; } device.UnlockForConfiguration(); } catch { /* 忽略锁失败 */ } } } else { // Android 直接设参数 CameraView.FlashMode CameraView.FlashMode FlashMode.On ? FlashMode.Off : FlashMode.On; } }4.3FocusMode的平台差异Continuous在 Android 上等同于Auto但在 iOS 上是独立模式CameraView.FocusMode的行为差异极大iOSContinuous启用AVCaptureAutoFocusSystem.Continuous镜头持续微调Auto仅在CapturePhotoAsync()前单次对焦AndroidContinuous和Auto均映射到Camera.Parameters.FOCUS_MODE_CONTINUOUS_VIDEO无区别坑点Continuous在低端 Android 设备上会导致Camera.Parameters设置失败setParameters failed必须降级为Auto。示例项目中FocusMode切换逻辑在MainPage.xaml.cs第 105 行// 根据设备型号动态降级 if (DeviceInfo.Platform DevicePlatform.Android DeviceInfo.Model.Contains(Redmi) || DeviceInfo.Model.Contains(Galaxy)) { cameraView.FocusMode FocusMode.Auto; // 避免 Redmi Note 8 的 Continuous 闪退 } else { cameraView.FocusMode FocusMode.Continuous; }5. 实战验证用三步法确认你的 CameraView 是否真正可用而不是“看起来能跑”5.1 第一步用CameraView.IsPreviewingCameraView.CameraState双状态校验预览是否真实启动CameraView.IsPreviewing是 UI 层属性可能因布局未完成而误报trueCameraView.CameraState是底层状态机枚举Stopped/Starting/Running/Stopping。必须同时满足IsPreviewing true CameraState CameraState.Running才代表预览流已就绪。示例项目中StartPreviewCommand的执行体// MainPageViewModel.cs 第 73 行 private async Task StartPreviewAsync() { if (cameraView null) return; // 等待 CameraState 变为 Running while (cameraView.CameraState ! CameraState.Running) { await Task.Delay(50); if (cameraView.CameraState CameraState.Stopped || cameraView.CameraState CameraState.Stopping) { throw new InvalidOperationException(Camera failed to start); } } // 再检查 IsPreviewing if (!cameraView.IsPreviewing) { // 强制刷新 cameraView.ForceLayout(); await Task.Delay(100); } }5.2 第二步用MediaPicker.CapturePhotoAsync()的PhotoResult元数据反向验证权限与存储路径MediaPicker.CapturePhotoAsync()成功返回的PhotoResult包含DateTaken、Width、Height、Orientation四个关键字段。若Width 0或DateTaken DateTime.MinValue说明照片未真正写入磁盘——常见于 Android 10 的Scoped Storage权限未正确申请或MediaStore插入失败。示例项目中ValidatePhotoResult方法// Utilities.cs 第 42 行 public static bool ValidatePhotoResult(PhotoResult result) { if (result null) return false; if (result.Width 0 || result.Height 0) return false; if (result.DateTaken DateTime.MinValue) return false; // 验证文件是否存在Android 10 可能返回 content:// URI if (result.FullPath.StartsWith(content://)) { return true; // content URI 无需文件存在 } return File.Exists(result.FullPath); }5.3 第三步用CameraView.CaptureAsync()的MediaFile的FilePath字段判断是否走原生捕获路径CameraView.CaptureAsync()返回的MediaFile对象其FilePath属性在不同平台含义不同平台FilePath值含义验证方式Android/data/data/{package}/cache/camera.jpg原生捕获写入应用私有目录File.Exists(mediaFile.FilePath)应为trueiOSnull原生捕获数据在内存流中mediaFile.AsStream()必须可读取UWPms-appdata:///temp/camera.jpg原生捕获写入临时目录StorageFile.GetFileFromApplicationUriAsync(new Uri(mediaFile.FilePath))示例项目中CaptureAndValidateAsync方法// MainPageViewModel.cs 第 135 行 private async Taskbool CaptureAndValidateAsync() { try { var mediaFile await cameraView.CaptureAsync(); if (DeviceInfo.Platform DevicePlatform.Android) { return !string.IsNullOrEmpty(mediaFile.FilePath) File.Exists(mediaFile.FilePath); } else if (DeviceInfo.Platform DevicePlatform.iOS) { using var stream mediaFile.AsStream(); return stream.Length 0; // iOS 流长度 0 即有效 } return true; } catch (Exception ex) { Debug.WriteLine($Capture failed: {ex.Message}); return false; } }6. 我的硬核调试习惯每次集成 CameraView 前强制走一遍「三秒断点法」省掉 80% 的线上排查时间6.1 断点一CameraViewRenderer.OnElementChanged()入口确认Control是否为null这是最基础的守门点。如果Control为null说明自定义渲染器未注册或AssemblyInfo.cs中漏了[assembly: ExportRenderer(typeof(CameraView), typeof(CameraViewRenderer))]。我在Android和iOS项目的AssemblyInfo.cs里永远把这行代码放在最顶部用#region CAMERA_RENDERER包裹避免被其他ExportRenderer冲突。一旦断点停在这里且Control null立刻检查MainActivity.cs的LoadApplication(new App())是否在base.OnCreate(savedInstanceState)之后调用——这是 Xamarin.Forms 6.0 的硬性要求早于base.OnCreate会导致渲染器加载失败。6.2 断点二CameraView.CaptureAsync()的TaskCompletionSource内部看SetResult()是否被调用CameraView.CaptureAsync()底层用TaskCompletionSourceT封装原生回调。我在Xamarin.CommunityToolkit源码里打了两个断点一个在Android渲染器CaptureAsync()方法开头一个在OnImageAvailable回调里tcs.SetResult(mediaFile)之前。如果第一个断点命中但第二个不命说明ImageReader的OnImageAvailable根本没触发——大概率是Surface创建失败或ImageReader未正确绑定到CaptureRequest.Builder。这时我会立刻去查AndroidManifest.xml是否漏了uses-feature android:nameandroid.hardware.camera.any /因为没有这个声明某些厂商 ROM如 Huawei EMUI会直接禁用Camera2 API。6.3 断点三PermissionsHelper.EnsureCameraPermissionAsync()的Permissions.RequestAsyncT()返回前看PermissionStatus实际值这是最隐蔽的坑。Permissions.RequestAsyncT()在 iOS 上返回PermissionStatus.Unknown时不代表权限未申请而是系统尚未弹窗比如用户刚从设置页返回。我强制在EnsureCameraPermissionAsync()里加日志Debug.WriteLine($Permission status before request: {status}); var newStatus await Permissions.RequestAsyncPermissions.Camera(); Debug.WriteLine($Permission status after request: {newStatus});如果before是Unknown而after还是Unknown说明UIApplication.SharedApplication.ApplicationIconBadgeNumber被设为 0iOS 14 的隐私限制必须让用户手动打开「设置 隐私与安全性 相机」。这种问题在线上无法捕获只能靠本地断点提前暴露。从那以后我每次集成CameraView都强制走一遍这「三秒断点法」第一秒看渲染器是否加载第二秒看原生捕获是否触发第三秒看权限状态是否真实更新。三个断点全过才敢提交 PR。不是怕代码错是怕下次凌晨三点被 Ops 电话叫醒说「用户拍不了照APP 直接退出」——而你翻日志发现只是AndroidManifest.xml少了一行uses-feature。希望帮到你。本文还有配套的精品资源点击获取