> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 页面、动作与生命周期

> 35页的逻辑 ID、主题模板、真实动作与提供者生命周期约定。

呈现器读取当前页面快照和已登记动作；页面身份、数量范围、报价与交易结果继续由服务端控制。

<h2 id="页面、动作与生命周期">
  页面、动作与生命周期
</h2>

`UiPage.key()` 是逻辑页面 ID，`UiPage.template()` 是主题选择 ID。原版 `menus` 配置按逻辑 ID，IA `pages` 按模板 ID。

完整35页及主要动作如下，标记“同名”的页面使用自己的页面 ID 作为模板。

<h3 id="市场与发布">
  市场与发布
</h3>

| 页面 ID | 模板 ID | 主要动作 |
| - | - | - |
| `home` | 同名 | 紧凑首页：三类交易、头像、钱包、领取、我的挂单；旧首页保留原入口 |
| `profile` | 同名 | 界面偏好、自己的待核对操作、历史、按权限显示的管理入口及返回 |
| `browse` | `browse` / `orders` | 搜索筛选、翻页、详情；个人订单使用 `orders` |
| `browse-filters` | 同名 | 类型、币种、材料、排序、搜索 |
| `order` | `detail` | 购买、供货、出价、撤单前确认 |
| `details` | 同名 | 查看长文本和条件 |
| `editor` | 向导模板，见下文 | 类型、物品或条件、数量、价格、时长 |
| `confirm` | `confirm` / `wizard-confirm` | 最终确认、返回 |
| `preview` | 同名 | 当前规则的背包匹配检查 |
| `supply-preview` | `supply` | 保护格、数量、最大可交、刷新、确认 |

发布编辑器的模板依步骤为 `wizard-type`、`wizard-item`、`wizard-terms`（收购）、`wizard-sale-terms`（出售）、`wizard-auction-terms`（拍卖）；最后确认使用 `wizard-confirm`。

<h3 id="输入与条件">
  输入与条件
</h3>

| 页面 ID | 模板 ID | 主要动作 |
| - | - | - |
| `number` | 同名 | 增减、预设、实际可用最大值、自定义输入 |
| `materials` | 同名 | 多选、筛选、主手导入 |
| `durability` | 同名 | 范围、预设、导入、清除 |
| `text-condition` | 同名 | 精确／包含、聊天输入、导入、清除 |
| `enchantments` | 同名 | 按中文名／英文名／ID 搜索、清空搜索、选择、导入、额外附魔开关 |
| `enchantment-range` | 同名 | 最低／最高等级、移除 |
| `insufficient` | 同名 | 所需金额和充值入口 |

<h3 id="资产与管理">
  资产与管理
</h3>

| 页面 ID | 模板 ID | 主要动作 |
| - | - | - |
| `wallet` / `wallet-currency` | `wallet` | 查看余额、充值／提现确认 |
| `assets` | `claims` | 查看资产、领取 |
| `history` / `receipt` | `history` | 翻页、只读收据、按需查看／复制操作编号 |
| `admin` / `admin-player` | 同名 | 待核对与指定玩家审计入口 |
| `admin-wallet` / `admin-assets` | 同名 | 指定玩家余额／全状态资产只读查看 |
| `admin-orders` / `admin-player-history` | 同名 | 指定玩家订单／历史只读查看 |
| `resolve-source` | `resolve` | 外部请求停止声明与再次确认 |
| `doctor` | 同名 | 节点、数据库、授权、充提诊断 |
| `inspect` / `evidence` | `inspect` | 结构化证据与合法核对入口 |
| `ui` / `themes` | 同名 | 选择后端、主题或恢复默认 |
| `result` | 同名 | 状态、收据、钱包、领取和继续浏览 |

<h2 id="首页与个人中心槽位">
  首页与个人中心槽位
</h2>

默认紧凑首页的原始槽位为 `0` 头像、`4` 提示、`8` 领取、`20/22/24` 三类交易、`45` 钱包、`53` 我的挂单。

`profile` 使用 `20` 界面偏好、`22` 待核对、`24` 历史、`31` 管理与 `49` 返回；管理入口随权限显示。待核对列表复用 `history` 页面。

首页布局可通过 `gui.home-layout: auto|compact|legacy` 选择；已有 `menus.home` 在 `auto` 下保留旧首页，迁移规则见[原版 GUI 个性化](/kitemarket/guide#原版-gui-个性化)。

呈现器应读取当前快照和动作，不假设所有首页都使用同一组槽位。

<h2 id="数量、金额与结果">
  数量、金额与结果
</h2>

数量最大值按实际钱包、可用背包物品及币种限额计算，拍卖只取主手这一堆；充值和提现使用真实余额及可预查的后端容量。

报价变化会要求重新选择，最终提交仍重新校验，主题不得自行放宽上限。

收据提供独立的“查看／复制操作编号”动作，在聊天中显示完整编号和复制入口；摘要保持简短，`inspect` 与只读 API 仍保留编号。

<h3 id="交易展示">
  交易展示
</h3>

一口价按每件单价部分购买，每单最低购买量默认1，可在发布时设为1至发布数量；余量不足最低量时只能买完全部余量。收购按单价分批供货，竞拍起价为整标总价。

主题直接使用服务端金额、输入范围与商品说明。数量、总量与已成交量独立展示，保留真实物品属性。

商品时间和倒计时只反映当前展示，不替代数据库截止校验。领取仍遵守物品自身堆叠上限，空间不足时留在领取箱。

<h2 id="动作与输入">
  动作与输入
</h2>

动作清单以当前 `page.actions()` 的槽位→不透明令牌为准。没有令牌的格子只展示信息；不得自己制造动作字符串，或将上一页面的令牌复用到新页。

每次打开或更新都替换页面身份、令牌与回调。

输入通过 `UiCallbacks.input(raw)`，关闭通过 `closed()`；`prompt()` 返回 `false` 时主插件继续使用聊天输入并保留草稿。

<h2 id="提供者生命周期">
  提供者生命周期
</h2>

| 接口 | 生命周期约定 |
| - | - |
| `register(owner, provider)` | 注册启用中的所属插件，返回可重复关闭的注销句柄 |
| `unavailable(...)` | 只检查本页可用性；`null` 表示就绪，其余为原因码 |
| `open(...)` / `update(...)` | 在玩家上下文呈现克隆快照，替换全部绑定 |
| `refresh(...)` | 可选同身份原地显示刷新；保留绑定，不重开；默认 `false` |
| `isOpen(...)` / `close(...)` | 只识别、关闭自己当前的视图 |
| `prompt(...)` | 原生输入或 `false` 交给主插件聊天输入 |
| `changed(owner)` | 实际资源变化后通知复查，不等于授予交易权 |

服务可能在数据库初始化后才注册。获取为空时监听 `ServiceRegisterEvent`，服务替换时丢弃旧句柄与页面；所属插件停用时注销，主插件会按会话保护回退。

不要在 Folia 全局线程读写玩家库存，示例不声明 Folia 认证。

<Card title="Java 呈现器开发" href="/kitemarket/ui-development/java#安装资源与实现提供者">
  提供者注册、页面更新、同页刷新与资源状态检查。
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.