跳转至

Variable-backed layouts（变量驱动布局(Variable-backed layouts)）

Variable-backed layouts allow you to dynamically control the state of layout components using variables. This enables you to build responsive applications where user interface elements react to user interactions, object properties, or custom logic defined in functions.

The following layout components support variable backing:

  • Pages: Control which page is displayed in a multi-page module
  • Sections: Control visibility and collapse state
  • Tabs: Control which tab is selected
  • Overlays: Control whether an overlay is open or closed

Variable-backed page selection

You can bind a string variable to a multi-page module to control which page is displayed. When the variable value matches a page's ID, that page becomes active.

To configure variable-backed page selection:

  1. Open the module settings panel from the left side bar in edit mode.
  2. In the configuration panel under Pages, locate the Variable-backed page selection setting.
  3. Select a string variable to control the displayed page.
  4. For each page, set a unique Page ID that matches the values your variable will contain.

This feature is useful for deep linking to specific pages through URL parameters, navigating between pages based on user actions, or controlling page selection from parent modules through interface variables.

:::callout{theme="neutral"} Layout events that switch pages do not update the value of the variable configured for variable-backed page selection. To keep the variable in sync with page changes triggered by events, use a set variable value event instead. :::

Variable-backed section conditional visibility

You can bind a Boolean variable to a section to control whether it is visible or hidden. By default, the section is hidden when the variable evaluates to true and visible when it evaluates to false. You can invert this default behavior by changing the Boolean selector to the right of the variable selection.

To configure variable-backed section visibility:

  1. Select the section in your module.
  2. Locate and toggle on the Conditional Visibility setting.
  3. In the configuration panel, locate the Hide section if setting.
  4. Select a Boolean variable to control the section visibility.
  5. Optionally, configure the section to hide when the Boolean variable is false.

This differs from the collapse state feature in that hidden sections do not appear in the layout at all, whereas collapsed sections still show their headers and can be expanded by users. Events will not be offered to update section visibility. Use set variable value events instead.

Variable-backed section collapse state

You can bind a Boolean variable to a collapsible section to control whether it is expanded or collapsed. When the variable evaluates to true, the section is collapsed. When it evaluates to false, the section is expanded.

To configure variable-backed collapse state:

  1. Select the section in your module.
  2. In the configuration panel, enable the Collapsible setting.
  3. Locate the Variable-backed collapse state setting and select a Boolean variable.

This feature is useful for expanding sections only when relevant data is present, or for coordinating the expand and collapse behavior of multiple sections.

:::callout{theme="neutral"} Layout events that expand, collapse, or toggle sections do not update the value of the variable configured for variable-backed collapse state. To keep the variable in sync with section state changes triggered by events, use a set variable value event instead. :::

Variable-backed overlay open state

You can bind a Boolean variable to an overlay to control whether it is open or closed. When the variable evaluates to true, the overlay opens. When it evaluates to false, the overlay closes.

To configure variable-backed overlay state:

  1. Select the overlay in your module.
  2. In the configuration panel, locate the Variable-backed open state setting.
  3. Select a Boolean variable to control the overlay state.

This feature is useful for opening overlays in response to events, controlling overlay state from parent modules through interface variables, or coordinating multiple overlays.

:::callout{theme="neutral"} Layout events that open or close overlays will update the value of the variable configured for variable-backed open state. You can also configure an On close event to reset an upstream variable or perform other actions when the overlay is closed. :::

Variable-backed selected tab

You can bind a string variable to a tab container to control which tab is currently selected. When the variable value matches a tab's ID, that tab becomes active. This works bidirectionally: selecting a tab updates the variable, and changing the variable selects the corresponding tab.

To configure variable-backed tab selection:

  1. Select the tab container in your module.
  2. In the configuration panel, locate the Variable-backed tab selection setting.
  3. Select a string variable to control the selected tab.
  4. For each tab, set a unique Tab ID that matches the values your variable will contain.

This feature is useful for synchronizing tab state across multiple tab containers, persisting the selected tab in the URL through a module interface variable, or programmatically changing tabs based on user actions elsewhere in the module.

:::callout{theme="neutral"} Unlike page selection and section collapse state, layout events that change the selected tab will also update the value of the variable configured for variable-backed tab selection. :::

中文翻译

变量驱动布局(Variable-backed layouts)

变量驱动布局允许您使用变量动态控制布局组件的状态。这使您能够构建响应式应用程序，其中用户界面元素能够响应用户交互、对象属性或函数中定义的自定义逻辑。

以下布局组件支持变量驱动：

  • 页面(Pages): 控制多页面模块中显示哪个页面
  • 分区(Sections): 控制可见性和折叠状态
  • 标签页(Tabs): 控制选中哪个标签页
  • 覆盖层(Overlays): 控制覆盖层是打开还是关闭

