使用节点预设

使用节点预设（预制模板）来构建您的应用程序并创建一致的界面。预设允许您创建应用程序的构建模块，并使应用程序更易于维护。

要从逻辑上分离应用程序的一部分，或者在应用程序运行时将内容添加到节点树中，为应用程序中出现多次的每个项创建一个预设件。例如，使用预设件来：

• 创建具有一致结构的内容。例如，使用预设可以创建始终具有相同结构但外观可以变化的按钮。

• 模块化您的工程，使其更容易维护。

• 控制您的 Kanzi 应用程序的加载和启动时间。

• 为您的 Kanzi 应用程序创建不同的主题。

• 本地化您的 Kanzi 应用程序。

使用预设件时请记住：

• 您可以像复制节点树中的任何其他节点一样复制预设件的实例。

• 添加到预设件实例的属性值会重写预设件中设置的属性值。

• 要引用预设件内的项（例如，在消息触发器或属性绑定中）时，使用相对路径。不要使用预设件本身作为任何消息或动画的目标路径。

您可以在预设件中嵌套预设件。

节点预设和节点预设实例

Node 预设仅在您加载它们时才会消耗设备上的内存。当您加载一个 node 预设时，该预设会根据其包含的节点和属性的数量消耗相应的内存。当您实例化一个 node 预设时，Kanzi 会创建节点并为这些节点分配属性。您可以通过将实例的数量乘以单个预设实例的内存需求来计算预设实例消耗的内存量。

当您将某个节点附加到节点树时，从资源管理器查找并请求节点使用的资源。资源管理器会加载资源，或者如果资源已加载则返回现有资源。

当您分离一个节点预设实例时，Kanzi 不会释放您分离的节点中使用的资源。这是一种性能优化，使您可以更改预设的父节点，或在节点树中移动预设，而无需再次加载预设使用的资源。当您想要释放所有不再使用的资源时，请调用 ResourceManager::purge。

Kanzi 假设您放置在节点树中的所有节点都将被使用。Kanzi 针对节点树中放置的所有内容已准备好立即使用的情况进行优化。如果某个节点不打算使用，请将其从节点树中移除。

Prefab Placeholder 和 Prefab View 节点

您可以同时使用 Prefab Placeholder 和 Prefab View 节点在您的项目中实例化一个节点预设。 这些节点之间的区别是：

• 当您使用 Prefab Placeholder 节点实例化节点预设时，Kanzi 会读取 Prefab Template 属性的值一次，并将 Prefab Placeholder 节点替换为该属性指向的预设。

  例如，如果您使用 Prefab Placeholder 2D 节点来实例化包含 Button 2D 节点的节点预设，当 Kanzi 实例化该节点预设时，它会将 Prefab Placeholder 2D 节点替换为 Button 2D 预设的根节点。

• 当您实例化一个带有 Prefab View 节点的节点预设时，Kanzi 监视 Prefab Template 属性的值，并将该属性指向的预设作为 Prefab View 节点的子节点添加。这使您可以更改 Prefab View 实例化的预设，并在加载资源时保持应用程序的响应。请参阅 异步加载节点预设资源。

  例如，如果您使用 Prefab View 2D 节点来实例化包含 Button 2D 节点的节点预设，当 Kanzi 实例化预设时，它将 Button 2D 节点的根节点作为 Prefab View 2D 节点的子节点添加。

何时使用 Prefab Placeholder 以及何时使用 Prefab View 节点。

使用 Prefab Placeholder 节点来实例化您在应用程序运行时不打算改变的节点预设。

如果您想动态更改预设，或想异步加载预设使用的资源，请使用 Prefab View 来实例化预设。 例如，当您为应用程序设置主题并希望为不同的主题使用不同的预设时，请使用 Prefab View 节点来实例化这些预设。

Kanzi 读取 Prefab Placeholder 的 Prefab Template 属性的值一次，但 Prefab View 节点监视 Prefab Template 属性值的变化。当 Prefab View 中的 Prefab Template 属性值发生变化时，Kanzi 用新的子节点替换其子节点。

创建和使用节点预设件

要创建和使用节点预设件：

1. 在 Prefabs 中，单击 并选择您要创建的预设。

   例如，创建一个 Button 2D 预设，并向其添加一个 Image 和一个 Text Block 2D 节点。

   

