---
name: daoyou-item-preview
description: 万界道友物品预览的固定展示与接入规范。新增道具、调整预览字段/文案/层级/折叠交互，或重构 ItemSlot、ItemPreview、presentation 适配器时使用；覆盖背包及复用预览的炼器、货架等入口。纯战斗规则、掉落数值或持久化变更不单独触发。
---

# 物品预览规范

本规范固化多轮验收的展示选择。接入与重构默认保持这些选择，不借机重新设计。用户明确提出新要求时以新要求为准，并同步更新对应规范；历史截图、旧实现和验收日志不覆盖最新要求。

## 使用方式

1. 先读本文件，再按受影响类型读取 [分类基线](references/type-baselines.md)。公共组件变更需核对全部类型。
2. 核对当前共享物品定义、事实 schema 和适配器，列明本次变化的名称、头部顺序、正文、描述、交互。未要求变化的部分沿用基线。
3. 在拥有该职责的层修改，以文末清单验收。新增类型复用结构和语义；没有事实来源的字段不生成，不自行添加装饰或解释。

## 固定信息结构

顺序：**图标＋完整名称＋有意义的头部字段 → 分组数据／效果 → 独立描述 → 业务操作**。调用方的必要情境提示可位于头部之后。

- 借鉴梦幻西游的信息层次，保留本项目纸墨视觉。不要复制棕金皮肤，不给不同类型另造卡片、尺寸或主题。
- 头部由每类显式列出顺序。类型、要求、数量都不是必填；不先默认生成再逐类删除。每条信息必须有新增意义。
- 正文只保留有用的数据、效果与真实限制。空字段、空分组不占位；不补“暂无”“进入背包后判断”等兜底解释。
- 普通信息采用“分组标题 → 内容”。传承技能／功法已作为物品名时，不再添加同名标题形成第三层缩进。
- 命名能力可使用单层展开项；展开内容仅普通行。可折叠分组也仅包含普通行，不扩成任意递归详情树。
- 描述独立放在最后的信息栏。精简重复字段不等于截短描述；尤其图纸保留完整描述。没有描述事实的装备不编造背景文案。
- 不默认展示“无丹毒”“不占服用额度”等不存在的副作用或限制；这不是删除真实代价、真实使用限制的理由。

## 文案与视觉

- 数值用阿拉伯数字与符号：`1%`、`5%`、`1张`；不用“1个百分点”“五个百分点”等混合表达。只改表达，不改变加法／乘法、单位或计算结果。
- 要求用最短准确条件，如 `炼气初期`、`不高于金丹`、`金丹及以上`。不附“可御使”“当前境界可以服用”等赘语。
- 名称改动归共享物品定义，保证格子、预览、目录等一致，不只在浮层裁掉后缀。
- 沿用 `ItemPreviewView`：名称 `text-base leading-6 font-semibold`（16px），正文 `text-sm leading-6`（14px/24px）；名称按既定分级着色，分组标题琥珀色，收益青色，代价／限制朱色，描述次级墨色。
- 数值数据用 Tailwind 默认 `font-mono`，正文仍用正文字体；不要改全局等宽字体或新增数字字体 token。见 [数字排版规范](../../../docs/numeric-typography.md)。
- 颜色表达语义，缩进表达所属关系，不因内容少就加边框、标签、摘要或重复标题填满空间。
- 传承灵印的技能简述用次级墨色，默认收起的具体效果用正文色；展开入口用青色，让意象描述与数值规则一眼可分。
- 物品格与预览头部直接使用 `GameIcon purpose="artwork"`，图标契约仅接受字符串（emoji 或 `icon:名称`），不传入 React 元素。归元灵露统一使用 💧；emoji 与注册图片都遵循本地图片显示强度，名称、数量、角标和空格提示保持清晰。透明度交给共享组件，不在适配器或页面内计算。

## 组件职责：数据决定内容，视图只渲染

以下路径均相对 `apps/web/src/components/feature/items/`：

