Node-RED:Создание нод/JavaScript-файл

Содержание

Введение

Руководство пользователя

Рецепты

Создание нод

Библиотеки

Перевод: Максим Кузьмин

Проверка/Оформление/Редактирование: Мякишев Е.А.

JavaScript-файл

Файл ноды с расширением «*.js» задает поведение той части ноды, что связана со средой выполнения Node-RED.

Конструктор ноды

Ноды определяются с помощью функции-конструктора, которую можно использовать для создания новых экземпляров ноды. Эта функция регистрируется с помощью среды выполнения, благодаря чему ее можно вызывать при развертке в потоке нод соответствующего типа.

Этой функции передается объект со свойствами, заданными в редакторе потока.

Самое первое, что должна сделать эта функция – это вызвать функцию «RED.nodes.createNode», чтобы инициализировать функционал, которым также обладают все прочие ноды. Только после этого пишется код, отвечающий за работу самой ноды.

function SampleNode(config) {
    RED.nodes.createNode(this,config);
    // код со специфическим функционалом ноды

}

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

Получение сообщений

Если вашей ноде нужно получать сообщения от нод, стоящих выше в потоке, в ней нужно зарегистрировать прослушивателя для события «input».

this.on('input', function(msg) {
    // делаем здесь что-нибудь с сообщением 'msg'
});

Отправка сообщений

Ноды могут отправлять сообщения нодам, стоящим ниже в потоке, при помощи функции send().

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

Если в «msg» содержится «null», то сообщение отправлено не будет.

Если нода отправляет сообщение в ответ на получение сообщения, то она должна переработать присланное сообщение, а не сгенерировать новое. Благодаря этому обеспечивается, что свойства присланного сообщения остаются без изменения на протяжении всего потока.

Несколько выходных портов

Если у ноды более одного выходного порта, а параметрах функции send() можно задать массив сообщений, каждое из которых будет отправлено соответствующему выходному порту.

this.send([ msg1 , msg2 ]);

Несколько сообщений

Кроме того, у вас есть возможность отправить несколько сообщений на один выходной порт, поместив внутри массива сообщений еще один массив сообщений.

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

Закрытие ноды

Развертка нового потока удаляет все старые ноды. Если при этом вам также нужно остановить то, чем нода занимается в данный момент (например, отключиться от удаленной системы), в этой ноде нужно зарегистрировать прослушивателя для события «close».

this.on('close', function() {
    // код для остановки процесса, выполняемого нодой
});

Кроме того, если вам для остановки того, чем нода занимается в данный момент, нужно выполнить какую-то асинхронную работу, в параметре функции function() – которая является прослушивателем событий – нужно задать функцию, которая будет вызываться после того, как вся работа будет выполнена.

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

Начиная с Node-RED версии 0.17

Если в зарегистрированном прослушивателе событий – т.е. в function() – стоит два параметра, то первый – это булево значение, определяющее, была ли нода закрыта через полное удаление или же она просто была перезапущена.

this.on('close', function(removed, done) {
    if (removed) {
        // Эта нода была удалена
    } else {
        // Эта нода была перезапущена
    }
    done();
});

Таймаут

До выхода Node-RED версии 0.17 среда выполнения бесконечно ждала вызова функции done(). Таким образом, если ноду не удавалось вызвать, среда выполнения могла зависнуть.

С выходом версии 0.17 среда выполнения в такой ситуации запустит 15-секундный таймаут. Если спустя эти 15 секунд нода так и не заработает, в логи будет записана соответствующая ошибка, а среда выполнения продолжит работать дальше.

Логирование событий

Если вам нужно, чтобы нода записывала в консоль логи о происходящих с нею событиях, то вы можете воспользоваться одной из следующих функций:

this.log("Что-то произошло");
this.warn("Произошло что-то, о чем вам надо знать");
this.error("О нет, произошло что-то ужасное!");

// Начиная с версии 0.17:
this.trace("Некоторые подробности о внутренней работе ноды, которые при обычном ее использовании, как правило, не нужны");
this.debug("Еще больше подробностей о работе ноды для ее отладки");

Сообщения уровней «warn» и «error» тоже отправляются на вкладку «Debug» боковой панели.

Обработка ошибок

Если нода сталкивается с ошибкой, останавливающей работу текущего потока, она должна написать об этом событии в логи при помощи функции this.error().

Если это такая ошибка, которую пользователь ноды, возможно, захочет обработать сам, то во втором параметре этой функции должно находиться исходное сообщение ноды (или пустое сообщение, если это нода категории «Input»):

node.error("ошибка", msg);

Это активирует все ноды «Catch», находящиеся в той же вкладке.

Установка статуса

Будучи запущенной, нода может показывать свой статус прямо в интерфейсе редактора Node-RED. Это делается при помощи функции status():

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

Более подробно об API для установки статуса можно почитать тут.

Кастомизация настроек ноды

Вы также можете предоставить доступ к настройкам своей ноды в пользовательском файле «settings.js».

Название любой настройки должно отвечать следующим требованиям:

• В начале должно стоять название соответствующей ноды
• Необходимо использовать т.н. «верблюжий регистр»
• Нода не должна требовать от пользователя настроить ее – у нее должны быть разумные умолчания

К примеру, если у ноды типа «sample-node» предоставлен доступ к настройке «colour», то названием для этой настройки должно быть «sampleNodeColour».

В среде выполнения Node-RED нода может обратиться к этой настройке через конструкцию «RED.setting.sampleNodeColour».

Предоставление редактору доступа к настройкам

Начиная с Node-RED версии 0.17.

В некоторых случаях может понадобиться, чтобы нода предоставила редактору доступ к значению какой-то своей настройки. Для этого нода должна зарегистрировать эту настройку в своей функции registerType().

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

• В поле «value» задается значение по умолчанию для этой настройки
• В поле «exportable» при помощи среды выполнения задается, чтобы эта настройка стала доступна редактору

В редакторе нода может обратиться к этой настройке так же, как и в среде выполнения – с помощью конструкции «RED.settings.sampleNodeColour».

Если вы попытаетесь зарегистрировать настройку, чье название не будет отвечать требованиям выше, в логи будет записана соответствующая ошибка.