PeerJS 怎么使用的?

针对 PeerJS 的常见 api 使用进行描述

概要

官网:PeerJS - Simple peer-to-peer with WebRTC

此 JavaScript 类库简化了 WebRTC 的使用,可用于建立连接、数据发送、媒体流请求。

入门使用示例


引入 PeerJS

  • CDN 引入
1
<script src="https://unpkg.com/peerjs@1.5.1/dist/peerjs.min.js"></script>
  • npm 项目依赖
1
npm i peerjs

初始化

1
2
3
4
5
6
7
// 新建实例
var peer = new Peer();

// 创建 peer,如果新建实例时未携带 id 参数,则此处会自动赋值随机唯一 id
peer.on('open', function(id) {
	console.log('My peer ID is: ' + id);
  });

连接

1
var conn = peer.connect('dest-peer-id');

被连接

1
peer.on('connection', function(conn) { ... });

操作连接

1
2
3
4
5
6
7
8
9
conn.on('open', function() {
	// 接收数据
	conn.on('data', function(data) {
	  console.log('Received', data);
	});

	// 发送数据
	conn.send('Hello!');
  });

请求数据流

1
2
3
4
5
6
7
// Call a peer, providing our mediaStream
var call = peer.call('dest-peer-id', mediaStream);

call.on('stream', function(stream) {
	// `stream` is the MediaStream of the remote peer.
	// Here you'd add it to an HTML video/canvas element.
  });

被请求数据流

1
2
3
4
peer.on('call', function(call) {
    // Answer the call, providing our mediaStream
    call.answer(mediaStream);
});

PeerJS 的 API

Peer

构造函数

1
const peer = new Peer[id] [options];

options

名称 解释
key PeerServer 的 API 密钥。这不用于默认 PeerServer(0.peerjs.com )以外的服务器。
host 服务器主机。缺省值为0.peerjs.com``'/' ,也可以为自己搭建的 PeerServer 服务。
port 服务器端口。默认值为 443
pinginterval Ping 间隔(毫秒)默认值为 5000
path 自承载 PeerServer 的运行路径。默认值为 '/'
secure true如果您使用的是 SSL。请注意,我们的云托管服务器和资产可能不支持 SSL。
config 传递给 RTCPeerConnection 的配置哈希。此哈希包含任何自定义 ICE/TURN 服务器配置。默认为{ 'iceServers': [{ 'urls': 'stun:stun.l.google.com:19302' }], 'sdpSemantics': 'unified-plan' }
debug 根据传入的调试级别打印日志消息。默认值为0

0:不打印;1:打印错误;2:打印错误和警告;3:打印所有

peer 方法

peer.connect

1
const dataConnection = peer.connect(id, [options]);

options

名称 解释
label 要用于标识此数据连接的唯一标签。如果未指定,将随机生成一个标签。可以使用 dataConnection.label 进行访问。
metadata 与连接关联的元数据,由发起连接的任何人传入。可以使用 dataConnection.metadata 进行访问。可以是任何可序列化的类型。
serialization 传输的序列化方式
reliable 数据通道是否应该可靠

peer.call

1
const mediaConnection = peer.call(id, stream, [options]);

options

名称 解释
metadata 与连接关联的元数据,由发起连接的任何人传入。可以使用 mediaConnection.metadata 进行访问。可以是任何可序列化的类型。
sdpTransform

peer.disconnect

1
peer.disconnect();

peer.reconnect

1
peer.reconnect();

peer.destroy

1
peer.destroy();

peer 触发事件

1
peer.on(event, callback);

event

event 解释
‘open’ 在与 PeerServer 建立连接时发出
‘connection’ 从远程 Peer 建立新的数据连接时发出
‘call’ 当远程对等体尝试呼叫您时发出
‘close’ 当对等体被销毁并且无法再接受或创建任何新连接时发出
‘disconnected’ 当对等体与信令服务器断开连接时发出
’error' 触发错误

peer 属性字段

字段 解释
id peer 的 id
connections 与此 Peer 关联的所有连接的哈希值,由远程 Peer 的 ID 进行键控。我们建议自己跟踪连接,而不是依赖此哈希。
disconnected 是否断开连接
destroyed 是否已被销毁

DataConnection

创建 DataConnection

1
const dataConnection = peer.connect(id, [options]);

方法

名称 解释
send 发送任何类型的数据
close 正常关闭数据连接,清理基础 DataChannel 和 PeerConnections

触发事件

1
dataConnection.on(event, callback);
名称 解释
‘data’ 从远程 peer 接收数据时触发
‘open’ 在建立连接并准备使用时触发
‘close’ 在你或远程 Peer 关闭数据连接时触发
’error' 发生错误时触发

属性字段

字段 解释
dataChannel 对与连接关联的 RTCDataChannel 对象的引用
label 启动连接时传入或由 PeerJS 分配的可选标签
metadata 与连接关联的任何类型的元数据,由发起连接的任何人传入
open 如果连接已打开并准备好进行读/写,则为 true
peerConnection 对与连接关联的 RTCPeerConnection 对象的引用
peer 此连接另一端的 Peer 的 ID
reliable 底层数据通道是否可靠;在启动连接时定义
serialization 通过连接发送的数据的序列化格式
type 始终是 'data'
bufferSize 浏览器缓冲区不再满后排队发送的消息数

MediaConnection

创建 MediaConnection

1
const mediaConnection = peer.call(id, stream, [options]);

方法

名称 解释
answer 在 peer 上接收到呼叫事件时,您可以调用回调提供的媒体连接来接受呼叫,并可以选择发送自己的媒体流。
close 关闭媒体连接

触发事件

1
mediaConnection.on(event, callback);
名称 解释
‘stream’ (stream)=>{}
‘close’ ()=>{}
’error' (err)=>{}

属性字段

名称 解释
open 媒体连接是否处于活动状态
metadata 与连接关联的任何类型的元数据,由发起连接的任何人传入
peer 此连接另一端的 Peer 的 ID
type 这始终是 'media'

util

名称 解释
.browser 当前浏览器是否支持该功能
.supports.audioVideo 当前浏览器是否支持媒体流和 PeerConnection
.supports.data 当前浏览器是否支持 DataChannel 和 PeerConnection
.supports.binary 当前浏览器是否支持二进制 DataChannel
.supports.reliable 当前浏览器是否支持可靠的 DataChannel

示例项目

Gearinger/gear-p2p-file (github.com)


参考

【1】PeerJS Documentation

Licensed under CC BY-NC-SA 4.0
Gear(夕照)的博客。记录开发、生活,以及一些不足为道的思考……