Docassemble中利用AJAX与屏幕刷新实现动态联动下拉列表

本教程探讨在docassemble中实现动态联动下拉菜单的两种主要方法，以国家和州选择器为例。我们将介绍如何利用`input type: ajax`结合依赖字段的`code`属性实现选项的实时更新，以及如何通过`background_response_refresh`策略在用户更改选择时刷新屏幕，从而动态调整字段选项乃至标签。文章旨在帮助开发者构建更具交互性和用户体验的docassemble表单。

传统实现方式回顾

在Docassemble中，实现国家和州/省的联动选择，最直接但非动态的方式是将它们放置在不同的问题中。用户首先回答国家问题，然后根据所选国家，在下一个问题中呈现相应的州/省列表。这种方式虽然功能完整，但用户体验上存在限制，因为它需要用户在不同页面间跳转。

以下是这种传统实现方式的示例代码：

---
question: |
  请选择您居住的国家/地区：
fields:
 - 国家: jurisdiction.country
   input type: combobox
   code: countries_list()
---
question: |
  请选择您居住的州/省：
fields:
 - ${ subdivision_type(jurisdiction.country) }: jurisdiction.state
   input type: combobox
   code: states_list(jurisdiction.country)
---

上述代码中，jurisdiction.state 字段的 states_list() 函数会根据前一个问题中 jurisdiction.country 的值来过滤州/省列表。subdivision_type() 函数则根据国家动态生成字段标签（例如，“State”或“Province”）。然而，这种方式无法在同一页面上实现实时联动。

方法一：利用 input type: ajax 实现依赖字段选项的动态更新

为了在同一页面上实现国家和州/省的联动，Docassemble 提供了 input type: ajax 机制。当一个字段被标记为 input type: ajax 后，其值发生改变时会触发一个后台AJAX请求。服务器会重新评估所有依赖于该字段值的其他字段的 code 或 choices_code，并将更新后的选项发送回客户端进行显示。

实现步骤与代码示例

将国家和州/省选择字段放置在同一个 question 块中，并为作为触发器的国家字段添加 input type: ajax。

萌动AI

CreateAI旗下AI动漫视频生成平台

438

查看详情

---
question: |
  请选择您居住的国家/地区和州/省：
fields:
  - 国家: jurisdiction.country
    input type: combobox
    code: countries_list()
    input type: ajax # 启用AJAX功能，当国家选择改变时触发
  - 州/省: jurisdiction.state
    input type: combobox
    code: states_list(jurisdiction.country) # 此处的代码会在国家改变时重新评估并更新选项
    # 注意：此方法默认不会更新字段的标签文本，如将“州/省”改为“行政区划类型”
---

注意事项

1. 选项更新： 这种方法能够有效地实现依赖字段（如州/省）下拉列表选项的实时更新，无需整个页面刷新，从而提供更流畅的用户体验。
2. 标签限制： input type: ajax 机制主要用于更新字段的选项。对于字段本身的标签（例如，subdivision_type(jurisdiction.country) 生成的文本），此方法默认不提供实时更新能力。若要实现标签的动态更新，通常需要结合自定义的客户端 JavaScript。
3. background_response_choices 补充： Docassemble 文档中提及的 background_response_choices 是一种更细粒度地控制 AJAX 请求返回选项的方式，通常用于当 AJAX 字段本身需要动态生成复杂选项，或者需要对 AJAX 响应进行定制化处理时。在上述国家-州联动的基础场景中，input type: ajax 结合依赖字段的 code 属性通常已足够实现选项的动态更新。

自定义JavaScript实现字段标签动态更新

如果需要根据用户选择动态修改字段的标签（例如，将“州/省”的标签从“州”变为“省”或“行政区划类型”），而 input type: ajax 无法直接满足，则需要编写自定义的客户端 JavaScript 代码。这通常涉及：

1. 监听国家/地区选择字段的 change 事件。
2. 获取用户选择的新值。
3. 根据新值，使用 JavaScript DOM 操作来查找并修改州/省字段的 HTML 标签元素。

这种方法需要一定的前端开发知识，并且可能与 Docassemble 内部生成的 DOM 结构耦合，维护起来可能较为复杂。

方法二：利用 background_response_refresh 实现屏幕整体刷新

另一种实现动态更新的策略是使用 background_response_refresh。当一个字段被标记为 background_response_refresh: True 时，其值发生改变后，整个页面会强制重新加载。这意味着服务器端的所有逻辑（包括字段选项的生成和字段标签的计算）都会重新执行，从而实现全面的动态更新。

实现步骤与代码示例

将国家和州/省选择字段放置在同一个 question 块中，并为作为触发器的国家字段添加 background_response_refresh: True。

---
question: |
  请选择您居住的国家/地区和州/省：
fields:
  - 国家: jurisdiction.country
    input type: combobox
    code: countries_list()
    background_response_refresh: True # 当国家选择改变时，刷新整个页面
  - ${ subdivision_type(jurisdiction.country) }: jurisdiction.state
    input type: combobox
    code: states_list(jurisdiction.country)

以上就是Docassemble中利用AJAX与屏幕刷新实现动态联动下拉列表的详细内容，更多请关注php中文网其它相关文章！