游戏引擎 / 系统课时
制作背包列表与物品详情
制作背包列表与物品详情
本课使用 Unity 6 UI Toolkit 制作可操作的运行时背包:左侧滚动显示物品图标、名称和数量,右侧展示选中物品的描述与使用按钮。使用治疗药剂后,库存数量、角色生命值和详情界面同步更新;物品耗尽时自动清除失效选择,避免重复消耗。
学习目标
- 使用
UIDocument和ListView构建背包列表与物品详情双栏布局。 - 通过
makeItem、bindItem和选择事件显示物品数据。 - 将使用按钮连接到库存消耗逻辑,并验证数量变化、空列表和按钮禁用行为。
搭建背包列表与详情布局
运行时背包采用左右双栏:左侧负责浏览和选择物品,右侧负责查看详情及执行操作。列表行展示图标、名称、数量;详情面板展示图标、说明、持有数量、使用按钮和反馈信息。
以下操作以 Unity 6(6000.0~6000.3)的 UI Toolkit 运行时接口为准。
- 在
Assets下创建UI文件夹,再通过Assets > Create > UI Toolkit > UI Document创建InventoryView.uxml。 - 双击 UXML 文件可使用 UI Builder 编辑,也可以在文本编辑器中直接编写下方结构。
- 在场景中通过
GameObject > UI Toolkit > UI Document创建运行时 UI 对象。 - 在该对象的 Inspector 中确认
Panel Settings已赋值,并将InventoryView.uxml拖入Source Asset。
InventoryView.uxml 的完整内容如下。示例采用固定的 800×440 像素面板,便于先完成交互验收;正式项目可以改为百分比宽度及响应式布局。
<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:
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 的对象上:
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。
按以下顺序进行验收:
- 进入 Play 模式。左侧应显示小型治疗药剂和铁钥匙,数量分别为
×2、×1。初始选中第一项,右侧显示药剂说明、持有 2 和生命60/100。 - 点击药剂的使用按钮一次。生命变成
90/100,列表数量变成×1,右侧持有数量变成 1。 - 再次点击使用。生命变成
100/100,药剂数量降到 0,列表不再显示药剂,详情清空且使用按钮禁用。 - 选择铁钥匙。详情显示“用于开启铁门”,但由于
heal = 0,使用按钮保持禁用,钥匙数量仍为 1。 - 退出 Play 模式,将
Current Health改成 100 后重新进入。药剂仍然存在,但使用按钮应禁用,点击不会消耗物品。
前两次药剂使用的预期 Console 输出如下。此结果要求初始生命为 60、最大生命为 100、药剂 heal = 30 且 amount = 2。
使用 小型治疗药剂,生命 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 完成库存到界面的同步。正式项目接入已有物品拾取、任务奖励或装备系统时,应让这些系统调用各自的库存修改接口,并在成功修改后统一发送变更通知。只要列表的数据源和事件链保持一致,新增、消耗和移除物品都可以沿用同一套界面刷新方式。