docs • creating nodes • .js

JavaScript 文件

节点 .js 文件定义了节点的运行时行为。

节点构造函数
接收消息
发送消息
- 多个输出
- 多个消息
关闭节点
- 超时行为
记录事件
- 处理错误
设置状态
自定义节点设置

节点构造函数

节点由一个构造函数定义，该函数可用于创建节点的新实例。该函数在运行时注册，以便在流中部署相应类型的节点时可以调用。

该函数会接收一个包含在流程编辑器中设置的属性的对象。

它首先要做的是调用 RED.nodes.createNode 函数来初始化所有节点共享的特性。之后，节点特定的代码就可以编写。

function SampleNode(config) {
    RED.nodes.createNode(this,config);
    // 节点特定的代码在这里

}

RED.nodes.registerType("sample",SampleNode);

接收消息

节点在 input 事件上注册一个监听器，以接收来自流中上游节点的消息。

从 Node-RED 1.0 开始，引入了新的监听器样式，允许节点在完成处理消息时通知运行时。这向监听器函数添加了两个新参数。需要小心以确保节点仍然可以安装在不使用这种新样式的 Node-RED 0.x 中。

this.on('input', function(msg, send, done) {
    // 处理 'msg' 的逻辑

    // 一旦完成，调用 'done'。
    // 这个调用被包装在一个检查 'done' 是否存在的逻辑中，
    // 因此该节点将在早期版本的 Node-RED 中工作 (<1.0)
    if (done) {
        done();
    }
});

处理错误

如果节点在处理消息时遇到错误，它应该将错误的详细信息传递给 done 函数。

这将触发同一标签页上存在的任何 Catch 节点，允许用户构建流来处理错误。

同样，如果节点安装在不提供 done 函数的 Node-RED 0.x 中，则需要谨慎处理。在这种情况下，应该使用 node.error：

let node = this;
this.on('input', function(msg, send, done) {
    // 处理 'msg' 的逻辑

    // 如果遇到错误，将其报告给运行时
    if (err) {
        if (done) {
            // 与 Node-RED 1.0 兼容
            done(err);
        } else {
            // 与 Node-RED 0.x 兼容
            node.error(err, msg);
        }
    }
});

发送消息

如果节点处于流的开始位置并对外部事件产生消息，它应该在 Node 对象上使用 send 函数：

var msg = { payload:"hi" }
this.send(msg);

如果节点希望在 input 事件监听器内部响应收到消息时发送，它应该使用传递给监听器函数的 send 函数：

let node = this;
this.on('input', function(msg, send, done) {
    // 为了最大程度地向后兼容，检查 send 是否存在。
    // 如果该节点安装在 Node-RED 0.x 中，它需要
    // 回退使用 `node.send`
    send = send || function() { node.send.apply(node,arguments) }

    msg.payload = "hi";
    send(msg);

    if (done) {
        done();
    }
});

如果 msg 为 null，则不发送消息。

如果节点是在收到消息后发送消息，则应重用收到的消息，而不是创建一个新的消息对象。这确保了消息中现有属性在整个流中的保留。

多个输出

如果节点有多个输出，可以将一组消息传递给 send，每个消息将被发送到对应的输出。

this.send([ msg1 , msg2 ]);

多个消息

可以通过在该数组中传递一组消息来向特定输出发送多个消息：

this.send([ [msgA1 , msgA2 , msgA3] , msg2 ]);

关闭节点

每当部署新的流程时，现有节点将被删除。如果它们在此发生时需要整理状态，例如与远程系统断开连接，它们应在 close 事件上注册一个监听器。

this.on('close', function() {
    // 整理任何状态
});

如果节点需要执行任何异步工作以完成整理，注册的监听器应接受一个参数，这是一个函数，当所有工作完成时调用。

this.on('close', function(done) {
    doSomethingWithACallback(function() {
        done();
    });
});

自 Node-RED 0.17 起

如果注册的监听器接受两个参数，第一个将是一个布尔标志，指示节点是否因为被完全移除而关闭，或者它只是被重新启动。如果节点被禁用，它也将被设置为 true。

this.on('close', function(removed, done) {
    if (removed) {
        // 该节点已被禁用/删除
    } else {
        // 该节点正在重新启动
    }
    done();
});

超时行为

自 Node-RED 0.17 起

在 Node-RED 0.17 之前，运行时会无限期等待 done 函数被调用。如果一个节点未能调用它，这将导致运行时挂起。

在 0.17 及之后的版本中，如果节点花费超过 15 秒，运行时将超时该节点。将记录错误，运行时将继续操作。

记录事件

如果一个节点需要记录某些内容到控制台，它可以使用以下函数之一：

this.log("发生了某事");
this.warn("发生了你应该知道的事情");
this.error("哦，不，发生了不好的事情");

// 自 Node-RED 0.17 起
this.trace("记录一些正常操作中不需要的内部细节");
this.debug("记录一些更详细信息以调试节点的行为");

warn 和 error 消息也会发送到流程编辑器的调试标签页。

设置状态

在运行过程中，节点能够与编辑器 UI 共享状态信息。这是通过调用 status 函数实现的：

this.status({fill:"red",shape:"ring",text:"disconnected"});

状态 API 的详细信息可以在这里找到。

自定义节点设置

一个节点可能希望在用户的 settings.js 文件中公开配置选项。

任何设置的名称必须遵循以下要求：

名称必须以相应的节点类型为前缀。
设置必须使用驼峰式命名 - 更多信息见下文。
节点不应要求用户设置它 - 应该具有合理的默认值。

例如，如果节点类型 sample-node 希望公开名为 colour 的设置，则设置名称应为 sampleNodeColour。

在运行时，节点可以引用该设置为 RED.settings.sampleNodeColour。

向编辑器公开设置

自 Node-RED 0.17 起

在某些情况下，节点可能希望向编辑器公开设置的值。如果是这样，则节点必须在调用 registerType 时注册该设置：

RED.nodes.registerType("sample",SampleNode, {
    settings: {
        sampleNodeColour: {
            value: "red",
            exportable: true
        }
    }
});

value 字段指定设置的默认值。
exportable 告诉运行时使设置可用于编辑器。

与运行时一样，节点在编辑器中也可以引用该设置为 RED.settings.sampleNodeColour。

如果节点尝试注册不符合命名要求的设置，将记录错误。