使用 Trajectory List Box 3D 节点

使用 Trajectory List Box 3D 节点可在 3D 空间中创建沿轨迹排列的项的可滚动列表。

Kanzi Studio 提供多种类型的轨迹。当您需要不同类型的轨迹时，请在第三方工具中创建样条轨迹并将其导入到您的 Kanzi Studio 项目中。请参阅 轨迹 (Trajectories)。

Trajectory List Box 3D 节点中的项目按照您将它们添加到 Trajectory List Box 3D 节点的顺序显示。要在 Trajectory List Box 3D 节点中选择一个项目，请单击或点击该项目。

轨迹的大小定义了点击和拖动手势的交互区域。如果轨迹太小，用户将无法选择 Trajectory List Box 3D 节点中的项目。为避免这种情况，确保轨迹足够大。请参阅 轨迹 (Trajectories)。

您在 Kanzi Studio 中创建的 Trajectory List Box 3D 节点默认情况下是焦点范围，并处理键焦点和键输入。请参阅 在 List Box 节点中处理键焦点。。

备注

所有列表框节点（Grid List Box 节点和 Trajectory List Box 3D 节点）中的项目都不是其子节点，即使在 Kanzi Studio 中，当您向列表框添加项目时看起来是这样。因为列表框项目不是列表框的子节点，所以您无法使用路径或别名从列表框外部引用这些项目。如果您需要从列表框项目引用列表框外部的对象，请使用绑定和别名。请参阅 绑定到 Grid List Box 节点之外的属性 和 从 Trajectory List Box 3D 节点导航到 Page 节点。。

Trajectory List Box 3D 节点是 Trajectory Layout 3D 节点的交互版本。请参阅 使用 Trajectory Layout 节点。

有关如何使用 Trajectory List Box 3D 节点创建交互式可滚动项目列表的示例，请参阅 轨迹列表框示例。

创建一个 Trajectory List Box 3D 节点

要创建 Trajectory List Box 3D 节点：

1. 在 Node Tree 中，按 Alt 并右键单击 您要创建 Trajectory List Box 3D 节点的 3D 节点，并选择 Trajectory List Box 3D。

   例如，在 Scene 节点中创建一个 Trajectory List Box 3D 节点。

   

   小技巧

   要查看轨迹，在 Preview 中单击 以进入 Analyze 模式，右键单击 ，然后选择 Debug objects。

   

2. 在 Node Tree 中，将项目添加到 Trajectory List Box 3D 节点。

   使用数据源向 List Box 节点添加项目。请参阅 使用数据源。

   例如，要创建相册列表，请添加多个代表列表中相册的节点。请参阅 使用 List Box Item Container 预设。

   当您添加项目时，Trajectory List Box 3D 节点会将它们沿着 Trajectory List Box 3D 节点使用的轨迹排列。

   要浏览 Trajectory List Box 3D 节点中的项目，在 Preview 中，点击并拖动 Trajectory List Box 3D 节点中的项目。

   

3. （可选）

   Kanzi Studio 默认情况下创建并使用圆形轨迹。您可以使用角度、弧、圆、椭圆、直线、矩形、螺旋、样条或梯形轨迹。请参阅 轨迹 (Trajectories)。

微调 Trajectory List Box 3D 节点的机制

您可以微调 Trajectory List Box 3D 节点的机制。您可以将列表框设置为：

• 将选定的项目移到列表框的中心。

  要设置列表框在用户单击该项目时将项目带到列表框对象的中心，请将 Selection Behavior 属性设置为 Bring Center。使用 Cursor Offset 属性设置选择在列表框中移动项目的方向。使用 Cursor Offset 属性设置选择在列表框中移动项目的方向。

  

• 在到达最后一个项目后从头开始显示项目。

  要在到达最后一个项目后从头开始显示 Trajectory List Box 3D 中的项目，请启用 Looping 属性。

  

• 使用 x 轴或 y 轴滚动列表框中的项目。

  要设置滚动轴，请设置 Allowed Scroll Axis 属性。

  例如，要设置列表框使用户可沿 y 轴滚动浏览项目，将 Allowed Scroll Axis 属性设置为 Y axis。

