init

Plugins/Item/FItemView.md

@@ -0,0 +1,66 @@
+# 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 控件显示。