拍摄
HAC 中拍照、录像、录音、水印和本地文件能力的页面流程。
适用场景
拍摄能力用于在 HAC 中调用摄像头、麦克风和本地文件能力，完成现场照片、视频、音频采集，并把文件路径返回给活字格页面。
适合巡检拍照、入库验收、质量缺陷、现场施工、售后取证等需要“现场留痕”的业务。
使用前提
- 应用运行在
HAC中； - 已安装 PDA / Android 交互命令插件；
- 已授权相机、麦克风和本地文件访问权限；
- 设备有可用存储空间；
- 页面已定义拍摄成功、取消、权限不足、文件过大和上传失败时的处理方式。
拍摄类命令通常返回本地文件 Uri，不是文件内容。需要展示或上传时，再用【读取本地文件】转换为 Object Url。
命令速查
| 命令 | 返回结果 | 用途 |
|---|---|---|
| 【拍摄照片】 | 照片 Uri | 调用相机拍照 |
| 【拍摄视频】 | 视频 Uri | 调用相机录像 |
| 【为照片添加水印】 | 水印照片 Uri | 给照片叠加业务水印 |
| 【录制音频】 | mp3 文件 Uri | 录制现场音频 |
| 【读取本地文件】 | Object Url | 读取文件内容用于展示或上传 |
图片中的配置用于说明命令之间的调用关系。拍照、录像和录音命令先返回本地文件 Uri，需要在页面中预览或上传时，再调用【读取本地文件】转换为 Object Url。
命令结果说明
| 命令 | 成功时的结果 | 页面处理 | 失败或取消时的处理 |
|---|---|---|---|
| 【拍摄照片】 | 照片 Uri | 保存 Uri，按需加水印，再读取为 Object Url | 保留当前页面状态，提示重拍或取消 |
| 【拍摄视频】 | 视频 Uri | 保存 Uri，按需读取或上传 | 提示重录或取消，不自动提交 |
| 【为照片添加水印】 | 水印照片 Uri | 用新的 Uri 替换预览或上传文件 | 保留原照片，允许重新加水印 |
| 【录制音频】 | 音频文件 Uri | 保存 Uri，按需读取或上传 | 提示重录或取消，不自动提交 |
| 【读取本地文件】 | Object Url | 写入图片、文件或上传控件 | 保留原 Uri，提示重新读取或重新拍摄 |
上表中的具体返回字段名称、字段类型、取消时的返回值和空值规则，应以当前插件版本的实际结果为准。请在发布前补充一组成功、取消和失败结果示例。
推荐流程
拍照并预览 Demo
可以先用一张照片验证从拍摄到页面显示的完整链路：
- 在任务页面放置“拍照”按钮和图片预览区域，并让按钮靠近当前任务对象；
- 在按钮命令中选择【拍摄照片】；
- 成功后保存照片
Uri，失败或取消时保留页面原状态； - 如果业务需要水印，在成功分支中调用【为照片添加水印】；
- 调用【读取本地文件】，将照片
Uri转换为Object Url； - 将
Object Url写入图片单元格或预览控件； - 提供“重拍”和“确认”操作，确认后再进入上传或业务提交流程。
对应的页面关系可以按下面的方式填写。字段名称和目标单元格需要替换为项目实际配置：
| 数据 | 保存位置 | 用途 |
|---|---|---|
原始照片 Uri | [变量或单元格] | 水印、重新读取或离线暂存 |
水印照片 Uri | [变量或单元格] | 预览和上传 |
Object Url | [图片单元格或变量] | 页面预览或文件上传 |
| 上传状态 | [单元格或业务字段] | 区分待上传、上传中、已上传和失败 |
配置截图建议分别标出拍摄命令、成功分支、【读取本地文件】的文件路径和 Object Url 保存位置。
照片采集并上传：
进入任务页面
-> 点击“拍照”
-> 执行【拍摄照片】
-> 返回照片 Uri
-> 按需执行【为照片添加水印】
-> 执行【读取本地文件】
-> 图片单元格显示预览
-> 用户确认
-> 服务端保存文件和业务数据弱网场景：
拍摄完成
-> 保存文件 Uri、业务主键和采集状态
-> 页面显示“待上传”
-> 网络恢复后读取本地文件并上传
-> 上传成功后标记“已上传”设计要点
- 拍摄按钮靠近任务对象，避免用户不知道给谁拍；
- 拍摄后显示预览、重拍、确认，不要直接上传；
- 多张照片要显示已拍数量、每张状态和上传结果；
- 明确区分“已拍摄”“已读取”“上传中”“已上传”“上传失败”；
- 小尺寸照片优先用于普通现场记录；全尺寸只用于需要细节判定的场景；
- 水印应包含操作人、时间、任务编号、地点等可追溯信息，但不要遮挡关键缺陷；
- 视频和音频要限制时长，避免文件过大。
页面至少应区分以下状态，并根据状态控制按钮：
| 状态 | 页面提示 | 可执行操作 |
|---|---|---|
| 未拍摄 | 请拍摄现场资料 | 拍照、录像或录音 |
| 拍摄中 | 拍摄中 | 等待完成或取消 |
| 已拍摄待确认 | 显示预览 | 重拍、确认 |
| 读取中 | 正在准备预览或上传 | 暂时禁用重复读取 |
| 上传中 | 上传中 | 等待完成，避免重复提交 |
| 已上传 | 已上传 | 查看或继续业务 |
| 上传失败 | 显示失败原因 | 重试，必要时保留本地文件 |
用户取消拍摄后，按钮应恢复可用，页面已有内容应保留；重拍时应明确是覆盖当前文件还是新增一张。多张采集需要为每个文件保存业务主键、顺序和上传状态。
上传成功后是否删除本地临时文件、临时文件保留多久，以及应用重启后是否可以恢复待上传记录，需要根据项目的离线和数据留存方案确定。
异常处理
| 异常 | 常见原因 | 推荐处理 |
|---|---|---|
| 相机无法打开 | 权限不足、无摄像头、相机被占用 | 提示授权或重试 |
| 用户取消拍摄 | 主动返回或关闭相机 | 保留原状态，不自动提交 |
| 文件路径为空 | 未完成拍摄、传参错误 | 提示重新拍摄并记录返回值 |
| 读取本地文件失败 | Uri 无效、文件被清理、权限不足 | 重新拍摄或重新选择文件 |
| 文件过大 | 全尺寸照片、长视频、弱网 | 压缩、缩短录制时长或稍后上传 |
| 水印失败 | Uri 无效、水印参数为空、文件不可写 | 保留原照片，允许重新加水印 |
| 上传失败 | 网络异常、服务端限制、请求过大 | 保留本地状态并提供重试 |
权限被拒绝时，应说明需要开启的系统权限和恢复入口；相机、麦克风或文件权限恢复后，页面应允许用户回到当前任务继续操作。正式业务还应记录操作人、采集时间、任务编号、文件类型、文件大小、上传状态和失败原因。水印中的操作人、时间、任务编号和地点需要明确数据来源，避免页面展示值与业务记录不一致。