docs • creating nodes • help

节点帮助风格指南

当选择一个节点时，它的帮助文本会显示在信息选项卡中。此帮助应为用户提供使用节点所需的所有信息。

以下风格指南描述了帮助的结构，以确保节点之间外观一致。

自 2.1.0 起：帮助文本可以以 markdown 而不是 HTML 提供。在这种情况下，<script> 标签的 type 属性必须为 text/markdown。
创建 markdown 帮助文本时，请注意缩进，markdown 对空格敏感，因此所有行在 <script> 标签内都不应该有前导空格。

本节提供了对节点的高层次介绍。长度应不超过 2 或 3 行。第一行 (<p>) 用作在调色板中悬停节点时的工具提示。

连接到 MQTT 代理并发布消息。

如果节点具有输入，此部分描述节点将使用的消息属性。可以提供每个属性的预期类型。描述应简短 - 如果需要进一步描述，应在详细信息部分中进行。

输入

payload string | buffer: 要发布的消息的有效负载。
topic string: 要发布的 MQTT 主题。

如果节点具有输出，类似于输入部分，本节描述节点将发送的消息属性。如果节点具有多个输出，可以为每个提供单独的属性列表。

输出

标准输出

payload string

命令的标准输出。
标准错误

payload string

命令的标准错误。

本节提供有关节点的更详细信息。它应解释如何使用，并提供有关其输入/输出的更多信息。

详细信息

msg.payload 被用作发布消息的有效负载。如果它包含一个对象，它将在发送之前被转换为 JSON 字符串。如果它包含一个二进制缓冲区，消息将按原样发布。

使用的主题可以在节点中配置，或者如果留空，可以通过 msg.topic 设置。

同样，QoS 和保留值也可以在节点中配置，或者如果留空，则分别通过 msg.qos 和 msg.retain 设置。

本节可用于提供外部资源的链接，例如：

任何相关的额外文档。例如，模板节点如何链接到 Mustache 语言指南。
节点的 git 仓库或 npm 页面 - 用户可以在此获得额外帮助

参考

Twitter API 文档 - msg.tweet 属性的完整描述
GitHub - 节点的 GitHub 仓库

上述示例是使用以下内容创建的：.

<script type="text/html" data-help-name="node-type">
<p>连接到 MQTT 代理并发布消息。</p>

<h3>输入</h3>
    <dl class="message-properties">
        <dt>payload
            <span class="property-type">string | buffer</span>
        </dt>
        <dd>要发布的消息的有效负载。</dd>
        <dt class="optional">topic <span class="property-type">string</span></dt>
        <dd>要发布的 MQTT 主题。</dd>
    </dl>

 <h3>输出</h3>
     <ol class="node-ports">
         <li>标准输出
             <dl class="message-properties">
                 <dt>payload <span class="property-type">string</span></dt>
                 <dd>命令的标准输出。</dd>
             </dl>
         </li>
         <li>标准错误
             <dl class="message-properties">
                 <dt>payload <span class="property-type">string</span></dt>
                 <dd>命令的标准错误。</dd>
             </dl>
         </li>
     </ol>

<h3>详细信息</h3>
    <p><code>msg.payload</code> 被用作发布消息的有效负载。如果它包含一个对象，它将在发送之前被转换为 JSON 字符串。如果它包含一个二进制缓冲区，消息将按原样发布。</p>
    <p>使用的主题可以在节点中配置，或者如果留空，可以通过 <code>msg.topic</code> 设置。</p>
    <p>同样，QoS 和保留值也可以在节点中配置，或者如果留空，则分别通过 <code>msg.qos</code> 和 <code>msg.retain</code> 设置。</p>

<h3>参考</h3>
    <ul>
        <li><a>Twitter API 文档</a> - <code>msg.tweet</code> 属性的完整描述</li>
        <li><a>GitHub</a> - 节点的 GitHub 仓库</li>
    </ul>
</script>

<script type="text/markdown" data-help-name="node-type">
连接到 MQTT 代理并发布消息。

### 输入

: payload (string | buffer) :  要发布的消息的有效负载。
: *topic* (string)          :  要发布的 MQTT 主题。


### 输出

1. 标准输出
: payload (string) : 命令的标准输出。

2. 标准错误
: payload (string) : 命令的标准错误。

### 详细信息

`msg.payload` 被用作发布消息的有效负载。
如果它包含一个对象，它将在发送之前被转换为 JSON 字符串。
如果它包含一个二进制缓冲区，消息将按原样发布。

使用的主题可以在节点中配置，或者如果留空，可以通过 `msg.topic` 设置。

同样，QoS 和保留值可以在节点中配置，或者如果留空，则分别通过 `msg.qos` 和 `msg.retain` 设置。

### 参考

 - [Twitter API 文档]() - <code>msg.tweet</code> 属性的完整描述
 - [GitHub]() - 节点的 GitHub 仓库
</script>

节标题

每个部分必须使用 <h3> 标签标记。如果“详细信息”部分需要子标题，则必须使用 <h4> 标签。

<h3>输入</h3>
...
<h3>详细信息</h3>
...
 <h4>一个子部分</h4>
 ...

### 输入
...
### 详细信息
...
#### 一个子部分
...

消息属性

消息属性列表使用 <dl> 列表标记。该列表必须具有 message-properties 的类属性。

列表中的每个项目由一对 <dt> 和 <dd> 标签组成。

每个 <dt> 包含属性名称和一个可选的 <span class="property-type">，该标签包含属性的预期类型。如果属性是可选的，<dt> 应具有 optional 的类属性。

每个 <dd> 包含对属性的简要描述。

<dl class="message-properties">
    <dt>payload
        <span class="property-type">string | buffer</span>
    </dt>
    <dd>要发布的消息的有效负载。</dd>
    <dt class="optional">topic
        <span class="property-type">string</span>
    </dt>
    <dd>要发布的 MQTT 主题。</dd>
</dl>

: payload (string | buffer) :  要发布的消息的有效负载。
: *topic* (string)          :  要发布的 MQTT 主题。

多个输出

如果节点具有多个输出，则每个输出应具有自己的消息属性列表，如上所述。这些列表应包装在具有 node-ports 的类属性的 <ol> 列表中。

列表中的每个项目应包括输出的简要描述，后面跟着一个 <dl> 消息属性列表。

注意：如果节点只有一个输出，则不应将其包装在此类列表中，仅使用 <dl>。

<ol class="node-ports">
    <li>标准输出
        <dl class="message-properties">
            <dt>payload <span class="property-type">string</span></dt>
            <dd>命令的标准输出。</dd>
        </dl>
    </li>
    <li>标准错误
        <dl class="message-properties">
            <dt>payload <span class="property-type">string</span></dt>
            <dd>命令的标准错误。</dd>
        </dl>
    </li>
</ol>

1. 标准输出
: payload (string) : 命令的标准输出。

2. 标准错误
: payload (string) : 命令的标准错误。

一般指导

在引用消息属性时，外界应在消息属性列表中描述，并用 msg. 前缀，以便清楚地向读者说明它。它们应包裹在 <code> 标签中。

有趣的部分在于 <code>msg.payload</code>。

有趣的部分在于 `msg.payload`。

在帮助文本的主体中不应使用其他样式标记（例如 <b>，<i>）。

帮助文本不应假定读者是经验丰富的开发人员或对节点所暴露的内容非常熟悉；最重要的是，它需要具有帮助性。