一般来说，您应该以“主要功能”风格编写模板，最小化副作用。当您确实需要副作用时，有一些特殊方法可供选择，例如 .insert() 或 .create_mutable()，以帮助您解决问题。

create 的返回值是一个实现了 View 特性的对象。《视图》有更复杂的生命周期，涉及诸如 build()、rebuild() 和 raze() 等方法，但通常您不需要担心这些。

元素

通常您不需要编写自己的 View 实现，因为这些已经提供了。其中最重要的是 Element 类型，它创建一个单独的显示节点实体。元素有三个方面

• 一个包类型：在创建实体时将插入该实体的包的类型。
• 零个或多个子元素。
• 零个或多个“效果”。

元素的孩子也是视图，使用 View 对象定义。这些由父节点构建，并使用标准的 Bevy 父/子关系作为显示节点的孩子插入。

“效果”是指添加或修改实体 ECS 组件的任何东西，例如

• 添加 bevy_mod_picking 事件处理程序。
• 添加自定义材质。
• 添加动画。
• 添加 ARIA 节点以实现无障碍。
• 应用样式。

子元素和效果使用构建器模式添加，如下例所示

Element::<NodeBundle>::new()
    .style(style_panel)
    .children((
        "Hello, ",
        "world!",
    ))

children() 方法接受单个视图或视图的元组。在这种情况下，我们正在传递纯文本字符串。因为 View 特性有一个针对 &str 的实现，因此这些字符串可以作为视图显示，并将构建适当的 bevy_ui Text 节点。

请注意，ViewTemplates 也实现了 View，因此您可以在定义子元素时自由混合模板和视图。

在上面的示例中，.style() 方法添加了一个“样式效果”——一个初始化实体样式组件的效果。

.style() 方法是 静态效果 的一个示例，它仅在元素首次创建时应用一次。还有 动态效果，可以多次应用。动态效果通常需要依赖项列表，并且仅在依赖项更改时重新运行效果。例如，以下是一个仅当“焦点”标志（由无障碍性 Focus 资源确定）设置为 true 时才显示“焦点矩形”的样式效果。

.style_dyn(
    // This closure only runs when 'focused' changes.
    |focused, sb| {
        if focused {
            sb.outline_color(colors::FOCUS)
                .outline_offset(1.0)
                .width(2.0);
        } else {
            sb.outline_color(Option::<Color>::None);
        }
    },
    focused,
)

另一个常用效果是 .insert() 以及其动态对应物 .insert_dyn()，它们用于插入一个 ECS 组件。还有一个变体，.insert_if()，当条件为真时插入组件，当条件为假时移除组件——非常适合像 Disabled 这样的标记组件。

.insert() 方法常用于插入 bevy_mod_picking 事件处理器。

更多示例

使用 Cond 进行条件渲染

Cond（简称“条件”）视图接受一个条件表达式和两个子视图，一个在条件为真时构建，另一个在条件为假时构建。

/// Widget that displays whether the count is even or odd.
struct EvenOrOdd;

impl ViewTempate for EvenOrOdd {
    type View = impl View;

    fn create(cx: &mut Cx) -> Self::View {
        let counter = cx.use_resource::<Counter>();
        Element::new().children((
            "The count is: ",
            Cond::new(counter.count & 1 == 0, "even", "odd"),
        ))
    }
}

注意：对于条件视图，使用常规的 if 语句或 match 是完全可行的，但是有一个限制，即所有分支的结果类型必须相同。 Cond 没有这个限制，true 和 false 分支可以是不同类型。内部，每当条件变量改变时，Cond 都会拆毁之前的分支并初始化新的分支。

通常，“false”分支是一个空的视图，()，它不渲染任何内容，也不创建实体。

使用 Switch 进行条件渲染

您可以使用 Switch 从多个视图中选择。这与 Bevy 游戏状态配合得很好！

let state = *cx.use_resource::<State<EditorState>>().get();

Switch::new(state)
    .case(EditorState::Realm, EditModeRealmControls)
    .case(EditorState::Terrain, EditModeTerrainControls)
    .case(EditorState::Scenery, EditModeSceneryControls)
    .case(EditorState::Meta, EditModeMetadataControls)
    .case(EditorState::Play, EditModePlayControls)

