> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-docs-new-agent-experience.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 用户输入

> 收集用户输入以启动工作流和对话流应用程序

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/self-host/use-dify/nodes/user-input)。

用户输入节点允许你定义从终端用户收集哪些内容作为应用程序的输入。

使用此节点启动的应用程序*按需*运行，可以通过直接用户交互或 API 调用启动。

你还可以将这些应用程序发布为独立的 Web 应用程序或 MCP 服务器，通过后端服务 API 公开它们，或在其他 Dify 应用程序中作为工具使用。

<Info>
  每个应用程序画布只能包含一个用户输入节点。
</Info>

## 输入变量

### 预设

预设输入变量由系统定义，默认可用。

* `userinput.files`：终端用户运行应用程序时上传的文件。

  <Note>
    对于工作流应用程序，此预设变量已被视为*遗留*变量，仅为向后兼容而保留。

    我们建议使用[自定义文件输入字段](#文件输入)来收集用户文件。
  </Note>

* `userinput.query`（仅限对话流）：从用户最新对话轮次自动捕获的文本消息。

### 自定义

你可以在用户输入节点中配置自定义输入字段，以收集不同类型的用户输入。每个字段都会成为下游节点可以引用的变量。

<Info>
  **标签名称** 会显示给你的终端用户。
</Info>

<Tip>
  若字段的值是你已知的（如产品标识符或租户 ID），且无需由终端用户输入，可将其标记为 **隐藏并预填**，自行提供值。详见 [隐藏并预填输入字段](#隐藏并预填输入字段)。
</Tip>

#### 文本输入

<Tabs>
  <Tab title="短文本">
    接受最多 256 个字符。用于姓名、电子邮件地址、标题或任何单行的简短文本输入。
  </Tab>

  <Tab title="段落">
    允许无长度限制的长文本。它为用户提供多行文本区域，用于详细响应或描述。
  </Tab>
</Tabs>

#### 结构化输入

<Tabs>
  <Tab title="选择">
    显示带有预定义选项的下拉菜单。用户只能从列出的选项中选择，确保数据一致性并防止无效输入。
  </Tab>

  <Tab title="数字">
    仅限数值输入，适用于数量、评分、ID 或任何需要数学处理的数据。
  </Tab>

  <Tab title="复选框">
    提供简单的是/否选项。当用户选中该框时，输出为 `true`；否则为 `false`。用于确认或任何需要二元选择的情况。
  </Tab>

  <Tab title="JSON 代码">
    接受 JSON 对象格式的数据，适用于将复杂的嵌套数据结构传递到你的应用程序。

    你可以选择定义 JSON schema 来验证输入内容，并指导用户了解预期的数据结构和验证要求。定义 schema 后，你还可以在其他节点中引用该对象的各个属性。
  </Tab>
</Tabs>

#### 文件输入

<Tabs>
  <Tab title="单个文件">
    允许用户上传任何支持类型的一个文件，可以从设备上传或通过文件 URL。上传的文件作为包含文件元数据（名称、大小、类型等）的变量可用。
  </Tab>

  <Tab title="文件列表">
    支持一次上传多个文件。它适用于批量处理文档、图像或其他文件。

    <Tip>
      使用列表操作符节点来过滤、排序或提取上传文件列表中的特定文件以进行进一步处理。
    </Tip>
  </Tab>
</Tabs>

**文件处理**

由于用户输入节点仅收集文件，不读取或解析其内容，上传的文件必须由后续节点适当处理。例如：

* 文档文件可以路由到文档提取器节点以进行文本提取，以便 LLM 能够理解其内容。

* 图像可以发送到具有视觉能力的 LLM 节点或专门的图像处理工具节点。

* CSV 或 JSON 等结构化数据文件可以使用代码节点进行解析和转换。

<Tip>
  当用户上传混合类型的多个文件（例如，图像和文档）时，你可以使用列表操作符节点按文件类型分离它们，然后将它们路由到不同的处理分支。
</Tip>

## 隐藏并预填输入字段

工作流有时需要一些你已知的输入，让终端用户手动填写只会增加摩擦。可将此类字段标记为 **隐藏并预填**：值由你预先填好，终端用户看不到该字段，而工作流仍能拿到值。

假设你的公司有多个产品的落地页，每个页面都嵌入了 AI 聊天机器人。这些聊天机器人背后的工作流基本相同，只是处理的产品不同。

与其为每个产品维护一个独立的工作流，不如只用一个，并为其添加隐藏的 `productName` 字段，然后为各个落地页预填不同的值。在终端用户看来，每个页面都有专属的产品聊天机器人，但实际上各个页面只是向同一个工作流传入了不同的 `productName`。

<Warning>
  隐藏字段 **并不保密**。字段值会出现在 URL 查询字符串中，浏览器地址栏、历史记录和网络流量中都能看到。凭据和 API 密钥需改用 [环境变量](/zh/learn/key-concepts#变量)。
</Warning>

<Info>
  单个文件和文件列表字段不支持此功能。
</Info>

<Steps>
  <Step title="启用功能">
    1. 在 **编辑变量** 窗口中，取消勾选 **必填**（若已勾选）。这两个选项互斥。
    2. 勾选 **隐藏并预填**。可同时设置默认值用作兜底。

    隐藏字段在 **预览** 面板中仍会显示，便于你在发布前测试流程。
  </Step>

  <Step title="预填字段值">
    1. 发布应用。
    2. 根据终端用户访问应用的方式，选择对应的方法。

           <Tabs>
             <Tab title="可分享的链接">
               适用于终端用户通过链接直接打开 WebApp 的场景。

               1. 在应用发布面板的 **Web App** 板块中，点击 **启动** 旁的齿轮图标。
                          <Frame>
                            <img src="https://mintcdn.com/dify-6c0370d8-docs-new-agent-experience/jyDkeP_GDYJzJ81D/images/use-dify/workflow/hidden-field-config-icon.png?fit=max&auto=format&n=jyDkeP_GDYJzJ81D&q=85&s=f95f92a6625dfbe948a76ea25d6026f6" alt="隐藏字段预填图标" width="874" height="330" data-path="images/use-dify/workflow/hidden-field-config-icon.png" />
                          </Frame>
               2. 填入隐藏字段的值并点击 **启动**。WebApp 打开后，预填值已作为 URL 查询参数填入地址栏，复制 URL 即可分享。

               **若需生成大量带有不同值的链接**，可参照该 URL 模式自行编写更多链接，或让第三方系统自动生成：

               ```text wrap theme={null}
               {WEBAPP_URL}?{VARIABLE_NAME}={VALUE}&{VARIABLE_NAME}={VALUE}

               # 示例：{WEBAPP_URL}/chat/abc123?productName=Acme&region=us-east
               ```

               <Note>
                 含空格或特殊字符的值需要 URL 编码（例如 `Acme Corp` 写作 `Acme%20Corp`）。
               </Note>

               <Accordion title="示例：CRM 自动填入客户 ID">
                 客服团队可在 CRM 的工单回复模板中，将 `?customerId={{customer.id}}` 追加到 WebApp URL 末尾。

                 客服发送链接时，CRM 会自动替换成实际的客户 ID，聊天机器人无需再询问即可识别客户。
               </Accordion>
             </Tab>

             <Tab title="在网站中嵌入">
               适用于将应用以 iframe 或脚本形式嵌入网站的场景。

               <Tabs>
                 <Tab title="所有访客同值">
                   适用于所有访客接收相同值的场景（如全站区域、嵌入页面的产品 ID 等）。

                   1. 在应用发布面板的 **Web App** 板块中，点击 **嵌入** > **预填隐藏字段**。
                                  <Frame>
                                    <img src="https://mintcdn.com/dify-6c0370d8-docs-new-agent-experience/jyDkeP_GDYJzJ81D/images/use-dify/workflow/embedding-icon.png?fit=max&auto=format&n=jyDkeP_GDYJzJ81D&q=85&s=a520746c46e496a41f5ded86966b2a78" alt="嵌入图标" width="876" height="338" data-path="images/use-dify/workflow/embedding-icon.png" />
                                  </Frame>
                   2. 填入隐藏字段的值。这些值会嵌入到 iframe URL 和脚本片段的 `inputs` 对象中。
                 </Tab>

                 <Tab title="访客不同值">
                   适用于每位访客接收各自值的场景（如登录用户的 ID、当前所在页面等）。

                   在网站的嵌入脚本中，把每个隐藏字段加到 `window.difyChatbotConfig` 的 `inputs` 对象里。值在渲染时根据当前页面上下文动态计算，每位访客都能拿到各自的值。

                   ```html theme={null}
                   <script>
                     window.difyChatbotConfig = {
                       token: 'YOUR_TOKEN',
                       inputs: {
                         productName: getCurrentProduct(),    // 来自当前页面
                         tenantId: getCurrentTenant(),        // 来自你的认证系统
                       },
                     };
                   </script>
                   ```
                 </Tab>
               </Tabs>
             </Tab>
           </Tabs>
  </Step>
</Steps>