独占活动主机

一个 Exclusive Activity Host 一次只能激活其一个子活动。当一个 Exclusive Activity Host 的子活动处于活动状态时，该活动主机的所有其他活动都处于非活动状态。例如，您可以使用一个 Exclusive Activity Host 在应用程序中切换视图。

使用 Exclusive Activity Host

要使用 Exclusive Activity Host：

1. 在 Activity Browser 中，点击 并创建根 Exclusive Activity Host。

   Kanzi Studio 创建一个 Exclusive Activity Host 作为 Screen 节点的第一个子节点。

   

2. 在 Activity Browser 中，在根 Exclusive Activity Host 下，点击 ，选择 Create Activity，并创建或分配一个预设到该 Activity。

   例如，创建名为 Media、Navigation 和 Phone 的活动。对于每个活动，使用相同的名称作为活动预设。

   Kanzi Studio 创建活动，将其分配给独占活动主机，并为每个活动在 Prefabs 中创建一个预设。

   在 Activity Browser 中，每个活动都有一个预设。在 Activity Browser 中，当您添加 Activity 时，您可以选择一个现有的预设或为您的活动创建一个预设。您只能选择属于 Activity 节点类型的预设。

   您在 Activity Browser 中添加的活动不是应用程序节点树中的节点。它们只是 Kanzi 在您激活这些活动后创建的结构的可视化。

   

3. 创建一个属性类型，您可以在 Exclusive Activity Host 中使用该属性类型来控制哪个 Activity 处于活动状态：

   1. 在 Activity Browser 中，右键单击 Exclusive Activity Host，选择 Create Controller Property，然后选择属性类型的数据类型。

      Exclusive Activity Host 使用 Controller Property 属性来设置和控制在该 Exclusive Activity Host 中哪个 Activity 处于活动状态。要更改 Activity 的状态，您还可以使用：

      • 具有 Activate Activity 消息的任何触发器

      • 具有 Apply Activation 操作的 Data Trigger。

      例如，选择 Create Controller Property > Enum 以创建具有枚举数据类型的属性类型。

      

   2. 命名属性类型，然后单击 OK。

      例如，将属性类型命名为 MyActivities。

      

      Kanzi Studio：

      1. 创建该属性类型。

         当您创建具有枚举数据类型的属性类型时，Kanzi Studio 会创建一个属性类型，其中枚举键的名称来自该 Exclusive Activity Host 的 Activities。

         

      2. 在 Exclusive Activity Host 中，添加创建的属性类型并将 Controller Property 属性设置为创建的属性类型。

         要设置哪个 Activity 在此 Exclusive Activity Host 中处于活动状态，您可以在 Exclusive Activity Host 中设置创建的属性类型的值。

         

4. 在 Prefabs 中，向每个 Activity 预设中添加内容。

   例如：在每个 Activity 中创建一个名为该 Activity 的 Image 节点。

   

5. 在 Activity Browser 中，将 Controller Property 属性设置为您要激活的 Activity。

   Activity Browser 在您的应用程序中模拟 Activities 的激活。要在您的 Kanzi 应用程序中激活 Activities，使用触发器和动作。请参阅 激活活动。

   当您激活一个活动时，Kanzi：

   1. 使用其预设创建一个 Activity 节点。

   2. 将 Activity 节点附加到节点树。

   3. 使活动可见。

   4. 如果活动主机具有按键焦点且未进行其他配置，则将按键焦点设置为活动。控制是否将焦点设置到激活的 Activity。。

   5. 将 Activity 的 Activity Status 属性设置为 Active，并发送 ActivityConcept::ActivityActivatedMessage 和 ActivityConcept::StatusChangedMessage 消息。如果 Activity 的预设件具有激活迁移动画，Activity 会先经过 Activating 状态。请参阅 Activity 的状态管理。

   

了解控制器属性的写入

Controller Property 是一个选择器，用于标识要激活哪个子 Activity。当您写入 Controller Property 时，Exclusive Activity Host 会激活与之匹配的子活动。当活动的 Activity 发生变化时，Activity Host 会写回您在 Activity Browser 中为该 Activity 设置的 Controller Property 值。写回操作按 Activity 名称进行去重，因此对于同一个 Activity 不会重复写回。

