扩展概述 ​

Neutralino框架提供了本机API，允许用户执行各种系统级操作，如访问文件系统、执行命令和显示对话框。虽然用户可能需要更多的本地API（如数据库连接器）来构建他们的应用程序， 但将所有这些API添加到框架核心会使框架变得臃肿。因此，该框架提供了一个基于WebSocket的扩展系统，使用户可以扩展Neutranojs API。

扩展API具有很强的灵活性，你可以使用任何编程语言开发扩展代码。此外，扩展API允许您将Neutranojs进程作为其他程序的一部分。

定义扩展 ​

首先，您需要使用以下结构在neutraminojs.config.json中定义扩展。

"extensions": [
    {
        "id": "js.neutralino.sampleextension",
        "commandLinux": "${NL_PATH}/extensions/binary/linux/ext_bin",
        "commandDarwin": "${NL_PATH}/extensions/binary/mac/ext_bin",
        "commandWindows": "${NL_PATH}/extensions/binary/win/ext_bin.exe"
    },
    {
        "id": "js.neutralino.binaryextension",
        "command": "node ${NL_PATH}/extensions/binary/main.js",
    }
]

• idString: 用于标识扩展的唯一id。此id只能包含除字母、数字和小数点
• commandString (可选): 用于启动扩展的跨平台命令。例如：node ${NL_PATH}/extensions/bin/main.js将在每个平台上工作。
• commandLinuxString (可选): Linux上的扩展启动命令。
• commandDarwinString (可选): macOS上的扩展启动命令。
• commandWindowsString (可选): Windows上的扩展启动命令。

启用扩展功能 ​

扩展API在默认情况下被禁用。通过在应用配置中添加以下设置来启用扩展。

"enableExtensions": true

使用Neutralenojs连接扩展 ​

正如您已经注意到的，扩展只是一个单独的进程。Neutralizojs在框架引导进程时开始生成扩展实例，并使用以下进程参数启动每个扩展进程。

• --nl-port=<port>: Neutralinojs服务的端口
• --nl-token=<token>: 使用本机API的访问令牌
• --nl-extension-id=<id>: 扩展的id

现在，您可以使用上述进程参数连接到Neutralenojs服务器。使用以下WebSocket URL启动新的WebSocket连接。

ws://localhost:{port}?extensionId={extensionId}

将消息从应用程序发送到扩展 ​

扩展API使用基于事件的消息传递协议。每条消息都使用以下JSON结构。

{
  "event": "<event_name>",
  "data": {}
}

使用内置扩展API向任何扩展发送消息，如下所示。

let extension = 'js.neutralino.sampleextension';
let event = 'helloExtension';
let data = {
  testValue: 10,
};

await Neutralino.extensions.dispatch(extension, event, data);

上面的代码片段向js.neutralino.sampleextension扩展实例发送了一条消息。您可以随时使用dispatch方法向扩展发送消息。 如果在扩展与主进程连接之前发送消息，则Neutralinojs客户端会让消息先排队，并在目标扩展的连接建立时发送消息。换句话说，当您向扩展发送消息时，您不需要担心扩展的状态。

将消息从扩展发送到应用 ​

当您将扩展与Neutranojs主进程连接时，您可以通过直接向NeutranoJS进程发送WebSocket消息来调用本机API。Neutralinojs服务根据以下格式处理消息。

{
  "id": "<id>",
  "method": "<method>",
  "accessToken": "<token>",
  "data": {}
}

• id String: UUID字符串
• method String: 本地方法名称. Eg: window.setTitle
• accessToken String: Neutralinojs服务生成的访问令牌
• data Object (可选): 本地方法的参数

您可以调用app.broadcast本地方法向所有应用实例发送消息。在应用程序代码中使用events.on注册回调，以接收扩展进程发送的消息。

终止扩展实例 ​

当Neutralino退出时，它不会向所有扩展实例发送终止信号。因此，当基于WebSocket的IPC（进程间通信）关闭时，有必要停止扩展进程。下面的Node.js扩展代码展示了如何做到这一点：

const WS = require("websocket").w3cwebsocket;
const { v4: uuidv4 } = require("uuid");
const chalk = require("chalk");

const { nl_port, nl_token, nl_extension_id } = require("minimist")(
  process.argv.slice(2)
);

const client = new WS(
  `ws://localhost:${nl_port}?extensionId=${nl_extension_id}`
);

client.onerror = () => log("Connection error!", "ERROR");
client.onopen = () => log("Connected");
client.onclose = () => process.exit();

client.onmessage = (e) => {
  const { event, data } = JSON.parse(e.data);

  if (event === "eventToExtension") {
    log(data);

    client.send(
      JSON.stringify({
        id: uuidv4(),
        method: "app.broadcast",
        accessToken: nl_token,
        data: { event: "eventFromExtension", data: "Hello app!" },
      })
    );
  }
};

function log(message, type = "INFO") {
  const logLine = `[${nl_extension_id}]: ${chalk[
    type === "INFO" ? "green" : "red"
  ](type)} ${message}`;
  console[type === "INFO" ? "log" : "error"](logLine);
}

这段代码是Neutralizojs的Node.js扩展示例，它建立了与Neutralizojs服务的WebSocket连接，并处理来自服务的传入消息。 当它从服务接收到特定事件时，它还使用client.send方法向服务发送消息。

有关如何终止运行中实例的详细信息，可以参考示例： https://github.com/neutralinojs/neutralinojs/tree/main/bin/extensions/sampleextension

在你的源代码中使用Neutralenojs ​

上述方法帮助您使用自定义后端代码扩展Neutranojs API。Neutralizojs进程可以生成多个扩展作为子进程，并使用内部消息协议进行通信。 另一方面，您可以从自己的进程生成Neutralizojs进程，并使用相同的消息传递协议进行通信。使用这种方法，可以使用任何后端语言编写Neutranojs应用程序。

您可以通过如下配置来获取Neutralinojs程序的身份验证信息。

"exportAuthInfo": true

上述设置将身份验证详细信息导出到${NL_PATH}/.tmp/auth_info.json，格式如下：

{
  "port": "<port>",
  "accessToken": "<token>"
}

然后使用扩展API连接Neutralinojs程序。