2. 要在应用程序中实例化预设件：

   • 从 Prefabs 拖动您创建的预设到 Node Tree，并将其放在您要使用该预设的节点上。

     Kanzi Studio 创建一个 Prefab Placeholder 节点，该节点在您的项目中实例化预设。

     

     要实例化不同的预设，在 Node Tree 中选择您要更改的预设，并在 Properties 中将 Prefab Template 属性设置为您要实例化的预设。

     

   • 在 Node Tree 按 Alt 并右键单击 中，选择要实例化预设的节点，选择 Prefab View，并在 Properties 中将 Prefab Template 属性设置为您要实例化的预设。

     

自定义节点预设件的实例

一个节点预设可以包含一个节点树，每个节点都有其自己的属性。当您在项目中编辑预设或其任何实例中的节点时，您会更改该预设的所有实例中的那些节点。您可以通过覆盖预设的属性值来自定义预设的每个实例，使其具有自己的属性值。例如，当您为通讯录条目创建一个预设时，您希望为每个通讯录条目显示不同的姓名、号码和照片。

要自定义节点预设的实例：

1. 在 Prefabs 中，选择预设中的节点，以便在该预设的实例中进行自定义。

   例如，要为预设的每个实例使用不同的纹理，请选择一个 Image 节点。

   

2. 在 Properties 中，在您要自定义的属性旁边，单击 。

   Kanzi Studio 从该属性创建一个自定义属性，将其添加到该预设的根节点，并在该预设的根节点中创建一个到该属性的 ##Template 绑定。

   请参阅 预设件根绑定。

   例如，要自定义您希望在该预设的不同实例中显示的纹理，请单击 ，位于 Image 属性旁边。Kanzi Studio 创建一个自定义 Image 属性，将其添加到该节点预设的根节点，并在 Image 节点中创建一个 ##Template 绑定到该节点预设根节点中的自定义 Image 属性。

   

3. 在 Node Tree 中选择您要自定义的预设实例的根节点。

   

4. 在 Properties 中，单击您自定义的属性旁边的 ，并设置该属性的值。

   只有此预设实例使用您设置的值。

   

编辑节点预设

要编辑节点预设，请双击 Prefabs 中的预设。Kanzi Studio 仅在 Preview 窗口选项卡中显示预设。您现在可以使用 Preview 工具编辑预设，并在不实例化预设的情况下查看编辑结果。

将节点转换为预设

要将项目的节点树的任何部分转换为预设，请从 Node Tree 将您要转换为预设的部分的根拖动到 Prefabs。

当您将节点拖放到 Prefabs 窗口时，Kanzi Studio 会从该节点创建一个预设模板，并用该预设的实例替换原始节点。

异步加载节点预设资源

当您异步加载预设资源时，Kanzi 使用单独的线程来加载资源。当 Kanzi 完成资源加载后，它使用主线程部署这些资源。这样，在加载资源时，您的应用程序仍然保持响应。要从多个预设异步加载资源，请参阅 教程：异步加载和部署资源。

使用资源剖析测量运行期间花费了多长时间在您的 Kanzi 应用程序中加载和部署资源和预设。

资源剖析数据可帮助您找出要异步加载哪些资源。

请参阅 测量资源的加载和部署时间。

要异步加载节点预设资源：

1. 创建要在 Kanzi 加载节点预设资源时显示的内容。

   例如，要创建一个加载屏幕，您可以用异步加载资源的预设件内容替换，从 Asset Packages > Factory Content 拖动 Processing Indicator 并将其放到 Prefabs 窗口上。

   

2. 创建一个节点预设，其资源您希望异步加载。

   例如：在 Prefabs 中创建一个 Stack Layout 2D，并向其添加多个 Image 节点，每个节点指向不同的图像。

   

3. 在 Node Tree 中创建一个 Prefab View 节点，在您希望异步加载预设资源的位置，并在 Properties 中将 Prefab Template 属性设置为您希望在 Kanzi 加载您在上一步中创建的预设资源时显示的内容。

   例如，将 Prefab Template 属性设置为 Processing Indicator 预设。

   

4. 在 Node Tree 中选择 Prefab View 节点，在 Node Components 按 Alt 并右键单击 Triggers 中，选择您要使用以开始加载预设资源的触发器。

   例如，添加 On Attached 触发器，以便在 Kanzi 将 Prefab View 节点附加到屏幕图时开始加载资源。

   

