方块/家具查询编辑指南

本文档说明如何向方块/家具查询页面添加、修改或删除条目。

数据文件位置

方块查询数据已按职责拆分到：

docs/.vitepress/theme/data/block-query/

常用文件：

文件	用途
`types.ts`	`BlockEntry`、`RecipeItem`、`CraftingRecipe` 等类型定义
`categories.ts`	中英文分类常量与分类类型守卫
`ingredients.ts`	可复用的合成原料常量
`blocks.functional.ts`	功能性方块
`blocks.furniture.ts`	家具
`blocks.tools.ts`	工具
`blocks.containers.ts`	容器
`blocks.plants.ts`	植物与作物
`blocks.decoration.ts`	装饰方块
`blocks.lighting.ts`	灯具
`blocks.other.ts`	其他
`index.ts`	聚合导出 `allBlocks`，通常无需手动修改

旧文件 docs/.vitepress/theme/components/block-list-data.ts 仅作为兼容导出层保留，新内容请优先添加到 data/block-query/ 下对应分类文件中。

编辑后，重启 npm run docs:dev 即可预览效果。

基础结构

每个条目是一个 BlockEntry 对象，添加到 allBlocks 数组中：

typescript

{
  id: 'unique-block-id',      // 必填，kebab-case 唯一标识
  icon: '/images/xxx/icon.png',  // 必填，图标路径
  nameZh: '方块中文名',        // 必填
  nameEn: 'Block English Name', // 必填
  categoryZh: '功能性方块',    // 必填，从下方分类中选择
  categoryEn: 'Functional Block', // 必填
  descriptionZh: '简短描述。',  // 必填，1~2 行
  descriptionEn: 'Short description.', // 必填
  obtainZh: '获取方式说明',     // 必填，可使用 HTML 标签
  obtainEn: 'How to obtain',    // 必填
  recipes: [                   // 可选，3×3 工作台合成表
    {
      pattern: [
        null, clayBall, null,
        clayBall, null, clayBall,
        clayBall, clayBall, clayBall,
      ],
      result: { nameZh: '方块中文名', nameEn: 'Block English Name', entryId: 'unique-block-id', icon: '/images/xxx/icon.png' },
      noteZh: '严格摆位。',
      noteEn: 'Shaped recipe.',
    },
  ],
  properties: { '硬度': '2.0' },  // 可选，属性键值对
  relatedIds: ['other-id'],     // 可选，关联方块 id 列表
}

分步操作

添加新条目

根据条目分类打开 docs/.vitepress/theme/data/block-query/blocks.*.ts 中对应文件
找到该文件导出的数组（如 functionalBlocks、furnitureBlocks）
在数组末尾（最后一个 ] 之前）追加新对象
注意：前一个条目末尾要有逗号

示例——添加一个新方块：

typescript

  // ─── 你自定义的分类 ───
  {
    id: 'my-custom-block',
    icon: '/images/teastory/my_block_icon.png',
    nameZh: '自定义方块',
    nameEn: 'My Custom Block',
    categoryZh: '装饰方块',
    categoryEn: 'Decoration',
    descriptionZh: '这是一个示例方块。',
    descriptionEn: 'This is an example block.',
    obtainZh: '工作台合成',
    obtainEn: 'Crafted at a crafting table',
    properties: { '硬度': '1.5', '发光等级': '0' },
    relatedIds: ['paddy-field'],
  },

修改条目

直接找到对应 id 的对象，修改任意字段即可。

删除条目

找到对应的对象，删除从 { 到 }, 的整段代码。

可用分类

中文	English
功能性方块	Functional Block
家具	Furniture
工具	Tool
容器	Container
植物与作物	Plants & Crops
装饰方块	Decoration
灯具	Lighting
其他	Other

字段规范

`id`

格式：kebab-case（全小写，连字符分隔）
示例：paddy-field、wooden-mortar-pestle、item-xian-rice-seedling
必须唯一，不可重复

`icon`

路径相对于站点根目录
图标建议 32×32 像素 PNG，透明背景，image-rendering: pixelated
图片放在 docs/public/images/ 下
- Teastory 相关图标放 docs/public/images/teastory/
- 原版 Minecraft 物品贴图放 docs/public/images/minecraft/block/ 或 docs/public/images/minecraft/item/
- 其他方块建议新建目录如 docs/public/images/blocks/

`nameZh` / `nameEn`

中英文名称都必须填写
英文名首字母大写（"Paddy Field" 而非 "paddy field"）

`descriptionZh` / `descriptionEn`

1~2 行简短描述
中英文都必须填写
不需要句号结尾的无特殊要求

`obtainZh` / `obtainEn`

