# ux-camera

**Repository Path**: glony/ux-camera

## Basic Information

- **Project Name**: ux-camera
- **Description**: ux-camera 跨平台相机组件
跨平台相机组件，支持拍照、图片裁剪、水印、闪光灯、手势缩放、点击对焦、横竖屏切换，兼容 H5 / APP / 小程序，Vue2 / Vue3 双版本支持。
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ux-camera 跨平台相机组件
# **[ux-camera 跨平台相机组件](https://ext.dcloud.net.cn/plugin?id=29556)** 

跨平台相机组件，支持拍照、图片裁剪、水印、闪光灯、手势缩放、点击对焦、横竖屏切换，兼容 H5 / APP / 小程序，Vue2 / Vue3 双版本支持。

## 依赖
无



![输入图片说明](https://img-cdn-tx.dcloud.net.cn/stream/plugin_screens/ux-camera_0.jpg/webp?&v=1788596626)
![输入图片说明](https://img-cdn-tx.dcloud.net.cn/stream/plugin_screens/ux-camera_1.png/webp?&v=1788596626)
![输入图片说明](https://img-cdn-tx.dcloud.net.cn/stream/plugin_screens/ux-camera_2.jpg/webp?&v=1788596626)
![输入图片说明](https://img-cdn-tx.dcloud.net.cn/stream/plugin_screens/ux-camera_3.jpg/webp?&v=1788596626)

## 平台兼容性

| 平台 | 支持 | 实现方式 |
|------|------|----------|
| H5 (Chrome) | ✅ | getUserMedia + Canvas |
| H5 (Safari iOS) | ✅ | getUserMedia（闪光灯不支持） |
| APP (Android) | ✅ | live-pusher |
| APP (iOS) | ✅ | live-pusher |
| 微信小程序 | ✅ | camera 组件 |
| 支付宝/百度/头条/QQ 小程序 | ✅ | camera 组件 |
| Vue 2 | ✅ | 条件编译兼容 |
| Vue 3 | ✅ | 条件编译兼容 |

## 功能特性

- **拍照**：支持前置/后置摄像头切换，JPEG/PNG 导出
- **图片裁剪**：矩形/圆角矩形/圆形裁剪框，自定义比例，手势拖拽缩放
- **水印**：实时时间水印、自定义文字/图片水印
- **闪光灯**：torch 常亮模式（Android Chrome / 小程序支持，iOS Safari ）
- **手势缩放**：双指 pinch-to-zoom，硬件缩放优先，CSS 缩放
- **点击对焦**：单指点击触发对焦动画，H5 端支持手动指定对焦位置
- **横竖屏切换**：自动检测屏幕旋转，UI 等比缩放适配横屏
- **加载提示**：相机启动时显示 loading 动画，支持自定义颜色/尺寸/文字
- **相册选图**：从系统相册选择图片（可进入裁剪流程）
- **内存管理**：Object URL 自动释放，避免内存泄漏

## 快速使用

```html
<template>
  <ux-camera
    title="拍照"
    facing="environment"
    :enable-zoom="true"
    :enable-autofocus="true"
    :enable-orientation="true"
    @ready="onReady"
    @photo="onPhoto"
    @error="onError"
    @back="onBack"
  />
</template>

<script>
import UxCamera from '@/uni_modules/ux-camera/components/ux-camera/ux-camera.vue'
//#ifdef APP-PLUS
import UxCamera from '@/uni_modules/ux-camera/components/ux-camera/ux-camera.nvue'
// #endif
export default {
  components: { UxCamera },
  methods: {
    onReady(e) { console.log('相机就绪', e) },
    onPhoto(result) {
      // result.tempFilePath  图片路径
      // result.width / result.height  图片尺寸
      // result.blob  Blob 对象（H5 端，可用于上传）
    },
    onError(msg) { uni.showToast({ title: msg, icon: 'none' }) },
    onBack() { uni.navigateBack() },
  },
}
</script>
```


## Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| title | String | `'拍照'` | 顶部标题 |
| hintText | String | `''` | 底部提示文字 |
| facing | String | `'environment'` | 摄像头方向：`'environment'` 后置 / `'user'` 前置 |
| resolution | String | `'high'` | 分辨率：`'low'` / `'medium'` / `'high'` |
| watermark | Object | `null` | 水印配置 |
| watermarkEnabled | Boolean | `false` | 是否启用水印 |
| enableCrop | Boolean | `false` | 是否开启拍照后裁剪 |
| cropConfig | Object | `{}` | 裁剪配置（透传给裁剪组件） |
| enableZoom | Boolean | `true` | 是否启用手势缩放 |
| enableAutofocus | Boolean | `true` | 是否启用点击对焦 |
| zoomRange | Array | `[1, 4]` | 缩放范围 `[min, max]` |
| enableOrientation | Boolean | `true` | 是否启用横竖屏切换 |
| loadingStyle | Object | `{}` | 加载层样式配置 |

### cropConfig 配置项

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| cropShape | String | `'rect'` | 裁剪框形状：`'rect'` / `'round-rect'` / `'circle'` |
| aspectRatio | Number | `0` | 宽高比：`0` 自由 / `1` 正方 / `1.585` 身份证 / `4/3` / `16/9` |
| cropWidth | Number | `0` | 固定裁剪框宽（优先级高于 aspectRatio） |
| cropHeight | Number | `0` | 固定裁剪框高 |
| minCropWidth | Number | `100` | 最小裁剪框宽 |
| minCropHeight | Number | `100` | 最小裁剪框高 |
| roundRadius | Number | `0` | round-rect 圆角半径 |
| minScale | Number | `0.5` | 图片最小缩放倍数 |
| maxScale | Number | `5` | 图片最大缩放倍数 |
| maskColor | String | `'rgba(0,0,0,0.6)'` | 遮罩颜色 |
| quality | Number | `0.92` | JPEG 压缩质量 0~1 |
| fileType | String | `'jpg'` | 导出格式：`'jpg'` / `'png'` |
| exportOriginalResolution | Boolean | `false` | 是否按原图像素导出 |
| canResizeFrame | Boolean | `true` | 是否允许调整裁剪框大小 |

### loadingStyle 配置项

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| loadingColor | String | `'#3be8a5'` | spinner 颜色 |
| loadingSize | Number | `80` | spinner 尺寸（rpx） |
| loadingText | String | `'正在启动相机...'` | 提示文字 |
| loadingTextColor | String | `'rgba(255,255,255,0.7)'` | 文字颜色 |
| loadingBg | String | `'rgba(0,0,0,0.85)'` | 遮罩背景色 |

## Events

| 事件名 | 参数 | 说明 |
|--------|------|------|
| ready | `{ width, height }` | 相机就绪 |
| photo | `{ tempFilePath, width, height, blob?, hasWatermark }` | 拍照完成（或裁剪完成） |
| error | `String` | 错误信息 |
| back | - | 点击返回按钮 |
| flash-change | `'torch'` / `'off'` | 闪光灯状态变化 |
| switch-camera | `'environment'` / `'user'` | 摄像头切换 |
| orientation-change | `{ orientation, isLandscape, screenWidth, screenHeight }` | 屏幕方向变化 |

## Slots

| 插槽名 | 说明 |
|--------|------|
| default | 取景框覆盖层（身份证框、银行卡框等） |
| hint | 底部提示区域自定义内容 |

## 组件方法（通过 ref 调用）

| 方法 | 说明 |
|------|------|
| openCamera() | 打开相机 |
| closeCamera() | 关闭相机 |
| takePhoto() | 拍照 |
| toggleFlash() | 切换闪光灯 |

## 目录结构

```
uni_modules/ux-camera/
├── components/ux-camera/
│   ├── ux-camera.vue           # 入口组件
│   ├── camera/
│   │   ├── ux-camera-h5.vue    # H5 平台实现
│   │   ├── ux-camera-mp.vue    # 小程序平台实现
│   │   └── ux-camera-app.vue   # APP 平台实现
│   ├── crop/
│   │   ├── ux-image-cropper.vue # 图片裁剪组件
│   │   └── crop-config.js       # 裁剪配置常量
│   ├── ux-popup/
│   │   ├── ux-popup.vue 				 # 弹窗组件
│   ├── ux-svg-icon/
│   │   ├── ux-svg-icon.vue 		 # svg icon 组件
│   └── utils/
│       └── index.js             # H5 工具方法（压缩、Base64、ObjectURL）
├── package.json
├── changelog.md
└── readme.md
```

## 隐私声明

- 组件运行时需请求摄像头权限
- 拍摄的照片数据仅在本地处理，不上传任何服务器
- 不收集、不存储、不传输任何用户隐私数据