• 反转滚动方向。

  要反转用户单击并拖动项目时列表框滚动的方向，请添加并启用 Reversed Scrolling 属性。

• 根据项目在轨迹上的位置更改其外观。

  要设置项目在轨迹上不同点的外观，请使用 Item Area Begin 和 Item Area End 属性。您使用 Item Area Begin 和 Item Area End 属性来设置 Visible Amount In Parent 属性的值，该属性设置着色器以根据对象在列表框中的位置更改项目的外观。

  例如，如果您使用 Visible Amount In Parent 属性逐渐改变项目的可见性，请将 Item Area Begin 属性设置为较大值，并将 Item Area End 属性设置为较小值。这样，您可以限制该项目的可见区域。

嵌套 Trajectory List Box 3D 节点

您可以嵌套 Trajectory List Box 3D 节点，以在 Trajectory List Box 3D 节点中创建一个 Trajectory List Box 3D 节点，每个节点都可以独立滚动。例如，您可以创建一个 Trajectory List Box 3D，用于在圆形轨迹上滚动包含专辑集的 Trajectory Layout 3D 节点。

在 Trajectory List Box 3D 节点中，使用 Allowed Scroll Axis 属性设置用户可以滚动列表的轴。

要嵌套 Trajectory List Box 3D 节点：

1. 创建一个 Trajectory List Box 3D 节点。请参阅 创建一个 Trajectory List Box 3D 节点。

   例如，使用圆形轨迹创建圆形路径。请参阅 使用 circle trajectories。

   

2. 选择您在上一步中创建的 Trajectory List Box 3D 节点。在 Properties 中，将 Allowed Scroll Axis 属性设置为您希望该节点滚动的轴。

   例如，要将 Trajectory List Box 3D 节点设置为在 x 轴上滚动，请将 Allowed Scroll Axis 属性设置为 X axis。

   

3. 创建您要嵌套在上一步中创建的 Trajectory List Box 3D 节点中的 Trajectory List Box 3D 节点。

   例如，如果要创建多个嵌套的 Trajectory List Box 3D 节点的相册：

   1. 在 Prefabs 中，创建一个 Trajectory List Box 3D 节点。

      Trajectory List Box 3D 节点默认情况下将其项沿圆形轨迹排列。

   2. 在 Properties 中，将 Allowed Scroll Axis 属性设置为 X axis。

   

4. 在 Node Tree 中，将项目添加到 Trajectory List Box 3D 节点。

   例如，从 Prefabs 中拖动几个表示专辑列表的 Trajectory List Box 3D 预设。在每个嵌套的 Trajectory List Box 3D 节点中，添加表示每个列表中专辑的项目。

   您可以使用数据源向 Trajectory List Box 3D 添加项目。请参阅 使用数据源。

   

绑定到 Trajectory List Box 3D 节点之外的属性

要将列表框项的属性绑定到列表框外的节点的属性，应使用别名。

例如，如果您有一个 Grid List Box 3D 或一个 Trajectory List Box 3D 节点，其中包含一个 Text Block 3D 节点项，并且想要将 Text Block 3D 节点的 Text 属性值设置为不在列表框中的 Empty Node 3D 节点属性的值：

1. 在 Node Tree 按 Alt 并右键单击 中，包含您要绑定的属性的节点并选择 Alias。请参阅 使用别名。

   例如，为 Empty Node 3D 节点创建一个别名。

2. 在 Dictionaries 确保将您创建的别名放在列表框节点可以访问的资源字典中。

   例如，将所有别名放置到 Screen 节点的资源字典中，或者在列表框节点中创建一个资源字典，并将别名放置到该资源字典中。请参阅 使用资源字典。