5. 在 Node Components 按 Alt 并右键单击 中，应用您在上一步中添加的触发器，并选择 Dispatch Message Action > Prefab View > Start Asynchronous Load。

   

6. 在 Start Asynchronous Load 操作中，将 Prefab Template 属性设置为指向您要异步加载其资源的预设的预设或资源 ID。

   

7. 要定义当 Kanzi 完成加载资源时会发生什么：

   1. 在 Node Tree 中选择 Prefab View 节点，在 Node Components 按 Alt 并右键单击 Triggers 中，选择 Message Trigger > Prefab View > Asynchronous Load Completed。

      

   2. 在 Node Components > Triggers 按 Alt 并右键单击 中，Asynchronous Load Completed 触发器，并选择一个操作。

      例如，选择 Dispatch Message Action > Page > Navigate to Page 操作，并将 Target Item 设置为 Page 节点，以便在 Kanzi 完成加载资源时，应用程序导航到该节点。

      

8. 在 Kanzi Studio 中选择 File > Export > Export as KZB Player for Windows，并在 <ProjectName>/Tool_project/Application Player 目录中打开应用程序的 exe 文件。

   因为 Kanzi Studio Preview 在启动时会加载项目中的所有资源，要查看异步加载资源的效果，可以将项目导出为 kzb 文件播放器，或者导出项目 kzb 文件并从项目的 Visual Studio 解决方案运行应用程序。

   

替换节点预设件的根节点

当您想要添加或更改用作预设的父节点的节点时，替换预设的根节点。 例如，如果您最初创建了一个以 Grid Layout 3D 作为其根的预设，但现在您想将该 Grid Layout 3D 放入 Stack Layout 3D 中，则需要替换该预设的根节点。

要替换节点预设件的根：

1. 在 Prefabs 按 Alt 并右键单击 中，选择您要替换的预设的根，并选择 Empty Node From Items。

   Kanzi Studio 用 Empty Node 节点替换预设的当前根节点，并将整个预设放置在该空节点内。对于 3D 预设，Kanzi Studio 创建一个 Empty Node 3D 节点，对于 2D 预设，它创建一个 Empty Node 2D 节点。

   

2. 在 Prefabs 中创建您想用作预设新根节点的节点。

   例如，创建一个 Stack Layout 3D。

   

3. 将旧预设从 Empty Node 节点根拖放到您在上一步中创建的新根节点。

   

在 API 中使用 Prefab View 3D 节点

要使用 Prefab view 3D 节点，请创建一个带有 3D 内容的预设件，并使用 setPrefab() 对其进行设置：

// Create a Prefab view 3D and add it to the scene.
PrefabView3DSharedPtr prefabView3D = PrefabView3D::create(domain, "Prefab view");
scene->addChild(prefabView3D);

// Acquire prefab from resource manager.
PrefabTemplateSharedPtr prefabTemplate = resourceManager->acquireResource<PrefabTemplate>("kzb://my_project/Prefabs/My3DPrefab");

// Use the prefab in the PrefabView3D node.
prefabView3D->setPrefab(prefabTemplate);

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

在 API 中使用 Prefab View 2D 节点

要使用 Prefab View 2D 节点，请创建一个带有 2D 内容的预设件，并使用 setPrefab() 对其进行设置：

// Create a Prefab view 2D and add it to the viewport.
PrefabView2DSharedPtr prefabView2D = PrefabView2D::create(domain, "Prefab view");
viewportNode->addChild(prefabView2D);

// Acquire prefab from resource manager.
PrefabTemplateSharedPtr prefabTemplate = resourceManager->acquireResource<PrefabTemplate>("kzb://my_project/Prefabs/My2DPrefab");

// Use the prefab in the PrefabView2D node.
prefabView2D->setPrefab(prefabTemplate);

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

Prefab View 属性类型

有关 Prefab View 节点的可用属性类型列表，请参阅 Prefab View 2D 和 Prefab View 3D。

Prefab Placeholder 属性类型和消息。

有关 Prefab Placeholder 节点的可用属性类型和消息的列表，请参阅 Prefab Placeholder 2D 和 Prefab Placeholder 3D。

另请参阅

使用绑定

资源管理

测量资源的加载和部署时间

教程：异步加载和部署资源

在 Lua 中使用预设件