这页专门说明 HNSignIn 的界面配置现在放在哪里、每一块控制什么，以及改界面时最容易踩哪些坑。

当前版本里，GUI 已经从主 config.yml 中拆出，运行时会从独立目录加载：

plugins/HNSignIn/gui/
├─ calendar.yml
└─ confirm-dialogs.yml

---

一、两份 GUI 配置各自负责什么

calendar.yml

负责主签到界面：

• 标题
• 背包大小
• 日期格槽位
• 连签 / 累签奖励槽位
• 统计栏与关闭按钮
• 各种日期状态展示物品

confirm-dialogs.yml

负责二级确认页面：

• 当前默认主要是补签确认弹窗
• 标题
• 说明文本
• 信息物品
• 确认 / 取消按钮

可以这样记：

• 主界面排版 看 calendar.yml
• 补签确认弹窗 看 confirm-dialogs.yml

---

二、calendar.yml 结构总览

当前默认结构大致是：

title: '&8高级签到日历 &7- &f{player}'
size: 54

day-slots: []
streak-reward-slots: []
total-reward-slots: []
stats-slot: 35
close-slot: 53
fill-empty-slots: true

display:
  filler: ...
  today-available: ...
  signed: ...
  signed-make-up: ...
  missed-available: ...
  missed-locked: ...
  future: ...
  reward-claimable: ...
  reward-claimed: ...
  reward-locked: ...
  stats: ...
  close: ...

---

三、标题与尺寸

title

title: '&8高级签到日历 &7- &f{player}'

用于主页面标题。

常见可用占位符包括：

• {player}
• {today}
• {current_streak}
• {total_signed}

建议：

• 标题尽量短，不要塞太多动态信息
• 复杂信息更适合放到 stats 物品 Lore

size

size: 54

当前默认 6 行背包。

建议：

• 如果你不打算重排槽位，不要轻易改 size
• 一旦改 size，就必须同步检查所有槽位是否越界

---

四、核心槽位

day-slots

这组槽位决定“月历日期格”放在哪里。

默认是一块 7 列的月历区域。

注意：

• 数量至少要能容纳当月展示范围
• 建议保持 7 列结构，避免周视图错位
• 改槽位时，最好一并检查和奖励槽位、统计栏是否冲突

streak-reward-slots / total-reward-slots

分别用于：

• 连签档位奖励展示
• 累签档位奖励展示

如果你把它们改得太少，部分奖励档位可能没有可渲染位置。

stats-slot / close-slot

分别对应：

• 统计面板物品
• 关闭按钮

这两个槽位通常建议固定，不要和日期格混排。

fill-empty-slots

fill-empty-slots: true

表示是否用 display.filler 填充未占用槽位。

建议：

• 想要界面整洁时保持 true
• 想做更自由的空位视觉效果时再改为 false

---

五、display 下各状态物品

filler

空白填充物。

常见做法：

• GRAY_STAINED_GLASS_PANE
• 名称写 ' '
• lore: []

today-available

当前业务日且可签到时显示。

重点常用字段：

• {today}
• {reset_time}
• {total_signed}
• {current_streak}
• {monthly_final_reward_progress}
• {monthly_final_reward_target}

signed / signed-make-up

分别表示：

• 普通签到已完成
• 补签已完成

这里很适合展示：

• {signed_at}
• {calendar_day_reward}
• {total_signed}

missed-available / missed-locked

分别表示：

• 可以补签的漏签日期
• 已经不可补签的漏签日期

这里最值得展示：

• {make_up_window}
• {make_up_cost}
• {calendar_day_reward}
• {last_signed_date}

future

未来日期。

通常只做提示，不建议写太多信息。

当前版本里，未来日期点击已经在 GUI 层直接短路：

• 不会再继续打到补签异步链路
• 不会再因为未来日期点击产生无意义仓储读取与提示噪音

reward-claimable / reward-claimed / reward-locked

用于累签奖励槽位。

常用占位符：

• {days}
• {total_signed}
• {current_streak}

stats

统计面板。

当前最适合放：