在启动期间，Kanzi 会多次设置活动的 Activity，例如在应用 Activity Host 内容时、在附加 Activity Host 时，以及在首次解析 Controller Property 源时。设置属性时，每次写入都会通知观察者，而不仅仅是在值发生变化时，因此 Controller Property 在初始化期间会多次变化。要仅对实际的值变化做出响应，请使用 On Property Change 触发器的 Ignore Identical Value 选项。

如果您绑定 Controller Property，请使用双向绑定。Activity Host 对 Controller Property 的首次写入会移除单向值源绑定，与对该属性的任何其他写入一样，因此单向绑定不起作用。双向绑定会在附加时以及数据上下文解析时覆盖 Controller Property，因此不要依赖您在此之前写入的值。请参阅 值源绑定。

要防止 Activity Host 写入您的数据对象，请使用 Data Trigger 和不带 Controller Property 源的 Apply Activation Action 来激活 Activity。请参阅 使用应用激活操作激活活动。

在 Exclusive Activity Host 中控制虚拟化

默认情况下，当您停用一个 Activity 时，Kanzi 会序列化该 Activity 及其子 Activity 的 Activity 属性值。除了您添加的 Activity 属性值外，这还包括有关 Activity 的焦点和激活状态的信息。请记住，Kanzi 不会序列化其他非 Activity 属性的运行时状态。

例如，即使包含该文本框的活动处于非活动状态，并且 Kanzi 卸载其内容，您也可以在 Text Box 中保留用户输入的信息。要实现此目的，在包含 Text Box 的 Activity 中，创建一个字符串活动属性，并在 Text Box 的 Text 属性与您创建的活动属性之间创建双向绑定。

您可以控制 Activities 的虚拟化：

• 在一个活动中。请参阅 在活动中控制虚拟化。

• 使用一个 Action。请参阅 使用 Action 控制虚拟化。

在活动中控制虚拟化

使用 Preserve History 属性，您可以在 Kanzi 停用该活动时控制活动中活动属性的序列化。

要在活动中控制虚拟化，请在 Activity Browser 或 Prefabs 中，选择您要控制活动属性值序列化的活动。在 Properties 中，添加 Preserve History 属性并将其设置为：

• 启用以序列化 Activity 属性的值。这是默认值。

  当您启用序列化并停用一个 Activity 时，Kanzi 会保留该 Activity 及其子 Activity 的 Activity 属性值。当您激活该 Activity 时，Kanzi 会恢复这些节点中 Activity 属性的序列化值。

• 禁用以禁用 Activity 属性值的序列化。

  当您禁用序列化并停用一个 Activity 时，Kanzi 不会保留该 Activity 及其子 Activity 的属性值。当您激活该 Activity 时，Kanzi 会重置这些节点中 Activity 属性的值。

使用 Action 控制虚拟化

使用 Action，您可以在激活或停用 Activity 之前控制 Activity 中属性的序列化。默认情况下，Kanzi 在您激活 Activity 时恢复序列化状态。

要使用 Action 控制虚拟化：

1. 在 Activity Browser、Prefabs 或 Node Tree 中，选择您要从中控制 Activity 属性值序列化的节点。

2. 在 Node Components 中，按 Alt 并右键单击 触发器，并创建一个您想用来控制活动序列化的触发器。

   例如，创建一个 On Attached 触发器。

   

3. 要在激活和活动时控制虚拟化，在您创建的触发器中，按 Alt 并右键单击 Actions，选择 Dispatch Message Action > Activity Host > Activate Activity Action，并在 Action 中将 Reset History 参数设置为：

   • 禁用以在用户激活该活动时恢复活动属性的序列化值。这是默认值。

   • 启用后，当用户激活该活动时，将重置活动属性的序列化值。

   

在 Exclusive Activity Host 中控制 Activity 持久性

默认情况下，当您停用一个活动时，Kanzi 会将该活动从节点树中分离，并删除该活动实例。

使用 Keep Activity Alive 属性，您可以在 Kanzi 停用该活动时控制活动持久性。

要控制活动持久性，请在 Activity Browser 或 Prefabs 中，选择您要控制其持久性的活动。在 Properties 中，添加 Keep Activity Alive 属性并将其设置为：

• Detach and Destroy。Kanzi 将该活动从节点树中分离，并删除该活动实例。这是默认值。

• Hide and Disable。Kanzi 隐藏并禁用该活动，而不是销毁它。当您再次激活该活动时，Kanzi 会恢复隐藏的活动并显示同一活动。该节点保持停用前的相同状态，即使您为该活动禁用了虚拟化也是如此。

  这样，再次激活该活动时可以跳过活动实例化。

