npm package: @luoxiao123/ng-cam
Description: 一款使用HTML5及以及 WebRTC/UserMedia实现，适用于angular框架的摄像头组件。
Author: luoxiao
Latest version: 11.0.4

# @luoxiao123/ng-cam [![npm version](https://badge.fury.io/js/%40luoxiao123%2Fng-cam.svg)](https://badge.fury.io/js/%40luoxiao123%2Fng-cam)

一款使用 HTML5 及以及 WebRTC/UserMedia 实现，适用于 angular 框架的摄像头组件。【该项目用于我的个人项目针对项目做的深度定制，待后续优化，其他人慎用】

**即插即用.** 该库包含一个模块，可以将其导入每个标准 Angular 9+项目中。

**简单实用** 组件为您提供完全控制，并允许您通过操作和事件绑定获取快照。

**轻量代码.** 小身材，也能大有可为。

## 特性

- 摄像头实时视图
- 拍照
- 兼容各种智能手机与现代操作系统 (系统必须支持 [WebRTC/UserMedia API](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices))
- 如果存在多个摄像头，则可以多个摄像头切换
- 智能手机上的纵向和横向模式
- 面向用户的摄像头的镜像实时视图-手机上的“自拍镜像”
- 为更好的后处理而捕获无损像素图像数据。
- 支持显示尺寸与实际像素分离，以便小容器中截取高分辨率图像
- 支持截图图像旋转

## 必要条件

### 运行时依赖

**提示:** 此项目运行在 `>= 3.7.0` 以及 Angular 9 中.

- Angular: `>=9.0.0`
- Typescript: `>=3.7.0`
- RxJs: `>=5.0.0`
- **重要:** 您的应用必须在安全的环境下使用 `https://` 或者在 localhost, 用于现代浏览器以允许 WebRTC / UserMedia 访问.

### 客户端

- [当前浏览器](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#Browser_compatibility) 必须支持 w/ HTML5 以及 WebRTC/UserMedia (Chrome >53, Safari >11, Firefox >38, Edge)
- 网络摄像头/摄像头
- 用户需要授权网页访问摄像机的权限

## 使用方法

1. 通过标准 npm 命令安装:

`npm install --save @luoxiao123/ng-cam`

2. 导入 `NgCamModule` 到你的 Angular module:

```typescript
import {NgCamModule} from '@luoxiao123/ng-cam';

@NgModule({
  imports: [
    NgCamModule,
    ...
  ],
  ...
})
export class AppModule { }
```

3. 在你的页面中使用 `NgCamComponent` :

`<ng-cam></ng-cam>`

一切就是真简单！

## 选项和事件

本节描述了组件的基本输入/输出。 所有输入输出都是可选的。

### 输入

- `trigger: Observable<void>`: 通过触发一个`Observable` 可观察对象进行拍摄快照. 当它发射时，图像将被捕获并发出事件（详见输出）.
- `width: number`: 摄像头实时取景拍照的视频宽度（单位为像素） 默认为 640。
- `height: number`: 摄像头实时取景拍照的视频高度（单位为像素） 默认为 480.
- `realWidth: number`: 定义摄像头区域的实际显示最大宽度（以像素为单位）.
- `realHeight: number`: 定义摄像头区域的实际显示最大高度（以像素为单位）.
- `videoOptions: MediaTrackConstraints`: 定义在请求视频流时的约束 ([MediaTrackConstraints](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints))。
- `mirrorImage: string | NgCamMirrorProperties`: 用于控制图像镜像的标志。 如果该属性不存在或为 `null` 并且摄像头声明 user-facing 面向用户, 则图像将被镜像 (x 轴) 以提供更好的用户体验（“自拍视图”）。 如果是字符串值 `"never"` 将阻止镜像, 而如果值为 `"always"` 则将镜像每一个摄像头视频流, 即使摄像头视频不是 user-facing 面向用户. 针对以后的扩展, `NgCamMirrorProperties` 对象也可以设置这些值.
- `allowCameraSwitch: boolean`: 启用/禁用摄像机切换图标。启用后，如果找到多个摄像头，将显示一个开关图标。
- `switchCamera: Observable<boolean|string>`: 可用于在可用的摄像机之间循环(true=下一个, false=上一个)切换, 或通过设备 ID deviceId （字符串）切换到特定设备.
- `captureImageData: boolean = false`: 用于在拍摄快照时启用/禁用无损像素 ImageData 对象的捕获的标志。 ImageData 将包含在发出的“WebCammage”对象 o 事件中。
- `imageType: string = 'image/jpeg'`: [图片类型](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL) 拍摄快照时截取图片文件类型. 默认为 'image/jpeg'.
- `imageQuality: number = 0.92`: [图片质量](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL) 拍摄快照时截取图片质量. 数值必须介于 0-1 之间. 默认为 0.92.
- `imageRotate: number = 0`: 图片质量旋转度 拍摄快照时，图片旋转角度建议值 0 、-90、90、180 默认为 0
- `imagePreview: number = 0`: 图片预览时间 拍摄快照时，快照图片覆盖视频部分一定时间进行图片预览 单位为秒 默认 0

### 输出

- `imageCapture: EventEmitter<NgCamImage>`:当拍摄快照时 (拍摄快照由 `[trigger]` 触发),就会通过该 `EventEmitter`发出图像. 图像数据以纯 Base64 字符串和 data-url 的形式包含在 `NgCamImage` 数据结构中.
- `imageClick: EventEmitter<void>`: 当点击摄像头视频区域时，就会通过该 `EventEmitter` 发出事件.
- `initError: EventEmitter<NgCamInitError>`: 当摄像头初始化出错时，就会通过该 `EventEmitter` 发出事件.
- `capErrors: EventEmitter<CaptureImageError>`: 当拍摄快照出错时，就会通过该 `EventEmitter` 发出事件.
- `cameraSwitched: EventEmitter<NgCamSwitched>`: 切换到视频设备后，发出活动设备 ID deviceId 和 video视频流 。

## 你应该知道的：

### 如何确定用户是否拒绝相机访问

当相机初始化由于某种原因而失败时，该组件会通过 `initError` 发出 `NgCamInitError` 事件. 如果由浏览器提供，则此对象包含字段 `mediaStreamError: MediaStreamError` ，其中包含有关 UserMedia 初始化失败的原因的信息。 根据 [Mozilla API docs](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia), 该对象包含一个 `name` 属性，该属性可提供有关原因的见解。

> 如果用户拒绝许可，或者匹配的媒体不可用，则分别通过 NotAllowedError 或 NotFoundError rejected promise。.

确定用户是否拒绝权限:

```
  <ng-cam (initError)="handleInitError($event)"></ng-cam>
```

```
  public handleInitError(error: NgCamInitError): void {
    if (error.mediaStreamError && error.mediaStreamError.name === "NotAllowedError") {
      console.warn("用户不允许使用摄像机！");
    }
  }
```

## 开发

关于组件开发库的一些描述。

### Build

Run `npm run packagr` to build the library. The build artifacts will be stored in the `dist/` directory.

### Start

Run `npm start` to build and run the surrounding demo app with the `NgCamModule`. Essential for live-developing.

### Generate docs/

Run `npm run docs` to generate the live-demo documentation pages in the `docs/` directory.

### Running Unit Tests

Run `npm run test` to run unit-tests.

## 项目溯源

本组件初始代码基于[ngx-webcam](https://github.com/basst314/ngx-webcam)二次开发，开发过程中对功能进行了删改，并进行了大量的代码重构。