• {today}
• {today_status}
• {reset_time}
• {month_signed}
• {total_signed}
• {current_streak}
• {fixed_cycle_key}
• {fixed_cycle_day}
• {fixed_cycle_signed}
• {personal_cycle_round}
• {personal_cycle_progress}
• {monthly_final_reward_progress}
• {monthly_final_reward_target}
• {make_up_cost}

close

关闭按钮。

一般只需要：

• 一个明显的材质
• 简单说明即可

---

六、confirm-dialogs.yml 结构

当前默认主要是：

make-up:
  title: '&8补签确认'
  description:
    - '...'
  info-item:
    material: CLOCK
    name: '...'
    lore: []
  confirm-button:
    material: LIME_WOOL
    name: '...'
    lore: []
  cancel-button:
    material: BARRIER
    name: '...'
    lore: []

title

弹窗标题。

description

说明文本区域，适合展示：

• {target_date}
• {make_up_cost}
• {calendar_day_reward}
• {total_signed}
• {current_streak}

info-item

中间说明物品，通常只作为上下文提示，不承担操作行为。

confirm-button / cancel-button

分别用于：

• 确认补签
• 取消并返回日历

建议：

• 确认按钮颜色明显偏正向
• 取消按钮颜色明显偏阻止 / 返回
• Lore 里写清楚点击后会发生什么

---

七、当前 GUI 可用占位符

GUI 文本里除了常见基础占位符，还常用这些：

• {today} / {target_date}
• {signed_at}
• {today_status}
• {month_signed}
• {make_up_window}
• {make_up_cost}
• {calendar_day_reward}
• {fixed_cycle_key} {fixed_cycle_day} {fixed_cycle_signed}
• {personal_cycle_round} {personal_cycle_progress}
• {monthly_final_reward_progress} {monthly_final_reward_target}

如果你想查更完整的占位符：

• 业务上下文占位符：看 config.yml 配置说明
• 对外 %hncore_sign_*%：看 PlaceholderAPI 占位符速查表

---

八、改 GUI 时最容易踩的坑

1）只改了 title / lore，没注意槽位结构

如果你同时改了：

• size
• day-slots
• stats-slot
• close-slot

那就不是“改文案”，而是在改布局，最好一次性整体检查。

2）把日期格和奖励格槽位重叠了

重叠后常见现象：

• 某些日期不显示
• 某些奖励槽被覆盖
• 统计栏位置异常

3）Lore 写太长导致信息噪音过大

特别是：

• today-available
• missed-available
• stats

这些物品很容易一口气塞太多内容。建议优先保留真正会影响玩家决策的信息。

4）把外部 %hncore_sign_*% 和内部 {...} 混用

GUI 配置里优先使用的是 HNSignIn 自身上下文占位符，也就是：

{current_streak}
{total_signed}

不要默认把 GUI 文本写成 %hncore_sign_streak% 这种外部占位符风格。

---

九、最推荐的改法

如果你只是想做轻量定制，建议按这个顺序改：

1. title
2. display.*.name
3. display.*.lore
4. stats 面板
5. confirm-dialogs.yml 文案
6. 最后才动槽位与尺寸

这样最稳，也最不容易把页面结构改坏。

---

十、最短记忆版

如果你只想先记关键点，可以直接记这句：

主日历看 calendar.yml，补签确认看 confirm-dialogs.yml；先改文案，最后再动槽位。 nt_streak}

不要默认把 GUI 文本写成 `%hncore_sign_streak%` 这种外部占位符风格。

---

## 九、最推荐的改法

如果你只是想做轻量定制，建议按这个顺序改：

1. `title`
2. `display.*.name`
3. `display.*.lore`
4. `stats` 面板
5. `confirm-dialogs.yml` 文案
6. 最后才动槽位与尺寸

这样最稳，也最不容易把页面结构改坏。

---

## 十、最短记忆版

如果你只想先记关键点，可以直接记这句：

> **主日历看 `calendar.yml`，补签确认看 `confirm-dialogs.yml`；先改文案，最后再动槽位。**