3. 创建绑定：

   1. 在 Node Tree 中，选择列表框节点内的节点，该节点是您要绑定到列表框节点外部的节点。

   2. 在 Properties 中，点击 + Add Binding，并使用别名创建绑定，以绑定到列表框节点外部节点中的属性。

      例如：在 Text Block 3D 节点中，使用您在第一步中创建的别名创建到 Empty Node 3D 节点的绑定。请参阅 Bindings expressions 参考。

      例如，使用以下绑定表达式：

      {#Empty Node 3D/TextConcept.Text}
      

      Text Block 3D 节点中的 Text 属性获取 Empty Node 3D 节点中的 Text 属性的值。

   3. 单击 Save。

从 Trajectory List Box 3D 节点导航到 Page 节点。

当您想从列表框节点内的节点导航到 Page 节点时，请使用别名。例如，如果您使用 Grid List Box 或 Trajectory List Box 3D 节点创建地址簿，并希望在 Page 节点中显示地址簿条目的内容。

要从列表框节点导航到 Page 节点：

1. 在 Node Tree 按 Alt 并右键单击 中，导航到每个您要导航到的 Page 节点并选择 Alias。Kanzi Studio 创建一个指向您创建它的节点的别名，并将该别名放置到最近的资源字典中。

   

2. 在 Dictionaries 确保将您创建的别名放在列表框节点可以访问的资源字典中。

   例如，将所有别名放置到 Screen 节点的资源字典中，或者在列表框节点中创建一个资源字典，并将别名放置到该资源字典中。请参阅 使用资源字典。

   

3. 添加并设置 Navigate to Page 操作：

   1. 在 Node Tree 中的列表框节点中，选择包含您要使用的触发器以导航到您在第一步中创建别名的 Page 节点之一的节点。

      

   2. 在 Node Components > Triggers 按 Alt 并右键单击 中，使用您要用于导航到 Page 节点的触发器，并创建一个 Navigate to Page 操作。

      

   3. 在 Navigate to Page 操作中，将 Target Item 属性设置为您要导航到的 Page 节点的别名。

      所有别名都以 ＃ 号开头。

      

在 Preview 中，当您单击包含 Navigate to Page 操作的节点时，您将激活在该操作中选择的 Page 节点。

当用户与 Trajectory List Box 3D 节点交互时做出反应。

使用 List Box 触发器在用户与 Trajectory List Box 3D 节点交互时做出反应。例如，您可以在用户滚动该列表框时设置 Trajectory List Box 3D 的外观。

您可以将这些 List Box 触发器与 Trajectory List Box 3D 节点一起使用：

名称 (Name)	描述 (Description)
List Box: Item Hidden	当列表框节点中的项目从工作内存中卸载时，List Box: Item Hidden 触发器被触发。 要设置您想要一次加载多少个项到工作内存，使用 Keep Alive Item Count 属性。
List Box: Item Selected	当用户在列表框中选择一个项目时，List Box: Item Selected 触发器被激活。
List Box: Item Visible	当列表框中的一个项目被创建并加载到工作内存时，List Box: Item Visible 触发器被触发。 要设置您想要一次加载多少个项到工作内存，使用 Keep Alive Item Count 属性。
List Box: Scroll Finished	当列表框滚动结束时，List Box: Scroll Finished 触发器被触发。
List Box: Scroll Started	当列表框开始滚动时，List Box: Scroll Started 触发器被激活。
List Box: Scrolled	每当列表框滚动时，List Box: Scrolled 触发器都会被设置。
List Box: Target Changed	当列表框的滚动目标更改时，List Box: Target Changed 触发器被激活。 例如，当用户选择列表框项时，滚动目标会发生变化，并且列表框会滚动以将该项移至列表框区域的中心。
List Box: User Scroll Finished	当用户停止滚动列表框时，List Box: User Scroll Finished 触发器被激活。
List Box: User Scroll Started	当用户开始滚动列表框时，List Box: User Scroll Started 触发器被激活。

要使用 List Box 触发器与 Trajectory List Box 3D 节点：

1. 创建一个 Trajectory List Box 3D 节点并向其添加项目。请参阅 创建一个 Trajectory List Box 3D 节点。

   

2. 定义您想通过 List Box 触发器设置的行为。

   例如，创建一个状态管理器，在其中定义状态，以在 List Box: Scroll Started 和 List Box: Scroll Finished 触发器被触发时设置 Trajectory List Box 3D 节点的外观。请参阅 创建状态机。

3. 添加和配置 List Box 触发器：

   1. 在 Node Tree 中，选择您要添加触发器的 List Box 节点。在 Node Components > Triggers 中，创建一个 List Box 触发器。

      例如：在 Node Tree 中，选择您在此过程开始时创建的 Trajectory List Box 3D 节点。在 Node Components 中，按 Alt 并右键单击 Triggers，并选择 Message Trigger > List Box > Scroll Started。

      

   2. 在 Node Components 中，按 Alt 并右键单击 您在上一步中创建的触发器，选择一个操作并进行配置。

      例如，选择 State Manager: Go to State 操作。在操作中，将 State 属性设置为在 List Box: Scroll Started 触发器关闭时设置 Trajectory List Box 3D 节点外观的状态。

      

4. 重复上一步，以添加并配置更多 List Box 触发器。

   例如，添加 List Box: Scroll Finished 触发器。在触发器的 State Manager: Go to State 操作中，将 State 设置为在触发器被触发时设置节点外观的状态。

在 Preview 中，当您滚动创建的 Trajectory List Box 3D 节点时，您添加的触发器将被触发。

控制 Trajectory List Box 3D 节点是否在使用中

要控制 Trajectory List Box 3D 节点是否在使用中，请使用 Input > Enabled 属性。禁用的 Trajectory List Box 3D 节点不会对用户输入做出反应。当您禁用 Trajectory List Box 3D 节点时，Kanzi 会停止正在进行的手势，并保留该 Trajectory List Box 3D 节点的选定项和滚动位置。

当您禁用节点的 Enabled 属性时，您实际上禁用了该节点及其在同一覆盖焦点范围内的子节点。

要观察节点是否有效启用，使用状态管理器或绑定中的 Input > Effectively Enabled 属性。例如，要向用户直观地指示节点是否正在使用，创建一个状态管理器并使用 Effectively Enabled 属性作为其控制器属性。

请参阅 控制节点对输入的反应方式。

为 Trajectory List Box 项启用双击手势

当您向 List Box 节点添加支持双击手势的项目时，必须在 List Box Item Container 预设中为这些项目启用双击手势。

要了解如何为节点启用双击手势，请参阅 为节点启用多击手势。

要为 List Box 项启用双击手势：

1. 创建一个 List Box Item Container 预设，并将其设置为 List Box 节点的 Item Container Template。请参阅 创建 List Box Item Container 预设。

2. 在 Prefabs 中，选择 List Box Item Container 预设。在 Properties 中，添加并启用 Input > Double-Click Enabled 属性。

   当您启用 Double-Click Enabled 属性时，Kanzi 在 List Box Item Container 预设中安装一个可生成双击消息的多击操纵器。

   

轨迹列表框示例

此示例展示了使用 Trajectory List Box 3D 节点创建交互式可滚动项目列表。该示例实现了一个简单的照片库，并使用动画实现选择效果。

Trajectory List Box 3D 节点、其 Circle Trajectory、在 Trajectory List Box 3D 中显示的内容以及突出显示居中照片的动画是在 Kanzi Studio 中创建的。启动高亮动画的时间点是根据滚动速度和从轨迹列表框组件生成的用户输入事件中可用的聚焦项目数据来定义的。

示例中的 Trajectory List Box 3D 节点使用了这些功能：

• Looping。您可以将 Trajectory List Box 3D 节点中的项目限制在定义的轨迹起点和终点之间，或在起点和终点位置之间过渡，如本示例中所示，使用 Looping 属性。

• Trajectory。要使用 Trajectory List Box 3D 的轨迹，您需要在 Library > Trajectories 中创建它。您可以在 Kanzi Studio 中创建圆形和直线轨迹。要使用样条轨迹，请在第三方工具中创建样条，导入并将样条添加为 Spline Trajectory。请参阅 使用 circle trajectories、使用线轨迹 和 使用样条轨迹。您可以通过添加和设置轨迹属性（例如 Item Area Begin、Item Area End、Cursor Offset 和 Override Distance）来自定义轨迹。

• 选择和目标行为。选择和目标事件是分别处理的。当用户释放指针时，会生成目标更改消息。它包含有关通过当前轨迹运动移至中心的项目的信息。当用户通过点击或轻触选择一个项目时，会生成选择消息。您可以在 Kanzi Studio 中选择 Bring Center 选择行为。您可以通过为 List Box: Target Changed 或 List Box: Item Selected 触发器设置调用的操作，为 Trajectory List Box 3D 的任何成员，甚至是轨迹列表框组件本身，定义更多的目标和选择事件操作。

获取示例

要获取该示例，请在 Kanzi Studio 的 Quick Start 窗口中点击 Examples。在 Trajectory_list_box 示例旁点击 。

Kanzi Studio 会将该示例下载到 <KanziWorkspace>/Examples/Trajectory_list_box 目录。

在 API 中使用 Trajectory List Box 3D 节点

要创建 Trajectory List Box 3D 节点：

// Create a Trajectory List Box 3D named MyListBox.
TrajectoryListBox3DSharedPtr trajectoryListBox = TrajectoryListBox3D::create(domain, "MyListBox");

要设置您希望 Trajectory List Box 3D 节点使用的轨迹：

// Create a circle trajectory named Circle with radius of 4 device independent units.
TrajectorySharedPtr trajectory = Trajectory::createCircle(Vector3(), Vector3::positiveY(), 0.0f, 4.0f, domain, "Circle");

// Set the list box to use the trajectory.
trajectoryListBox->setTrajectory(trajectory);
// Increase the layout size to cover the whole trajectory.
trajectoryListBox->setWidth(10.0f);
trajectoryListBox->setDepth(10.0f);
trajectoryListBox->setHeight(3.0f);

要将项添加到 Trajectory List Box 3D 节点：

// Create cube meshes and add them as items of the Trajectory List Box 3D node.
// Items on the trajectory appear in the order that you add them to the Trajectory List Box 3D node.
Model3DSharedPtr item1 = Model3D::createCube(domain, "item1", 1.0f, ThemeRed);
Model3DSharedPtr item2 = Model3D::createCube(domain, "item2", 1.0f, ThemeGreen);
Model3DSharedPtr item3 = Model3D::createCube(domain, "item3", 1.0f, ThemeBlue);
Model3DSharedPtr item4 = Model3D::createCube(domain, "item4", 1.0f, ThemeOrange);
Model3DSharedPtr item5 = Model3D::createCube(domain, "item5", 1.0f, ThemeYellow);
trajectoryListBox->addItem(item1);
trajectoryListBox->addItem(item2);
trajectoryListBox->addItem(item3);
trajectoryListBox->addItem(item4);
trajectoryListBox->addItem(item5);

要使 Trajectory List Box 3D 节点循环其项目：

// Make the Trajectory List Box 3D node to loop. All items fit to the trajectory so that they are positioned evenly.
trajectoryListBox->setLooping(true);

要设置 Trajectory List Box 3D 节点对项目选择的反应方式：

// Make clicking items bring them to the center of the trajectory.
trajectoryListBox->setSelectionBehavior(ListBoxConcept::SelectionBehaviorBringToCenter);
// Change the position where the clicked items are brought to be one quarter from the beginning of the trajectory.
trajectoryListBox->setCursorOffset(0.25f);

有关详细信息，请参阅 TrajectoryListBox3D 类。

Trajectory List Box 3D 属性类型

有关 Trajectory List Box 3D 节点可用属性类型的列表，请参阅 Trajectory List Box 3D。

另请参阅

使用 Grid List Box 节点

使用 Trajectory Layout 节点

使用角度轨迹

使用弧形轨迹

使用 circle trajectories

使用椭圆轨迹

使用线轨迹

使用矩形轨迹

使用螺旋轨迹

使用样条轨迹

使用梯形轨迹

轨迹 (Trajectories)

使用 List Box Item Container 预设

焦点

使用绑定