获取方式说明
支持 HTML 标签，如 <span class="item-chip"><img src="..." alt="" />物品名</span>
纯文字说明也可以，如 '工作台合成'

`recipes`

可选字段；不填写则详情弹窗不显示合成表
每个配方的 pattern 必须正好 9 格，顺序为从左到右、从上到下
空槽用 null
原料可先在数据文件顶部定义为 RecipeItem 常量，再在多个配方中复用
entryId 可选；填写后原料或产物可点击打开对应条目详情，如 entryId: 'empty-tea-bag'
count 用于显示堆叠数量；如产物 count: 3 会在右下角显示 3
noteZh / noteEn 可说明“严格摆位”“无序配方示例摆位”“水桶是否返还”等
不要只凭“工作台合成”猜摆位；没有可靠摆位时可以先不填 recipes

示例：

typescript

const clayBall = { nameZh: '黏土球', nameEn: 'Clay Ball', icon: '/images/minecraft/item/clay_ball.png' }

recipes: [
  {
    pattern: [
      null, clayBall, null,
      clayBall, null, clayBall,
      clayBall, clayBall, clayBall,
    ],
    result: {
      nameZh: '陶壶（湿胚）',
      nameEn: 'Clay Kettle (Wet)',
      entryId: 'clay-kettle',
      icon: '/images/teastory/clay_kettle.png',
    },
    noteZh: '严格摆位。',
    noteEn: 'Shaped recipe.',
  },
]

`properties`

可选字段，不填则不显示属性表格
键值对格式，key 为属性名（中文），value 为属性值

示例：

typescript

properties: {
  '硬度': '2.0',
  '爆炸抗性': '3.0',
  '工具': '任何锹',
  '发光等级': '15',
}

`relatedIds`

可选字段，用于在详情弹窗底部显示关联方块
值为其他条目的 id 数组
示例：['tea-seeds', 'paddy-field']
引用的 id 必须存在于 allBlocks 中，否则不显示

图标准备

准备方块图标（建议 32×32 PNG，像素风）
放入 docs/public/images/ 下合适目录
在 icon 字段填写路径，如 /images/blocks/my_block.png

现有图标目录说明：

目录	用途
`/images/teastory/`	TeaStory 茶道相关物品（约 105 个）
`/images/minecraft/block/`、`/images/minecraft/item/`	Minecraft 原版物品贴图
`/images/`	通用截图和 logo

提示：如果还没有图标，可以先借用 teastory/ 下已有图标测试，正式上线前替换。

完整示例

以下是一个完整条目的参考：

typescript

{
  id: 'pot-zisha',
  icon: '/images/teastory/pot_zisha.png',
  nameZh: '紫砂壶',
  nameEn: 'Zisha Pot',
  categoryZh: '功能性方块',
  categoryEn: 'Functional Block',
  descriptionZh: '紫砂材质茶壶，保温性能优异，冲泡的茶饮品质更佳。',
  descriptionEn: 'Zisha clay tea pot with excellent heat retention, producing higher quality tea.',
  obtainZh: '使用 <span class="item-chip"><img src="/images/teastory/zisha_clay.png" alt="紫砂泥" />紫砂泥</span> 在工作台合成',
  obtainEn: 'Crafted from zisha clay',
  properties: {
    '保温加成': '+15%',
  },
  relatedIds: ['zisha-clay', 'zisha-clay-cup'],
},

注意事项

不要删除或修改 types.ts、categories.ts 与 index.ts 中的类型、分类和聚合逻辑，除非确实在调整数据结构
添加条目时注意在对应分类数组最后一个元素后面不能有逗号，但前面每个元素末尾都要有逗号
保持条目按分类分组，用注释 // ─── 分类名 ─── 分隔
尽量保持英文翻译同步更新，不要只写中文
编辑完成后运行 npm run docs:dev 确认页面正常渲染

方块/家具查询编辑指南 ​

数据文件位置 ​

基础结构 ​

分步操作 ​

添加新条目 ​

修改条目 ​

删除条目 ​

可用分类 ​

字段规范 ​

id ​

icon ​

nameZh / nameEn ​

descriptionZh / descriptionEn ​

obtainZh / obtainEn ​

recipes ​

properties ​

relatedIds ​

图标准备 ​

完整示例 ​

注意事项 ​

方块/家具查询编辑指南

数据文件位置

基础结构

分步操作

添加新条目

修改条目

删除条目

可用分类

字段规范

`id`

`icon`

`nameZh` / `nameEn`

`descriptionZh` / `descriptionEn`

`obtainZh` / `obtainEn`

`recipes`

`properties`

`relatedIds`

图标准备

完整示例

注意事项