docs • 创建节点 • .js

JavaScript 文件

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

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

节点构造函数

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

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

首先必须调用RED.nodes.createNode函数来初始化所有节点共享的功能特性。之后才是节点特定的代码部分。

function SampleNode(config) {
    RED.nodes.createNode(this,config);
    // node-specific code goes here

}

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

接收消息

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

在Node-RED 1.0版本中，引入了一种新型的监听器，允许节点在处理完消息后通知运行时环境。这为监听器函数新增了两个参数。需要注意确保该节点仍可安装在未使用这种新型监听器的Node-RED 0.x版本中。

this.on('input', function(msg, send, done) {
    // do something with 'msg'

    // Once finished, call 'done'.
    // This call is wrapped in a check that 'done' exists
    // so the node will work in earlier versions of Node-RED (<1.0)
    if (done) {
        done();
    }
});

错误处理

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

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

再次提醒，如果节点安装在Node-RED 0.x版本中需要特别注意，该版本不提供done函数。这种情况下，应该使用node.error：

let node = this;
this.on('input', function(msg, send, done) {
    // do something with 'msg'

    // If an error is hit, report it to the runtime
    if (err) {
        if (done) {
            // Node-RED 1.0 compatible
            done(err);
        } else {
            // Node-RED 0.x compatible
            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) {
    // For maximum backwards compatibility, check that send exists.
    // If this node is installed in Node-RED 0.x, it will need to
    // fallback to using `node.send`
    send = send || function() { node.send.apply(node,arguments) }

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

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

如果msg为空，则不发送任何消息。

如果节点在收到消息后需要发送响应消息，它应当重用接收到的消息而非创建新的消息对象。这样可以确保消息上的现有属性在流程的后续部分得以保留。

多路输出

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

this.send([ msg1 , msg2 ]);

多条消息

可以通过在此数组中传递消息数组，向特定输出发送多条消息：

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

关闭节点

每当部署新流程时，现有节点会被删除。如果任何节点需要在此情况下清理状态（例如断开与远程系统的连接），它们应该在close事件上注册监听器。

this.on('close', function() {
    // tidy up any state
});

如果节点需要执行任何异步工作来完成清理，已注册的监听器应接受一个参数，该参数是一个在所有工作完成时将被调用的函数。

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

自 Node-RED 0.17 版本起

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

this.on('close', function(removed, done) {
    if (removed) {
        // This node has been disabled/deleted
    } else {
        // This node is being restarted
    }
    done();
});

超时行为

自 Node-RED 0.17 版本起

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

在0.17及更高版本中，如果节点运行时间超过15秒，运行时将使其超时。将记录错误并且运行时将继续运行。

记录事件

如果节点需要向控制台输出日志信息，可以使用以下函数之一：

this.log("Something happened");
this.warn("Something happened you should know about");
this.error("Oh no, something bad happened");

// Since Node-RED 0.17
this.trace("Log some internal detail not needed for normal operation");
this.debug("Log something more details for debugging the node's behaviour");

warn 和 error 消息也会发送到流程编辑器的调试选项卡。

设置状态

在运行时，节点能够与编辑器界面共享状态信息。这是通过调用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来引用该设置。

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