激活活动

当您激活一个活动时，Kanzi：

1. 使用其预设创建一个 Activity 节点。

2. 将 Activity 节点附加到节点树。

3. 使活动可见。

4. 如果活动主机具有按键焦点且未进行其他配置，则将按键焦点设置为活动。控制是否将焦点设置到激活的 Activity。。

5. 将 Activity 的 Activity Status 属性设置为 Active，并发送 ActivityConcept::ActivityActivatedMessage 和 ActivityConcept::StatusChangedMessage 消息。如果 Activity 的预设件具有激活迁移动画，Activity 会先经过 Activating 状态。请参阅 Activity 的状态管理。

默认情况下，当您停用一个 Activity 时，Kanzi 会序列化该 Activity 及其子 Activity 的 Activity 属性值。除了您添加的 Activity 属性值外，这还包括有关 Activity 的焦点和激活状态的信息。请记住，Kanzi 不会序列化其他非 Activity 属性的运行时状态。

请参阅 在 Exclusive Activity Host 中控制虚拟化。

您可以使用以下方式激活 Activity：

• Activate Activity 消息。请参阅 使用激活活动消息激活活动。

• 一个 Set Property 操作。请参阅 使用设置属性操作激活活动。

• Navigate To Next Activity 和 Navigate To Previous Activity 操作。请参阅 激活下一个或上一个 Activity。。

• 一个 Apply Activation Action。请参阅 使用应用激活操作激活活动。

找出 Activity 是否处于活动状态。

要确定一个 Activity 是否处于活动状态：

• 检查该活动的 Activity Status 属性的值。

• 在该活动的独占活动主机中检查 Controller Property 属性的值。

设置初始活动的 Activity

要设置 Exclusive Activity Host 中初始处于活动状态的 Activity：

• 在 Activity Browser 中，选择您希望在 Exclusive Activity Host 变为活动状态时处于活动状态的 Activity。

• 在侧边面板中，启用 InitiallyActive 属性。

当您为某个 Activity 启用 InitiallyActive 属性时，Exclusive Activity Host 会在其自身变为活动状态时激活该 Activity，而无需显式激活它。显式激活会覆盖此设置。

在 Exclusive Activity Host 中，同一时间只能有一个 Activity 启用 InitiallyActive 属性。如果您为另一个 Activity 启用 InitiallyActive 属性，则上一个 Activity 的该属性会被取消设置。

使用激活活动消息激活活动

当使用 Activate Activity 消息时：

• 激活活动的条件过于复杂，无法用属性的值来表示。

• 您无法提前知道在 Exclusive Activity Host 中的 Activities 的数量。

要使用 Activate Activity 消息激活一个活动：

1. 创建一个 Exclusive Activity Host，其中包含多个活动，您可以使用 Controller Property 控制其激活状态。

   

2. 创建一个带有触发器的节点，您要使用该触发器来激活 Activity。

   例如，创建一个 Button 节点并使用 Button: Click 触发器。

   

3. 在 Node Tree 中，选择您在上一步中创建的节点。在 Node Components > Triggers 中，按 Alt 并右键单击 您要用于激活 Activity 的触发器，选择 Dispatch Message Action > Activate Activity 消息，并在操作集中：

   • Target Item 到包含您要激活的 Activity 的 Exclusive Activity Host。

   • Activation Path 到您要激活的 Exclusive Activity Host 到 Activity 的路径。

     如果您将 Activity 节点嵌套在其他类型的节点中，请在路径中仅包含祖先 Activity 节点。

     小技巧

     要获取到 Activity 的完整激活路径， 在 Activity Browser 中右键单击一个 Activity 并选择 Copy Activation Path。此命令会将从顶级 Activity Host 到该 Activity 的整个路径复制下来。

     Activity Activation Path 仅包含 Activities 和 Activity Hosts。

     
   

要激活活动，请在 Preview 中单击您创建的按钮。

备注

在需要该 Activity 时立即发送 ActivityHostConcept::ActivateActivityMessage，包括从 Code Behind 发送。Exclusive Activity Host 会存储激活路径，并在预设件加载完成后转发该路径，因此您无需使用计时器或手动挂起的动作来等待预设件。