使用 For 渲染多个项目

For::each() 接受一个项目列表和一个回调，该回调为每个项目构建一个 View。

struct EventLog;

impl ViewTempate for EventLog {
    type View = impl View;

    fn create(cx: &mut Cx) -> Self::View {
      let log = cx.use_resource::<ClickLog>();
      Element::new()
          .children(For::each(&log.0, |item| {
              Element::new()
                  .styled(STYLE_LOG_ENTRY.clone())
                  .children((item.to_owned(), "00:00:00"))
          }).with_fallback("No items")),
    }
}

在更新过程中，For 视图将项目列表与之前的列表进行比较，并计算差异。只有实际发生变化的项目（插入、删除和修改）才会重新构建。 For 构造有三个不同的变体，它们在处理项目之间的比较方式上有所不同。

• For::each() 要求数组元素实现 PartialEq。
• For::each_cmp() 接受一个额外的比较器参数，用于比较项目。
• For::index() 不比较项目，而是使用数组索引作为键。这个版本效率较低，因为项目插入或删除需要重新构建所有子视图。

返回多个节点

通常，ViewTemplate 返回一个单一的 View。如果您想返回多个视图，请使用元组。

(
    "Hello, ",
    "World!"
)

这是因为视图的元组也是视图。

销毁（Despawning）

要销毁Quill视图层次结构，只需在根实体上调用.despawn()即可。请不要调用.despawn_recursive()，因为这会导致panic。原因是Quill视图层次结构比简单的父子关系更复杂，它依赖于Bevy组件钩子来完成内部清理。

这也意味着Quill UI目前与StateScoped（始终进行递归销毁）不兼容，尽管这可能是未来版本中可以解决的问题。

对于移除子树，您不应销毁单个实体（这会导致混淆），而应依靠条件结构，如Cond和Switch。

可变：局部状态

在UI代码中，父小部件通常需要跟踪一些局部状态。通常，这种状态需要由创建UI的代码和事件处理程序访问。“可变”是管理局部状态的一种反应式方法。

Mutable<T>是一个引用，它指向存储在Bevy World中的可变数据。由于可变本身只是一个id，它支持克隆/复制，这意味着您可以将它传递给子视图或其他函数。

创建一个新的Mutable是通过实现为Cx和World的create_mutable::<T>(value)方法来完成的。请注意，通过Cx创建的可变由当前视图拥有，并在视图销毁时自动销毁。在世界上创建的处理程序不是这样的；您负责删除它们。

访问可变中的数据有几种方法，但都需要某种类型的上下文，以便检索数据。这个上下文可以是Cx上下文对象或World。

• 可变.获取(cx)
• 可变.获取(世界)
• 可变.设置(cx,新值)
• 可变.设置(世界,新值)

由于Mutables是组件，因此它们也是反应式的：调用mutable.get(cx)会自动将该可变添加到上下文的跟踪集中。然而，如果您传递一个World，则不会发生这种情况。

上述的.get()、.set()方法假设可变中的数据实现了Copy。还有.get_clone()和.set_clone()方法，它们与实现Clone的数据类型一起使用。

您也可以通过.update()就地更新可变，该方法接收一个回调函数，该函数传递一个对可变数据的引用。

钩子方法和Cx对象

在创建视图模板或构建视图时，会传递Cx上下文对象作为参数。该对象包含对跟踪范围的引用，该范围跟踪当前模板的响应式依赖集合。

Cx包含一些用于管理状态的方法，称为“钩子函数”。这个“钩子”一词来自React.js，意味着同样的意思：一个提供对与当前模板相关联的隐式状态访问的方法。“隐式状态”指的是你不需要手动分配和释放钩子返回的数据。

钩子结果会根据调用顺序自动进行记忆化：在模板内部第一个调用的钩子将始终返回相同的结果，无论它被调用多少次，第二个钩子也是如此，依此类推。这意味着，然而，每次调用钩子时必须保持相同的顺序——如果你在if语句中条件性地调用钩子，或在循环中调用钩子，这将是一个错误，并会导致恐慌。

以下是一些最常用的钩子：

