调用与资源
相机以全屏模态呈现。应用准备配置、打开相机并处理结果;取景、拍摄、预览和选择由库完成。
调用入口
useCamera() 返回 [camera, holder]。在稳定的组件树中渲染宿主,调用 camera.open(input, { signal }) 开始交互。宿主不会预先打开相机;缺少宿主时返回 failed / unavailable。
modes 决定模式顺序,首项是初始模式。initialFacing 与 initialFlash 在根级设置,默认分别是 back 与 auto。retention 决定模式切换时是否保留媒体。
生命周期
输入校验通过后,已经取消的信号直接返回 cancelled。有效新调用接替同一宿主旧调用,旧调用返回 cancelled;非法新输入不影响当前交互。每次调用使用自己的 AbortController,旧信号不会取消新交互。
真实宿主卸载取消所属调用。React effect 临时重放不自动取消;过期回调不覆盖新调用。一次结果最多交付一次,成功交付后不会被后续取消改写。
结果与失败
按 status 分支处理:success 读取 media;cancelled 结束本次流程;failed 读取 error.reason 和 error.message。完整失败原因见类型。
局部拍照、录像、麦克风或照片处理错误留在相机内,保留此前媒体。用户明确重试或取消;不自动重拍,也不交付不符合要求的原图。
水印与文件
水印由 watermark.lines 提供,只写入照片像素,不作用于视频。空数组不生成水印。它不提供防篡改证明。
成功结果仍指向临时文件,success 只表示用户选用了媒体。消费者负责文件保存、上传与释放;库只清理尚未交付且属于本轮的文件。id 是媒体展示标识,不是业务照片 ID。
相机窗口全屏覆盖,关闭后恢复原页面。取景状态栏跟随实际相机窗口,不要求业务页面逐个补偿。
控件呈现
取景控件、模式切换、预览中的普通操作和局部提示使用 Design 的系统 regular 玻璃表面,并固定深色外观以保持浅色文字的可读性。普通表面不额外叠加黑色染色,材质呈现交由系统根据背后内容处理。不支持原生玻璃或系统开启“减少透明度”时,使用深色实色表面;应用无需另行判断平台。
保存、删除和快门保留各自的状态颜色;浮动错误提示使用红色告警图标与边线,正文保持清晰。按压或淡入只改变前景透明度,材质及其父视图保持不透明。材质不改变禁用、模式选择、确认或媒体交付行为,也不进入拍摄成片。
预览删除使用玻璃按钮。首次点击在原位显示红色“确认删除”,再次点击才删除当前文件。点击其它位置、开始滑动、切换图片或媒体分类、返回和退出预览会取消确认;轮播仍在移动时不能删除。模式切换时整批丢弃媒体的确认仍使用原有相机内确认流程。