游戏引擎 / 系统课时

制作背包列表与物品详情

制作背包列表与物品详情

本课使用 Unity 6 UI Toolkit 制作可操作的运行时背包:左侧滚动显示物品图标、名称和数量,右侧展示选中物品的描述与使用按钮。使用治疗药剂后,库存数量、角色生命值和详情界面同步更新;物品耗尽时自动清除失效选择,避免重复消耗。

学习目标

  • 使用 UIDocument 和 ListView 构建背包列表与物品详情双栏布局。
  • 通过 makeItem、bindItem 和选择事件显示物品数据。
  • 将使用按钮连接到库存消耗逻辑,并验证数量变化、空列表和按钮禁用行为。

搭建背包列表与详情布局

运行时背包采用左右双栏:左侧负责浏览和选择物品,右侧负责查看详情及执行操作。列表行展示图标、名称、数量;详情面板展示图标、说明、持有数量、使用按钮和反馈信息。

以下操作以 Unity 6(6000.0~6000.3)的 UI Toolkit 运行时接口为准。

  1. 在 Assets 下创建 UI 文件夹,再通过 Assets > Create > UI Toolkit > UI Document 创建 InventoryView.uxml。
  2. 双击 UXML 文件可使用 UI Builder 编辑,也可以在文本编辑器中直接编写下方结构。
  3. 在场景中通过 GameObject > UI Toolkit > UI Document 创建运行时 UI 对象。
  4. 在该对象的 Inspector 中确认 Panel Settings 已赋值,并将 InventoryView.uxml 拖入 Source Asset。

InventoryView.uxml 的完整内容如下。示例采用固定的 800×440 像素面板,便于先完成交互验收;正式项目可以改为百分比宽度及响应式布局。

xml
<ui:UXML xmlns:ui="UnityEngine.UIElements">
  <ui:VisualElement style="flex-direction: row; width: 800px; height: 440px; background-color: rgb(25, 36, 52); padding-left: 16px; padding-right: 16px; padding-top: 16px; padding-bottom: 16px;">
    <ui:VisualElement style="width: 380px; margin-right: 20px;">
      <ui:Label text="背包" style="font-size: 22px; color: white;" />
      <ui:ListView name="item-list" style="flex-grow: 1;" />
    </ui:VisualElement>
    <ui:VisualElement style="flex-grow: 1;">
      <ui:Label name="detail-name" text="请选择物品" style="font-size: 22px; color: white;" />
      <ui:Image name="detail-icon" style="width: 64px; height: 64px; margin-top: 8px;" />
      <ui:Label name="detail-desc" style="color: white; margin-top: 8px;" />
      <ui:Label name="detail-count" style="color: white; margin-top: 8px;" />
      <ui:Button name="use-button" text="使用" style="margin-top: 12px;" />
      <ui:Label name="health-label" style="color: white; margin-top: 8px;" />
      <ui:Label name="feedback-label" style="color: white;" />
    </ui:VisualElement>
  </ui:VisualElement>
</ui:UXML>

这份 UXML 只定义视觉结构,不存储库存。item-list、detail-name、detail-icon 等名称是后续 C# 查询控件的标识,必须与脚本中的 Q<T>() 参数完全一致。

ListView 使用可复用的行元素,不会为全部库存物品同时创建独立的 GameObject。固定高度列表适合名称、图标和数量等结构一致的物品行;本例设置行高为 56 像素,图标为 40×40 像素。

建立可通知界面的背包数据源

为了独立运行示例,先创建一个小型背包组件,同时模拟角色生命值。它负责判断物品是否可以使用、扣除数量以及发出库存变化事件。实际项目应由已有的背包服务和生命组件承担这些职责,UI 不直接修改库存。

创建 DemoInventory.cs:

csharp
using System;
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

[Serializable]
public class InventoryEntry
{
    public string id;
    public string displayName;
    [TextArea] public string description;
    public Sprite icon;
    [Min(0)] public int amount = 1;
    [Min(0)] public int heal = 30;
}

public class DemoInventory : MonoBehaviour
{
    [SerializeField] private List<InventoryEntry> items = new();
    [SerializeField, Min(1)] private int maxHealth = 100;
    [SerializeField, Min(0)] private int currentHealth = 60;

    public IList Source => items;
    public IReadOnlyList<InventoryEntry> Items => items;
    public int CurrentHealth => currentHealth;
    public int MaxHealth => maxHealth;
    public event Action Changed;

    // heal 为 0 的物品在本示例中不可使用。
    public bool CanUse(InventoryEntry entry)
    {
        return entry != null &&
               items.Contains(entry) &&
               entry.amount > 0 &&
               entry.heal > 0 &&
               currentHealth < maxHealth;
    }