| 层 | 固定职责 |
| --- | --- |
| 共享物品定义／事实 | 正式名称、属性和规则的来源；不得为预览另造一份业务事实 |
| `presentation/types.ts` | 结构化契约：头部 field/quantity/status，正文 line/disclosure、分组与描述 |
| `presentation/{basic,equipment,consumable}.ts` | 读取本类事实，返回轻量 summary 和延迟执行的 preview(options)；自行决定完整有序的字段、分组、数量与状态 |
| `presentation/registry.ts` | 用 `satisfies Record<ItemDefinition['kind'], ItemAdapter>` 静态检查类型覆盖 |
| `itemPresentation.ts` | 格子、聊天和货架等轻量摘要入口；不提前构建效果正文 |
| `itemPreviewModel.ts` | 解析适配器，组装标题、图标、颜色和内容；不判断道具种类 |
| `ItemPreview.tsx` | 接入既有参数，传递查看上下文、数量标签和调用方操作 |
| `ItemPreviewView.tsx` | 仅渲染模型与统一样式／展开交互；不查定义、计算规则、判断 kind 或具体物品 ID |
| `ItemSlot.tsx`／业务调用方 | 浮层定位、开关、模态壳、情境提示和操作；API 写入与玩法选择不进纯预览 |

新增同类道具通常只改共享定义；新增 kind 才补适配器与注册。类型差异在适配器集中表达，同一 kind 的消耗品子类型在消耗品适配器处理。不要把这些差异搬到公共渲染层，也不要引入运行时插件系统或每物品一套 JSX。

消耗品分组用 `role`（effect/preview/restriction/source）和 `collapsible` 表达语义。符箓使用 `talismanDetailRows` 结构化行，确认文本由相同行格式化。禁止根据 key 子串、标题相等、切割中文冒号等方式反推语义；已删的无效字段应停止生成，不靠视图过滤掩盖。

## 交互边界

- PC 悬停延迟 350ms，移出后取消待打开的预览，允许移入浮层操作；默认触屏点击、键盘聚焦使用同一预览。备料等启用 `quickOnTouch` 的入口由触屏轻点执行快捷操作、长按 500ms 查看预览；移动手指时取消长按，长按后的点击不得重复执行操作。沿用原生 `popover=auto`、单个打开、Esc 关闭、视口避让和长内容内部滚动，不改成详情抽屉。
- 仅打开的预览挂载正文和业务操作。展开器蕴／器诀不能关闭浮层；处理 popover 的 toggle 时保持 `event.target === event.currentTarget` 边界，避免接收子级 details 事件。
- 物品栏不提供“移动”“合并”及对应目标选择、取消移动状态。拖拽移动是后续需求，不提前实现。
- 装备／卸下、转存、拆分、整理等现有适用操作仍由业务入口负责。转存不是已删除的格位移动。
- 物品栏预览不展示装备比较或差值箭头；替换、存入、取出等操作使用短文案。堆叠丹药的服用数量与操作排在同一紧凑区域，支持直接输入、逐颗增减和设为本次最多数量。
- 复杂参悟、灵兽技能选择等留在对应玩法页，不塞进预览。真实消耗和写入逻辑不由展示模型决定。

## 验收与防回退

- 对照分类基线逐项核对名称、头部顺序、数量、默认折叠、直接消耗、描述。不得恢复双加合计、归元后消耗、重复类型、三层传承标题或移动／合并。
- 检查公共模型组装与渲染是否新增 kind/ID 特判；摘要入口是否开始调用详细预览；正文是否出现任意 JSX 或从文案反解析数据。
- 改公共展示时覆盖装备、图纸、传承灵印、归元灵露、功法玉简、丹药、灵果，以及材料、灵种、符箓；同一物品在背包和受影响的其他入口命名、内容一致。
- UI 改动运行 `pnpm run lint`、`pnpm run build`，按 [测试规范](../../../docs/testing.md) 做本地浏览器检查：桌面／360px、长名称、长描述、空分组、键盘、触屏点击、Esc、展开后浮层仍在；涉及批量服用时检查数量上下限与快捷操作。不得用“编译通过”代替交互验收。
- 不在前端／服务端添加单元测试。改动纯共享领域逻辑时遵循领域 skill 和仓库测试规则；只改本规范时验证 skill、链接和 diff 即可。报告已执行与未执行的检查。

## 关联规范

- 场景布局同时遵循 [daoyou-game-ui](../daoyou-game-ui/SKILL.md)；预览本身是查看数据的决策层，不套用场景首屏的隐藏数值原则来删效果。
- 修改共享物品事实或规则时同时使用 [daoyou-game-core-domain](../daoyou-game-core-domain/SKILL.md)。
- [展示实现与历史记录](../../../docs/item-presentation-ui.md) 用于查代码脉络；历史记录中已被本规范替代的文案、操作和字体方案不可恢复。