更新记录

1.0.0（2026-01-28） 下载此版本

v1.0.0（首发）

1. 支持相机拍照、相册选择、微信导入图片
2. 支持单张/多张拍摄模式切换（自定义最大数量）
3. 附带首次进入分步引导、相机网格参考线
4. 适配微信小程序、App、H5

平台兼容性

拍照页面使用文档

页面介绍

pages/index/index.vue 是一个用于拍摄和选择照片的页面组件，支持单张/多张拍摄模式切换、相机拍照、相册选择、微信导入图片以及图片预览功能。

功能特性

• ✅ 单张/多张拍摄模式切换
• ✅ 相机拍照功能
• ✅ 相册选择图片
• ✅ 微信导入图片
• ✅ 图片预览功能
• ✅ 首次进入引导步骤
• ✅ 分步操作指引
• ✅ 相机网格参考线
• ✅ 拍摄边框辅助

参数说明

页面接收以下参数：

使用方法

1. 导航到拍照页面

uni.navigateTo({
  url: '/pages/index/index?Quantity=5' // 设置最多拍摄5张照片
});

2. 拍摄或选择照片

• 拍照：点击底部中央的拍照按钮
• 从相册选择：点击左下角的"相册上传"按钮
• 从微信导入：点击右下角的"微信导入"按钮
• 切换拍摄模式：点击拍摄区域底部的"拍单张"或"拍多张"按钮

3. 预览照片

点击左上角的"预览"按钮，可以查看已拍摄或选择的照片。

4. 完成拍摄

在多张拍摄模式下，当拍摄了至少一张照片后，右下角的按钮会变为"完成"按钮，点击即可完成拍摄并返回上一页。

回调事件

页面完成拍摄后，会通过 uni.$emit 触发 OnSite 事件，传递拍摄的图片列表：

// 监听拍摄完成事件
uni.$on('OnSite', (imageList) => {
  console.log('拍摄完成，图片列表：', imageList);
  // 处理拍摄的图片
});

数据结构

1. 图片路径格式

• 单张模式：返回包含单个图片路径的数组 [imagePath]
• 多张模式：返回包含多个图片路径的数组 [imagePath1, imagePath2, ...]

2. 示例返回数据

// 单张模式返回
['/storage/emulated/0/Android/data/io.dcloud.HBuilder/apps/HBuilder/doc/uniapp_temp_1634567890123/cache/1634567890123.jpg']

// 多张模式返回
[
  '/storage/emulated/0/Android/data/io.dcloud.HBuilder/apps/HBuilder/doc/uniapp_temp_1634567890123/cache/1634567890123.jpg',
  '/storage/emulated/0/Android/data/io.dcloud.HBuilder/apps/HBuilder/doc/uniapp_temp_1634567890456/cache/1634567890456.jpg'
]

权限说明

使用本页面需要以下权限：

• 相机权限：用于拍照功能
• 相册权限：用于从相册选择图片
• 微信权限：用于从微信导入图片（可选）

错误处理

1. 微信导入权限错误：当微信导入权限未配置时，会提示用户并询问是否切换到相册选择
2. 权限拒绝：当用户拒绝权限时，会给出相应提示
3. 达到最大拍摄数量：当在多张模式下达到最大拍摄数量时，会提示用户

指引功能

首次进入引导

首次进入页面时，系统会自动显示分步引导，帮助用户了解页面功能：

1. 第一步：引导用户使用"相册上传"功能
2. 第二步：引导用户切换"单张拍摄"和"多张拍摄"模式
3. 第三步：引导用户使用"完成"按钮上传材料

指引触发条件

• 首次进入页面时自动触发
• 页面会通过本地存储记录用户是否已经看过指引
• 点击指引中的"我知道"按钮后，指引会被关闭并标记为已完成

指引内容

注意事项

1. 本页面使用本地图片路径，无需上传到后端服务器
2. 拍摄完成后会自动返回上一页，并通过事件传递图片列表
3. 页面会记住用户的拍摄模式设置（通过本地存储）
4. 首次进入页面会显示引导步骤，帮助用户了解功能
5. 指引功能仅在首次进入时显示，后续进入会直接显示拍摄界面

示例代码

完整使用示例

// 导航到拍照页面
uni.navigateTo({
  url: '/pages/index/index?Quantity=3' // 设置最多拍摄3张照片
});

// 监听拍摄完成事件
uni.$on('OnSite', (imageList) => {
  console.log('拍摄完成，图片列表：', imageList);

  // 处理拍摄的图片
  if (imageList && imageList.length > 0) {
    // 显示图片
    this.images = imageList;

    // 上传到服务器（如果需要）
    this.uploadImages(imageList);
  }
});

// 上传图片到服务器（示例）
uploadImages(imageList) {
  imageList.forEach((imagePath, index) => {
    uni.uploadFile({
      url: 'https://your-api.com/upload',
      filePath: imagePath,
      name: 'file',
      formData: {
        index: index
      },
      success: (res) => {
        console.log('上传成功：', res);
      },
      fail: (err) => {
        console.error('上传失败：', err);
      }
    });
  });
}

相机辅助功能

网格参考线

拍摄区域显示网格参考线，帮助用户更好地对齐拍摄对象：

• 垂直参考线：将拍摄区域分为三等分，位于左侧1/3和右侧2/3位置
• 水平参考线：将拍摄区域分为三等分，位于上方1/3和下方2/3位置
• 作用：帮助用户保持水平拍摄，对齐拍摄对象，遵循构图规则

拍摄边框

拍摄区域周围显示白色边框，明确指示拍摄范围：

• 边框样式：2px 白色实线边框
• 作用：清晰界定拍摄区域，帮助用户了解照片的最终范围

提示文字

拍摄区域中央显示提示文字，指导用户拍摄：

• 主标题："事故现场情况及周边环境"
• 副标题："请将材料完整置于拍摄框内并平行于参考线拍摄"

页面结构

• 顶部：预览按钮
• 中间：拍摄区域（包含相机预览、网格参考线、边框辅助、模式切换、提示文字）
• 底部：控制按钮（相册上传、拍照、完成/微信导入）
• 弹窗：图片预览弹窗（点击预览按钮显示）

技术实现

• 使用 uni.createCameraContext() 获取相机上下文
• 使用 uni.chooseImage() 选择相册图片
• 使用 uni.chooseMessageFile() 从微信导入图片
• 使用自定义组件 preview-modal 实现图片预览
• 使用本地存储 uni.getStorageSync() 记住用户设置
• 使用 CSS 实现网格参考线和边框辅助
• 使用 walkthrough 组件实现首次进入引导

版本历史