    public bool TryUse(InventoryEntry entry)
    {
        if (!CanUse(entry)) return false;

        // 先确认治疗有效,再扣除一个物品。
        currentHealth = Mathf.Min(maxHealth, currentHealth + entry.heal);
        entry.amount--;

        if (entry.amount == 0)
            items.Remove(entry);

        Debug.Log($"使用 {entry.displayName},生命 {currentHealth}/{maxHealth},剩余 {entry.amount}");

        // 只有成功修改数据后才通知视图。
        Changed?.Invoke();
        return true;
    }
}

这里使用 IList 作为 ListView.itemsSource 的数据接口,使用 IReadOnlyList<InventoryEntry> 供视图读取物品。视图不应直接调用 Source.RemoveAt() 或修改 amount,否则会绕过使用条件和 Changed 通知。

在场景中新建 InventoryData 对象,挂载 DemoInventory,并在 Inspector 设置以下测试数据:

字段 小型治疗药剂 铁钥匙
id potion-small iron-key
displayName 小型治疗药剂 铁钥匙
description 恢复最多30点生命 用于开启铁门
amount 2 1
heal 30 0
icon 药剂 Sprite 钥匙 Sprite

将 Max Health 设置为 100,Current Health 设置为 60。图标资源可通过纹理导入设置中的 Texture Type = Sprite (2D and UI) 获得;测试时暂不分配图标也不会影响列表和按钮逻辑。

TryUse 有三条需要验证的规则:生命已满时不能浪费药剂;库存为零时不能继续使用;成功消耗到零时移除整条物品记录。示例中 Changed 事件只在成功使用后触发,失败操作不会造成列表变化。

绑定列表选择与使用操作

接下来由 InventoryView 负责连接 UI 和背包状态。makeItem 创建可复用的视觉行,bindItem 将指定索引的数据填写到该行;selectionChanged 更新右侧详情;使用按钮请求 TryUse,随后通过 Changed 事件刷新列表。

背包列表、选中物品详情与使用后的库存刷新数据流

在 Assets/Scripts 创建 InventoryView.cs,将下列脚本挂载到含有 UIDocument 的对象上:

csharp
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UIElements;

[RequireComponent(typeof(UIDocument))]
public class InventoryView : MonoBehaviour
{
    [SerializeField] private DemoInventory inventory;

    private ListView list;
    private Label nameLabel, descLabel, countLabel;
    private Label healthLabel, feedbackLabel;
    private Image detailIcon;
    private Button useButton;
    private InventoryEntry selected;

    private void OnEnable()
    {
        if (inventory == null)
        {
            Debug.LogError("InventoryView 未绑定 DemoInventory");
            enabled = false;
            return;
        }

        var root = GetComponent<UIDocument>().rootVisualElement;
        list = root.Q<ListView>("item-list");
        nameLabel = root.Q<Label>("detail-name");
        descLabel = root.Q<Label>("detail-desc");
        countLabel = root.Q<Label>("detail-count");
        healthLabel = root.Q<Label>("health-label");
        feedbackLabel = root.Q<Label>("feedback-label");
        detailIcon = root.Q<Image>("detail-icon");
        useButton = root.Q<Button>("use-button");

        // 先定义行创建与数据绑定,再连接真实库存。
        list.makeItem = MakeRow;
        list.bindItem = BindRow;
        list.fixedItemHeight = 56;
        list.selectionType = SelectionType.Single;
        list.itemsSource = inventory.Source;

        list.selectionChanged += OnSelectionChanged;
        useButton.clicked += UseSelected;
        inventory.Changed += OnInventoryChanged;

        int index = inventory.Items.Count > 0 ? 0 : -1;
        list.selectedIndex = index;
        selected = index >= 0 ? inventory.Items[index] : null;
        ShowDetail();
    }

    private VisualElement MakeRow()
    {
        var row = new VisualElement();
        row.style.flexDirection = FlexDirection.Row;
        row.style.alignItems = Align.Center;
        row.style.paddingLeft = 6;

        var icon = new Image
        {
            name = "row-icon",
            scaleMode = ScaleMode.ScaleToFit
        };
        icon.style.width = 40;
        icon.style.height = 40;
        row.Add(icon);

        var itemName = new Label { name = "row-name" };
        itemName.style.flexGrow = 1;
        itemName.style.marginLeft = 8;
        row.Add(itemName);
        row.Add(new Label { name = "row-count" });
        return row;
    }

    private void BindRow(VisualElement row, int index)
    {
        var entry = inventory.Items[index];
        row.Q<Image>("row-icon").sprite = entry.icon;
        row.Q<Label>("row-name").text = entry.displayName;
        row.Q<Label>("row-count").text = $"×{entry.amount}";
    }

    private void OnSelectionChanged(IEnumerable<object> items)
    {
        selected = list.selectedItem as InventoryEntry;
        feedbackLabel.text = "";
        ShowDetail();
    }