Exclusive Activity Host 仅在其已附加并拥有 Activity 内容后才处理该消息。在此之前，它会丢弃激活请求且不发出警告。如果您的应用程序可能在此之前发送请求，例如通过外部接口到达的请求，请将这些请求排队，并在 Activity Host 附加后再发送。要检查 Activity Host 是否已附加，请使用其 ActivityElement.Attached 属性。

激活路径是相对于 Activity Host 的。Copy Activation Path 命令会复制包括根节点在内的完整路径，这与消息参数格式不兼容。请参阅 已知问题。

使用设置属性操作激活活动

使用 Set Property 操作来激活活动，当您的应用程序逻辑依赖于 Controller Property 属性的值来激活活动时。

要使用 Set Property 操作激活一个活动：

1. 创建一个 Exclusive Activity Host，其中包含多个活动，您可以使用 Controller Property 控制其激活状态。

   

2. 创建一个带有您要用于激活活动的触发器的节点。

   例如，创建一个 Button 节点并使用 Button: Click 触发器。

   

3. 在 Node Tree 中，选择您在上一步中创建的节点。在 Node Components > Triggers 中，按 Alt 并右键单击 您要用于激活活动的触发器，选择 Set Property 操作，并在操作中设置：

   • 将 Target Item 到包含您要激活的活动的 Exclusive Activity Host 节点。

   • 将 Target Property 设置为您在 Exclusive Activity Host 中的 Controller Property 属性中设置的属性类型。

   • 将 Fixed Value 设置为您要激活的 Activity 中使用的 Controller Property 属性的值。

   

要激活活动，请在 Preview 中单击您创建的按钮。

激活下一个或上一个 Activity。

要激活下一个或上一个 Activity：

1. 创建一个 Exclusive Activity Host，其中包含多个 Activities，您可以使用 Controller Property 控制其激活状态。

   

2. 创建一个带有触发器的节点，您要使用该触发器来激活 Activity。

   例如，创建一个 Button 节点并使用 Button: Click 触发器。

   

3. 在 Node Tree 中，选择您在上一步中创建的节点。在 Node Components > Triggers 中，按 Alt 并右键单击 您要用于激活 Activity 的触发器，选择 Navigate To Next Activity 或 Navigate To Previous Activity 操作，并在操作中设置：

   • 将 Target Item 到包含您要激活的 Activities 的 Exclusive Activity Host。

   • （可选） 要在到达该 Exclusive Activity Host 中的最后一个或第一个 Activity 后触发触发器时激活第一个或最后一个 Activity，请将 Loop Activity 属性设置为启用。

   

要激活活动，请在 Preview 中单击您创建的按钮。

使用应用激活操作激活活动

Apply Activation Action 在包含此操作的 Data Trigger 中，只要条件满足，就会保持活动处于激活状态。当触发条件不再满足时，Kanzi 会将活动的状态回滚到应用操作之前的状态。仅将 Apply Activation Action 与 Data Trigger 一起使用。

当您想将活动的激活与应用程序逻辑同步时，使用 Apply Activation Action。

例如，使用 Apply Activation Action 来显示当属性具有特定值时的集群指示器，然后当该属性的值不再是该值时隐藏相同的指示器。

使用 Data Trigger 时，请记住，Data Trigger 的动作优先于任何其他触发器的动作。

了解如何通过完成 教程：控制应用程序 UI，使用 Data Trigger 和 Apply Activation Action 来控制活动的激活状态。

要使用 Apply Activation Action 激活一个 Activity：

1. 在 Activity Browser 中，使用 Activities 创建一个 Exclusive Activity Host。

   例如，创建一个具有 Activities 的 Exclusive Activity Host 节点，以显示大灯模式：

   • Automatic

     • 在侧边面板中，启用 InitiallyActive 属性。

       这样可将 Automatic 活动默认设为激活状态。

   • High

   

2. 在 Prefabs 中，添加活动显示的内容。

   例如，为每个车灯模式添加一张图像。

   

3. （可选） In the Properties, set the size of the Exclusive Activity Host and position of the Activities in the Activity Host.

   

4. 创建一个节点，用于控制您在第一步中创建的某个活动的激活状态。

   例如，从 Asset Packages 中，将 Checkbox 拖到 Node Tree 中的 Exclusive Activity Host 节点。在 Properties 中，将 Checkbox 放置在 Activity Host 中。

   

