列表框节点 (List Box nodes)¶
使用 List Box 节点在可滚动列表中排列项目。例如，使用 List Box 节点创建联系人列表、媒体播放器中的专辑列表或汽车设置列表。虽然布局控制节点将其项目排列在静态布局中，但 List Box 节点将其项目排列在一个列表中，用户一次只能看到一定数量的项目。要访问更多项目，用户需要滚动列表框。请参阅 布局控制节点。
使用 Grid List Box 节点可用于创建以网格形式排列的项的可滚动列表。 了解网格列表框节点 (Grid List Box nodes) > 
|
使用 Trajectory List Box 3D 节点可在 3D 空间中创建沿轨迹排列的项的可滚动列表。 了解 3D 轨迹列表框 (Trajectory List Box 3D) 节点 > 
|
使用 List Box Item Container 预设更改列表框中当前选定项的外观。 了解列表框项容器 (List Box Item Container) 预设件 > 
|
设置可见区域的大小¶
要设置 List Box 节点中项的可见区域的大小，使用以下属性：
Layout Height 用于设置 Grid List Box 或 Trajectory List Box 3D 节点的可见区域的高度。
Layout Width 用于设置 Grid List Box 或 Trajectory List Box 3D 节点可见区域的宽度。
Layout Depth 用于设置 Trajectory List Box 3D 节点可见区域的深度。
选择一个项并定义其选择行为¶
您可以设置选中 List Box 节点中的哪个项，以及用户选中项时项如何反应。例如，您可以将选中的项移到列表框可见区域的中心。
要设置列表框中哪个项目被选中，使用 Selected Item Index 属性。索引从 0 开始。
要使用绑定更新 Selected Item Index 属性的值，请使用到源或双向绑定。Kanzi 在内部会覆盖任何针对 Selected Item Index 属性的单向绑定。请参阅 绑定 (Bindings)。
例如，您可以通过单击该项目或使用滑块来使用户能够在 List Box 节点中选择一个项目。请参阅 创建双向绑定。
要设置列表框，使用户选择某个项目时将其移至列表框区域的中心，请使用 Selection Behavior 属性。请参阅 将选定的项放到 Grid List Box 中心 和 使用 Trajectory List Box 3D 节点。
访问项目的数量和位置¶
要获取 List Box 节点中项目的数量和位置，请使用这些只读属性：
List Box > Item Count 以获取列表框中的项目数量，包括虚拟项目。
例如，使用 Item Count 属性设置用户可以使用的 Slider 的最大值，以：
在 List Box 节点中选择一个项目。请参阅 创建双向绑定。
滚动一个 Grid List Box 节点。请参阅 使用滑块滚动 Grid List Box 节点。。
List Box Item Container > Item Index 以获取列表框中项目的位置。索引从 0 开始。
例如，使用 Item Index 属性在绑定中设置列表框项的外观，基于其与所选项的距离。使用 List Box > Selected Item Index 属性获取所选项的索引。您可以使用此方法来减小距离所选项较远的项的大小和不透明度。
为 List Box 节点定义项目¶
您可以定义列表框项的内容来源以及如何呈现这些内容。例如，您可以使用设置每个项目外观的项目模板，并从数据源获取项目的数据。请参阅 使用数据源。
要设置为 List Box 节点中的项目提供数据的数据对象，请使用 Items Source 属性。请参阅 使用列表数据对象。
要设置您希望 List Box 节点为其列表中的项目使用哪个预设模板，请使用 Item Template 属性。请参阅 使用列表数据对象。
要在列表框中的项目之间共享功能，使用 Item Container Template 属性。当您设置 Item Container Template 属性时，列表框中的每个项目都会从 List Box Item Container 预设继承功能。例如，Item Container Template 可以包含一个状态管理器，该管理器会更改列表框中所选项目的缩放比例。这样，您无需为每个项目设置功能。请参阅 使用 List Box Item Container 预设。
要设置您想要一次加载多少个项到工作内存，使用 Keep Alive Item Count 属性。
在 Keep Alive Item Count 属性中设置的值越小，释放用于其他任务的工作内存就越多。如果快速滚动列表框，这可能会导致项目在列表框中出现延迟。
控制 List Box 节点是否在使用中¶
要控制 List Box 节点是否在使用中，请使用 Input > Enabled 属性。禁用的 List Box 节点不会对用户输入做出反应。当您禁用 List Box 节点时，Kanzi 会停止正在进行的手势，并保留该 List Box 节点的选定项和滚动位置。
当您禁用节点的 Enabled 属性时，您实际上禁用了该节点及其在同一覆盖焦点范围内的子节点。
要观察节点是否有效启用，使用状态管理器或绑定中的 Input > Effectively Enabled 属性。例如，要向用户直观地指示节点是否正在使用，创建一个状态管理器并使用 Effectively Enabled 属性作为其控制器属性。
请参阅 控制节点对输入的反应方式。
在 List Box 节点中处理键焦点。¶
您在 Kanzi Studio 中创建的 List Box 节点默认情况下将 Focus Scope Type 属性设置为 Group。这意味着 List Box 节点默认情况下是焦点范围，并处理键焦点和键输入。请参阅 焦点。
您可以导航每个列表项中的可聚焦列表项和可聚焦节点：
在前进方向上按下 Tab 键。
在向后方向上，通过按下 BackTab 键或 Shift Tab 键。
当您在列表项中的任何节点中启用 Focus > Focusable 属性时，您使这些节点可以聚焦并使其能够接收键输入。
这些节点启用了 Focusable 属性，并且默认情况下可以接收焦点：
您使用 Kanzi Engine API 或 Kanzi Studio 创建的 Button、Toggle Button、Slider 和 Text Box 节点。
使用 Kanzi Studio 创建的 Scroll View 节点。
默认情况下，Kanzi 会同步 List Box 节点中的项目选择和键焦点，以便：
如果应用程序的关键焦点在 List Box 节点中，并且该 List Box 中的一个可聚焦项目被选中，则该项目将获得关键焦点。
请注意，虚拟化列表项无法获得焦点。
小技巧
要将键焦点从应用程序中的任何位置移动到用户按下的节点，可以使用 Focus > Focus On Press 属性。请参阅 将焦点设置到用户按下的节点上。。
当键焦点移动到列表项时，Kanzi 将该列表项设置为选中。
例如，该视频演示了一个示例 Grid List Box 2D 节点，该节点显示了一系列安全控制设置。每个列表项包含一个 Toggle Button 节点和一个 Button 节点，显示信息图标。灰色轮廓可视化具有键焦点的节点。要了解如何更改用户界面元素在获得焦点时的外观，请参阅 表明用户界面元素何时具有焦点。
当用户浏览列表时：
当应用程序的关键焦点在 List Box 节点中，并且用户按下 Tab 键时，Kanzi 会将焦点移动到列表项中的可聚焦节点。 从列表项中的最后一个可聚焦节点，焦点移动到下一个列表项，Kanzi 将其设置为选中。
如果 List Box 节点的 Selection Behavior 属性设置为 Bring Center，Kanzi 会将选定的项目带到列表框区域的中心。
当用户单击列表项以选择它时，Kanzi 将键焦点设置为该项中第一个可聚焦的节点，用户可以通过键输入与该节点交互。
例如，用户可以按下 Enter 键来切换 Toggle Button 或按下 Button。
列表框触发器¶
使用 List Box 触发器在用户与 List Box 节点交互时做出反应。例如，您可以在用户滚动该节点时设置 List Box 节点的外观。请参阅 当用户与 Grid List Box 节点交互时做出反应。 和 当用户与 Trajectory List Box 3D 节点交互时做出反应。。