    private void ShowDetail()
    {
        bool valid = selected != null;
        nameLabel.text = valid ? selected.displayName : "请选择物品";
        detailIcon.sprite = valid ? selected.icon : null;
        descLabel.text = valid ? selected.description : "背包为空或未选中物品";
        countLabel.text = valid ? $"持有:{selected.amount}" : "持有:0";
        healthLabel.text = $"生命 {inventory.CurrentHealth}/{inventory.MaxHealth}";
        useButton.SetEnabled(valid && inventory.CanUse(selected));
    }

    private void UseSelected()
    {
        if (!inventory.TryUse(selected))
        {
            feedbackLabel.text = "无法使用:库存不足或生命已满";
            ShowDetail();
            return;
        }

        feedbackLabel.text = "使用成功";
    }

    private void OnInventoryChanged()
    {
        // 保存原对象引用,避免删除列表行后错误选中其他物品。
        var previous = selected;
        list.RefreshItems();

        int index = -1;
        for (int i = 0; i < inventory.Items.Count; i++)
        {
            if (ReferenceEquals(inventory.Items[i], previous))
            {
                index = i;
                break;
            }
        }

        list.selectedIndex = index;
        selected = index >= 0 ? inventory.Items[index] : null;
        ShowDetail();
    }

    private void OnDisable()
    {
        if (list != null)
            list.selectionChanged -= OnSelectionChanged;
        if (useButton != null)
            useButton.clicked -= UseSelected;
        if (inventory != null)
            inventory.Changed -= OnInventoryChanged;
    }
}

将 InventoryData 对象拖入 InventoryView 组件的 Inventory 字段。这样,背包数据组件和 UI 控制器在场景中建立引用关系。

这段代码有三个容易被忽略的细节。

  • makeItem 只负责创建行结构,不能把某个物品对象永久绑定到行上。滚动列表会回收行元素,并重新调用 bindItem 显示其他数据。
  • OnInventoryChanged 使用原物品对象引用寻找新的索引。物品删除后清空选择,避免列表缩短时右侧详情错误地指向下一件物品。
  • OnDisable 解除选择、按钮和库存事件订阅,避免对象反复启用时产生重复响应。

此处使用 RefreshItems() 而非每次调用 Rebuild(),因为物品消耗仅改变数据内容或列表数量,没有改变 makeItem 的行模板。两者的适用边界可参考 Unity 6 ListView 文档。

运行并验证库存与界面同步

进入 Play 模式之前,确认场景里存在 InventoryData 和挂载 InventoryView 的 UI Document 对象。InventoryView.uxml 已设置为 UI Document 的 Source Asset,Inventory 引用已连接,两个测试物品的数量分别为 2 和 1。

按以下顺序进行验收:

  1. 进入 Play 模式。左侧应显示小型治疗药剂和铁钥匙,数量分别为 ×2、×1。初始选中第一项,右侧显示药剂说明、持有 2 和生命 60/100。
  2. 点击药剂的使用按钮一次。生命变成 90/100,列表数量变成 ×1,右侧持有数量变成 1。
  3. 再次点击使用。生命变成 100/100,药剂数量降到 0,列表不再显示药剂,详情清空且使用按钮禁用。
  4. 选择铁钥匙。详情显示“用于开启铁门”,但由于 heal = 0,使用按钮保持禁用,钥匙数量仍为 1。
  5. 退出 Play 模式,将 Current Health 改成 100 后重新进入。药剂仍然存在,但使用按钮应禁用,点击不会消耗物品。

前两次药剂使用的预期 Console 输出如下。此结果要求初始生命为 60、最大生命为 100、药剂 heal = 30 且 amount = 2。

text
使用 小型治疗药剂,生命 90/100,剩余 1
使用 小型治疗药剂,生命 100/100,剩余 0

如果测试中出现异常,按以下顺序定位:

现象 优先检查 修复方法
背包完全不可见 UI Document 的 Panel Settings、Source Asset 将正确的 UXML 资产重新指定给 UIDocument
控件空引用报错 UXML 中各元素的 name 与 Q<T>() 查询名称逐字核对
图标空白但文字正常 Sprite 导入设置与 icon 引用 设置 Sprite 类型并在 Inspector 指定资源
使用后列表数量不变 Changed 事件与 RefreshItems 调用 确认成功消耗后发出通知且视图已订阅
物品移除后详情错位 选择索引和对象引用 删除后重新校验原对象是否还在库存

当前实现通过 Changed 完成库存到界面的同步。正式项目接入已有物品拾取、任务奖励或装备系统时,应让这些系统调用各自的库存修改接口,并在成功修改后统一发送变更通知。只要列表的数据源和事件链保持一致,新增、消耗和移除物品都可以沿用同一套界面刷新方式。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

制作背包列表与物品详情

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通