5. 使用 Apply Activation Action 创建一个 Data Trigger：

   1. 在 Node Tree 中，选择 Exclusive Activity Host 节点。在 Node Components 中，按 Alt 并右键单击 Triggers 并选择 Data Trigger。

      

   2. 在 Expression 中的 Data Trigger 中，单击 。在 Node Tree 中，选择 Checkbox。从 Properties 中，将 Toggle State 属性拖到 Expression 字段，并编辑表达式以

      {@Checkbox/ButtonConcept.ToggleState}==1
      

      此条件表达式必须评估为 True 或 False。作为来源，您可以使用属性或数据源中的数据对象。

      单击 Save。

      通过这种方式，您可以设置 Data Trigger 以在检查 Checkbox 时执行 Apply Activation Action。

      

   3. 在 Data Trigger 中，按 Alt 并右键单击 Actions 并选择 Apply Activation Action。

      

   4. 在 Apply Activation Action 中，设置：

      • Activity Host Path 到 .

      • Activity Activation Path 到 High

      您在 Activity Activation Path 属性中设置的活动路径是相对于您在 Activity Host Path 属性中设置的独占活动主机节点的。

      Activity Browser 表示 Exclusive Activity Host 具有带有 图标的 Data Trigger。

      

   小技巧

   要获取到 Activity 的完整激活路径， 在 Activity Browser 中右键单击一个 Activity 并选择 Copy Activation Path。此命令会将从顶级 Activity Host 到该 Activity 的整个路径复制下来。

   Activity Activation Path 仅包含 Activities 和 Activity Hosts。

   

在 Preview 中，切换复选框：

• 当复选框被选中时，Checkbox 中 Toggle State 属性的值为 1，并且 Data Trigger 激活您在 Apply Activation Action 中设置的活动。

  当条件在包含此 Action 的 Data Trigger 中满足时，Apply Activation Action 会保持 Activity 激活。

• 当未选中复选框时，Checkbox 中 Toggle State 属性的值为 0，并且 Data Trigger 会停用您在 Apply Activation Action 中设置的活动。

  当触发条件不再满足时，Kanzi 将活动的状态回滚到应用操作之前的状态。

小技巧

在应用程序开发期间，使用这些 Data Trigger 工具在 Activity Browser 侧面板中：

工具	描述 (Description)
	显示 Data Trigger 的位置以及该 Data Trigger 的源活动和目标活动的位置。
	模拟应用 Data Trigger 时的状态。 这使您能够在满足 Data Trigger 条件时查看应用程序的状态，而无需更改应用程序中的属性值。
	在 Node Components 窗口中显示所选的 Data Trigger。

使用 Toggle Button Group 激活活动

您可以在 Toggle Button Group 中使用 Toggle Button 节点来激活活动主机中的活动。例如，您可以创建一个应用程序导航栏，以允许用户在应用程序屏幕之间切换。

要使用 Toggle Button Group 激活活动：

1. 创建一个活动主机，其中包含多个活动，其激活状态由 Controller Property 控制。

   例如，创建一个具有 Activities 的 Exclusive Activity Host 来显示不同的应用程序屏幕，并使用 Controller Property 来控制哪个 Activity 处于活动状态。请参阅 使用 Exclusive Activity Host。

   

2. 为您在上一步中创建的每个 Activity 创建一个 Toggle Button Group，并使用一个 Toggle Button 节点。请参阅 创建切换按钮组。

   在 Toggle Button Group 中，以与用于控制活动的枚举选项相同的顺序排列 Toggle Button 节点。

   

3. 选择 Toggle Button Group，在 Properties 中点击 + Add Binding，并在 Binding Editor 中设置：

   • Binding Mode 到 Two way

   • Property 到 Current Button Index

     使用 Current Button Index 属性来访问在 Toggle Button Group 中切换开启的 Toggle Button 的索引。

   • 将 Source 设置为 Activity Host 中的控制器属性，以控制在该活动主机中哪个 Activity 处于活动状态。

   单击 Save。

   通过此绑定，您可以在切换按钮组中被切换的切换按钮与 Activity Host 中处于活动状态的 Activity 之间创建双向连接。

   

现在，当您激活一个活动时，Kanzi 会切换相应的 Toggle Button，当您切换一个 Toggle Button 时，Kanzi 会激活相应的活动。

在 API 中使用 Activities

有关详细信息，请参阅 Activity2D、Activity3D、ExclusiveActivityHost2D 和 ExclusiveActivityHost3D 类。

另请参阅

教程：构建应用程序 UI

教程：控制应用程序 UI