67 lines
4.3 KiB
Markdown
67 lines
4.3 KiB
Markdown
# FItemView
|
||
|
||
## 基本信息
|
||
- **类型**: USTRUCT(BlueprintType)
|
||
- **父类**: (无)
|
||
- **源文件**: Plugins/Item/Source/Item/Public/ItemContainer.h
|
||
- **模块**: Item
|
||
|
||
## 功能概述
|
||
一个轻量级的只读数据传输结构体，用于向UI提供物品的快照。包含物品标识（ID、Type）、显示信息（Name、Description、Icon）、当前位置（以TScriptInterface表示）以及格式化后的属性文本。
|
||
|
||
## 设计用意
|
||
将可变状态（FItemInstance）与只读视图分离，防止UI代码直接修改物品数据。快照模式确保即使底层物品发生移动，UI仍持有稳定数据。作为IItemContainer::GetItemViews()的返回类型，是容器到UI的数据桥梁。
|
||
|
||
## 职责范围
|
||
承载从容器到UI的物品显示数据。作为IItemContainer::GetItemViews()的返回类型使用。不拥有也不修改物品实例。
|
||
|
||
## 项目内依赖
|
||
（无项目内依赖 - 定义于ItemContainer.h中，仅包含引擎头文件）
|
||
|
||
## 对外接口
|
||
FItemView 是一个纯数据 USTRUCT（BlueprintType），所有字段标记为 BlueprintReadOnly，外部代码只能读取不能写入。调用方通过 IItemContainer::GetItemViews() 或 GetItemViewByID() 获取 FItemView 数组/单例，然后在 Blueprint 或 C++ 中读取以下字段：
|
||
|
||
- **ItemID** (FGuid): 物品的唯一标识符，由 ItemFactory::CreateItemInstance 生成（FGuid::NewGuid()）。
|
||
- **Location** (TScriptInterface<const IItemContainer>): 物品当前所在容器的只读接口引用。UI 可通过此字段判断物品属于哪个容器。
|
||
- **ItemType** (FName): 物品类型名称，对应 DataTable 中的行名（RowName）。
|
||
- **ItemName** (FText): 物品的显示名称，复制自 FItemDef::ItemName。
|
||
- **ItemDescription** (FText): 物品的描述文本，复制自 FItemDef::ItemDescription。
|
||
- **Icon** (TObjectPtr<UTexture2D>): 物品图标，复制自 FItemDef::DefaultIcon。
|
||
- **ItemDataText** (FText): 物品的动态属性格式化文本。由 FItemViewFactory::CreateView 遍历物品的 FInstancedPropertyBag，通过 IItemViewStrategy 格式化每个属性值后拼接而成。包含换行符分隔的多行属性描述。
|
||
|
||
注意：FItemView 是快照数据，不随物品状态变化自动更新。UI 需要在库存变化时重新获取。
|
||
|
||
## 使用方法
|
||
FItemView 由 FItemViewFactory 创建、由 IItemContainer 的查询方法返回，外部代码通常不直接构造。
|
||
|
||
**从容器获取物品视图（C++ 侧）：**
|
||
```cpp
|
||
// DefaultContainer.cpp:54-66
|
||
TArray<FItemView> UDefaultContainer::GetItemViews() const
|
||
{
|
||
TArray<FItemView> Results;
|
||
UItemRegistrySubsystem* Registry = GetRegistry(this);
|
||
if (!Registry) return Results;
|
||
Results.Reserve(Items.Num());
|
||
for (const TUniquePtr<FItemInstance>& Item : Items)
|
||
{
|
||
if (!Item) continue;
|
||
FItemDef Def = Registry->GetItemDef(Item->ItemType);
|
||
Results.Add(FItemViewFactory::CreateView(Registry, Def, *Item,
|
||
TScriptInterface<const IItemContainer>(this)));
|
||
}
|
||
return Results;
|
||
}
|
||
```
|
||
|
||
**在 Blueprint 中消费 FItemView：**
|
||
UI Widget（如 WBP_InventoryView）通过引用 BP_InventoryComp 组件，从其 ViewCache 读取 FItemView 数组，然后访问 ItemName、Icon、ItemDataText 等字段绑定到 UI 控件进行显示。FItemView 的所有字段均为 BlueprintReadOnly，可以直接在 Blueprint 中读取但不可修改。
|
||
|
||
## 用例
|
||
- `Plugins/Item/Source/Item/Private/DefaultContainer.cpp:54-66` -- GetItemViews() 遍历内部 Items 并为每个物品调用 FItemViewFactory::CreateView 构造 FItemView，作为 TArray 返回。
|
||
- `Plugins/Item/Source/Item/Private/DefaultContainer.cpp:69-81` -- GetItemViewByID() 按 FGuid 查找单个物品并返回其 FItemView。
|
||
- `Plugins/Item/Source/Item/Public/Inventory.h:27` -- IInventory 接口声明 GetItemViews() 返回 TArray<FItemView>，Bridge 到面向 Blueprint 的接口。
|
||
- `Plugins/Item/Source/Item/Private/ItemViewFactory.cpp:11-19` -- PopulateCommon 填充 FItemView 的通用字段（ItemID、ItemType、ItemName、ItemDescription、Icon、Location）。
|
||
- `Plugins/Item/Source/Item/Private/ItemViewFactory.cpp:57-85` -- CreateView 完整构造 FItemView，包括通过策略格式化动态属性文本。
|
||
- `Document/Content/Blueprints/WBP_InventoryView.md` -- UI Widget 读取 FItemView 数组，绑定 ItemName、Icon、ItemDataText 到 UI 控件显示。
|