变量驱动页面选择(Variable-backed page selection)

您可以将字符串变量绑定到多页面模块，以控制显示哪个页面。当变量值与页面的ID匹配时，该页面将变为活动状态。

配置变量驱动页面选择的步骤：

  1. 在编辑模式下，从左侧边栏打开模块设置面板。
  2. 在配置面板的页面(Pages)下，找到变量驱动页面选择(Variable-backed page selection)设置。
  3. 选择一个字符串变量来控制显示的页面。
  4. 为每个页面设置唯一的页面ID(Page ID)，该ID应与变量将包含的值匹配。

此功能对于通过URL参数深度链接到特定页面、根据用户操作在页面之间导航，或通过接口变量从父模块控制页面选择非常有用。

:::callout{theme="neutral"} 切换页面的布局事件(Layout events)不会更新为变量驱动页面选择配置的变量值。要使变量与事件触发的页面更改保持同步，请改用设置变量值(set variable value)事件。 :::

变量驱动分区条件可见性(Variable-backed section conditional visibility)

您可以将布尔变量绑定到分区，以控制其是可见还是隐藏。默认情况下，当变量求值为true时分区隐藏，求值为false时可见。您可以通过更改变量选择右侧的布尔选择器来反转此默认行为。

配置变量驱动分区可见性的步骤：

  1. 在模块中选择分区。
  2. 找到并开启条件可见性(Conditional Visibility)设置。
  3. 在配置面板中，找到如果满足以下条件则隐藏分区(Hide section if)设置。
  4. 选择一个布尔变量来控制分区可见性。
  5. 可选地，配置分区在布尔变量为false时隐藏。

此功能与折叠状态功能的不同之处在于，隐藏的分区完全不会出现在布局中，而折叠的分区仍会显示其标题，并且用户可以展开。事件不会提供更新分区可见性的功能。请改用设置变量值(set variable value)事件。

变量驱动分区折叠状态(Variable-backed section collapse state)

您可以将布尔变量绑定到可折叠分区，以控制其是展开还是折叠。当变量求值为true时，分区折叠。当求值为false时，分区展开。

配置变量驱动折叠状态的步骤：

  1. 在模块中选择分区。
  2. 在配置面板中，启用可折叠(Collapsible)设置。
  3. 找到变量驱动折叠状态(Variable-backed collapse state)设置并选择一个布尔变量。

此功能适用于仅在存在相关数据时展开分区，或协调多个分区的展开和折叠行为。

:::callout{theme="neutral"} 展开、折叠或切换分区的布局事件(Layout events)不会更新为变量驱动折叠状态配置的变量值。要使变量与事件触发的分区状态更改保持同步，请改用设置变量值(set variable value)事件。 :::

变量驱动覆盖层打开状态(Variable-backed overlay open state)

您可以将布尔变量绑定到覆盖层，以控制其是打开还是关闭。当变量求值为true时，覆盖层打开。当求值为false时，覆盖层关闭。

配置变量驱动覆盖层状态的步骤：

  1. 在模块中选择覆盖层。
  2. 在配置面板中，找到变量驱动打开状态(Variable-backed open state)设置。
  3. 选择一个布尔变量来控制覆盖层状态。

此功能适用于响应事件打开覆盖层、通过接口变量从父模块控制覆盖层状态，或协调多个覆盖层。

:::callout{theme="neutral"} 打开或关闭覆盖层的布局事件(Layout events)将更新为变量驱动打开状态配置的变量值。您还可以配置关闭时(On close)事件，以在覆盖层关闭时重置上游变量或执行其他操作。 :::

变量驱动选中标签页(Variable-backed selected tab)

您可以将字符串变量绑定到标签页容器，以控制当前选中的是哪个标签页。当变量值与标签页的ID匹配时，该标签页变为活动状态。这是双向工作的：选择标签页会更新变量，而更改变量则会选中相应的标签页。

配置变量驱动标签页选择的步骤：

  1. 在模块中选择标签页容器。
  2. 在配置面板中，找到变量驱动标签页选择(Variable-backed tab selection)设置。
  3. 选择一个字符串变量来控制选中的标签页。
  4. 为每个标签页设置唯一的标签页ID(Tab ID)，该ID应与变量将包含的值匹配。

此功能适用于同步多个标签页容器的标签页状态、通过模块接口变量将选中的标签页持久化到URL中，或根据模块中其他位置的用户操作以编程方式更改标签页。

:::callout{theme="neutral"} 与页面选择和分区折叠状态不同，更改选中标签页的布局事件(Layout events)也会更新为变量驱动标签页选择配置的变量值。 :::