express-ws

WebSocket endpoints for Express applications. Express应用程序的WebSocket端点。Lets you define WebSocket endpoints like any other type of route, and applies regular Express middleware. 允许您像任何其他类型的路由一样定义WebSocket端点，并应用常规Express中间件。The WebSocket support is implemented with the help of the ws library.WebSocket支持是在ws库的帮助下实现的。

Installation安装

npm install --save express-ws

Usage用法

Full documentation can be found in the API section below. This section only shows a brief example.完整的文档可以在下面的API部分中找到。本节仅显示一个简短的示例。

Add this line to your Express application:将此行添加到您的Express应用程序中：

var expressWs = require('express-ws')(app);

Important: Make sure to set up the express-ws module like above before loading or defining your routers!重要提示：在加载或定义路由器之前，请确保像上面一样设置express-ws模块！ Otherwise, express-ws won't get a chance to set up support for Express routers, and you might run into an error along the lines of router.ws is not a function.否则，express-ws将没有机会设置对express路由器的支持，并且您可能会在路由器上遇到router.ws is not a function错误。

After setting up express-ws, you will be able to add WebSocket routes (almost) the same way you add other routes. 在设置了express-ws之后，您将能够添加WebSocket路由（几乎），就像添加其他路由一样。The following snippet sets up a simple echo server at /echo. 下面的代码段在/echo中设置了一个简单的echo服务器。The ws parameter is an instance of the WebSocket class described here.ws参数是这里描述的WebSocket类的一个实例。

app.ws('/echo', function(ws, req) {
  ws.on('message', function(msg) {
    ws.send(msg);
  });
});

It works with routers, too, this time at /ws-stuff/echo:它也适用于路由器，这次是在/ws-stuff/echo：

var router = express.Router();

router.ws('/echo', function(ws, req) {
  ws.on('message', function(msg) {
    ws.send(msg);
  });
});

app.use("/ws-stuff", router);

Full example完整示例

var express = require('express');
var app = express();
var expressWs = require('express-ws')(app);

app.use(function (req, res, next) {
  console.log('middleware');
  req.testing = 'testing';
  return next();
});

app.get('/', function(req, res, next){
  console.log('get route', req.testing);
  res.end();
});

app.ws('/', function(ws, req) {
  ws.on('message', function(msg) {
    console.log(msg);
  });
  console.log('socket', req.testing);
});

app.listen(3000);

API

expressWs(app, server, options)

Sets up express-ws on the specified app. 在指定的app上设置express-ws。This will modify the global Router prototype for Express as well - see the leaveRouterUntouched option for more information on disabling this.这也将修改Express的全局路由器原型-有关禁用此功能的更多信息，请参阅leaveRouterUntouched选项。

• app: The Express application to set up express-ws on.：要在上设置express-ws的Express应用程序。
• server: Optional. When using a custom http.Server, you should pass it in here, so that express-ws can use it to set up the WebSocket upgrade handlers. ：可选。使用自定义http.Server时，应该将其传递到此处，以便express ws可以使用它来设置WebSocket升级处理程序。If you don't specify a server, you will only be able to use it with the server that is created automatically when you call app.listen.如果不指定server，则只能将其与调用app.listen时自动创建的服务器一起使用。
• options: Optional.可选择的 An object containing further options. 包含其他选项的对象。
  • leaveRouterUntouched: Set this to true to keep express-ws from modifying the Router prototype. 将此设置为true可防止express-ws修改Router原型。You will have to manually applyTo every Router that you wish to make .ws available on, when this is enabled.启用此功能后，您必须手动将其应用到您希望使ws可用的每个路由器。
  • wsOptions: Options object passed to WebSocketServer constructor. Necessary for any ws specific features.传递给WebSocketServer构造函数的Options对象。对于任何特定于ws的功能都是必要的。

This function will return a new express-ws API object, which will be referred to as wsInstance in the rest of the documentation.此函数将返回一个新的express-ws API对象，在文档的其余部分中称为wsInstance。

wsInstance.app

This property contains the app that express-ws was set up on.此属性包含在其上设置express-ws的app。

wsInstance.getWss()

Returns the underlying WebSocket server/handler. 返回基础WebSocket服务器/处理程序。You can use wsInstance.getWss().clients to obtain a list of all the connected WebSocket clients for this server.您可以使用wsInstance.getWss().clients客户端来获取此服务器所有连接的WebSocket客户端的列表。

Note that this list will include all clients, not just those for a specific route - this means that it's often not a good idea to use this for broadcasts, for example.请注意，该列表将包括所有客户端，而不仅仅是特定路由的客户端——这意味着，例如，将其用于广播通常不是一个好主意。

wsInstance.applyTo(router)

Sets up express-ws on the given router (or other Router-like object). 在给定的router（或其他类似路由器的对象）上设置express-ws。You will only need this in two scenarios:您只需要在两种情况下使用：

1. You have enabled options.leaveRouterUntouched, or您已启用选项options.leaveRouterUntouched，或
2. You are using a custom router that is not based on the express.Router prototype.您使用的自定义路由器不是基于express.Router原型的。

In most cases, you won't need this at all.在大多数情况下，你根本不需要这个。

Development发展

This module is written in ES6 and uses ESM.该模块使用ES6编写，并使用ESM。