• create_mutable()已经在上一节中进行了讨论。
• create_effect(闭包, 依赖项)运行一个回调，但仅在依赖项更改时。
• create_memo(工厂, 依赖项)返回一个记忆化值，当依赖项更改时，会重新计算。
• create_entity()生成一个新的空实体ID。当模板实例被销毁时，该实体将自动被销毁。
• create_callback(系统)注册一个新的单次系统。返回的对象可以传递给子小部件和其他函数，并用于接收事件。

Cx还有一些额外的不是钩子的方法，因为它们不需要按照特定的顺序调用

• use_resource()返回对指定资源的引用。
• use_component()返回对指定组件的引用。

Quill Obsidian crate通过添加一些额外的钩子扩展了Cx特质

• is_hovering()如果鼠标悬停在当前元素上，则返回true。
• is_focused()如果元素具有键盘焦点，则返回true。还有其他变体，如is_focus_visible()。
• use_element_rect(id)根据实体ID返回小部件的屏幕矩形。
• create_bistable_transition(打开)创建一个简单的状态机，当需要为具有“进入”和“退出”动画的元素进行动画处理时可以使用。

Element::from_entity()和显式实体ID

元素通常在构建时会生成一个新的实体。但是，有些情况下您可能想指定已生成的实体的实体ID。为此，您可以使用Element::for_entity(id)，而不是使用Element::new()。

这种用法的一个例子是悬停：当鼠标悬停在元素上时，我们想突出显示元素的颜色。为此，我们希望在构建元素时传递一个“is_hovered”标志作为参数，以便计算适当的样式。但是，计算“is_hovered”需要知道元素的实体ID，而这个ID在元素创建之前是不存在的。

在Obsidian库中，有一个名为is_hovering(id)的钩子（对Cx的扩展），如果给定的元素当前正被鼠标悬停，它会返回true。我们可以通过以下步骤设置我们的小部件：

• 使用id = cx.create_entity()创建一个新的实体ID。
• 使用cx.is_hovering(id)检查悬停。
• 使用Element::for_entity(id)根据创建的ID创建一个Element。
• 在Element的构建方法中，使用is_hovered条件性地应用样式。

响应式上下文和Bevy观察者

虽然目前还没有对观察者的明确支持，但是有一种方法可以从观察者那里触发反应。

您可以通过在owner实体上插入一个Observer组件来为Quill的View创建一个观察者。

let owner = cx.owner();
cx.create_effect(
    |world, owner| {
        world.entity_mut(owner).insert(Observer::new(callback));
    },
    owner
);

由于观察者附加到所有者实体上，因此当View销毁时，它也会被销毁。

要触发反应，将一个Commands注入观察者回调，并调用一个TriggerReaction命令。此命令手动标记跟踪范围为已更改，将在下一个周期更新。

commands.add(TriggerReaction(owner));

请注意，您不应在响应式回调中调用TriggerReaction，因为这可能导致无限循环。

样式

在Bevy中，有几种不同的方法来处理样式。一种是“命令式样式”，这意味着您明确创建样式组件，如BackgroundColor和Outline，并在模板中附加到显示节点。

这种方法的一个缺点是您对从不同来源组合样式的功能有限。Rust有一个从另一个结构体继承结构值的方法，即..语法；这假设在声明点已知两个结构值。理想情况下，我们希望有一个通用的机制，允许我们使用“基本”样式，然后在上面添加自定义设置，但又不要求向世界公开基本样式的内部细节。

Quill对样式采取更函数式的方法，使用bevy_mod_stylebuilder包。此包提供了一个StyleBuilder接口，允许您使用流畅的构建模式定义Bevy样式。此外，它支持组合：您可以将一组样式(style1, style2, style3)传递，并且将按顺序应用这三个样式。

fn style_button(ss: &mut StyleBuilder) {
    ss.border(1)
        .display(ui::Display::Flex)
        .flex_direction(ui::FlexDirection::Row)
        .justify_content(ui::JustifyContent::Center)
        .align_items(ui::AlignItems::Center)
        .align_content(ui::AlignContent::Center)
        .padding((12, 0))
        .border(0)
        .color(colors::FOREGROUND)
        .cursor(CursorIcon::Pointer);
}

element.style((
    // Default text styles
    typography::text_default,
    // Standard Button styles
    style_button,
    // Custom style overrides
    self.custom_styles.clone()
))