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

# 界面、主题与第三方开发

KiteMarket 提供**完整原版 GUI＋ItemsAdder v4 兼容**。

第三方开发者可以自由制作、修改、自用、分发或独立销售自己的配置／Java 界面，**无需额外的 KiteMC 主题授权**。公开 SDK 与示例采用独立 MIT 许可，基础插件不内置 IA 主题资源。

> [!NOTE]
>
> **版本与获取**
>
> 基础呈现接口保留 v1.0.0 用法，公开仓库 `main` 已更新 v1.1 接口与示例；新增页面按 v1.1 页面清单处理。运行包、SDK 和示例以[下载页](https://www.kitemc.asia/kitemarket/download.md)实际公开版本为准。
>
> 固定 Paper1.21.11／Java21／ItemsAdder4.0.16组合已有自有配置主题与 Java 市场示例的真实打开记录，具体范围见[兼容说明](https://www.kitemc.asia/kitemarket/compatibility.md)，不推及其他版本或 Folia。

## 快速开始

只改原版外观时，使用[原版 GUI 文件配置](https://www.kitemc.asia/kitemarket/guide.md#原版-gui-个性化)，无需编写插件。

使用内置 IA 呈现器时，安装自有资源和主题声明即可；只有需要自定义呈现逻辑时才使用 Java SDK。

**1. 取得示例**

从公开仓库取得 `examples/ui/themes/example-ia` 配置示例；Java IA 例位于 `examples/ui-java`。使用与主插件匹配的源码或实际 Release 示例包，按版本选择对应文件。

**2. 安装资源与主题**

按[IA 接入](https://www.kitemc.asia/kitemarket/dlc.md)安装自己的命名空间和主题文件，重建资源包并登记实际 UUID、SHA-1。

**3. 加载配置或插件**

Java 示例还需将示例 JAR 放入 `plugins/`，正常重启；配置主题只需 `/km reload`。

**4. 选择并验证**

玩家成功应用指定包后使用 `/km ui itemsadder example-ia`；Java 例主题为 `example-ia-java`。确认按钮操作真实市场，开发时使用隔离角色和订单。

## Java 示例：GitHub Packages

Java 项目以 `compileOnly` 引用 UI SDK；公开 SDK 为 Java 11，真实 IA 示例适配代码为 Java 21。

> **[查看 Java 示例依赖](https://www.kitemc.asia/kitemarket/ui-development/java.md#java-示例-github-packages)**
>
> Gradle、Maven、Packages 认证及 Release 下载备用方式。

## 玩家选择与服务器默认值

玩家使用 `/km ui` 查看请求偏好、实际界面、主题和回退原因。指定后端及可选主题使用：

```text theme={null}
/km ui auto
/km ui vanilla
/km ui itemsadder example-ia
```

选择只保存偏好；没有真实提供者、客户端或资源未就绪时继续使用原版并说明原因。

设置页中的「选择主题」列出已登记主题的后端与可用原因，也可恢复服务器默认主题。偏好在同一市场网络内跨服保存；切换保留草稿，不能重复提交交易。

服务器自动顺序和默认主题示例：

```yaml theme={null}
gui:
  renderer: auto
  auto-order: [itemsadder, vanilla]
  default-themes:
    itemsadder: example-ia
```

玩家按钮、命令帮助和补全仅显示 auto／vanilla／itemsadder。

旧 `germ`／`dragoncore` 偏好、配置与 SDK 枚举保留读取，作为已有第三方扩展位置；开发者可以自行注册、维护并验证实际 provider。没有匹配已注册提供者时报告 `UI_BACKEND_RETIRED` 并回退，保留原偏好。

## 自有主题描述

配置主题使用 `themes/*.yml` 声明字体背景、页面覆盖和实际资源包身份；用 `/km reload` 校验并加载。

> **[配置主题与 IA 资源](https://www.kitemc.asia/kitemarket/ui-development/templates.md#自有主题描述)**
>
> 完整 YAML 示例、主题 ID 规则、状态背景及包加载确认。

## 安装资源与实现提供者

内置 IA 呈现器使用配置主题；Java 扩展自行注册提供者。两者都使用真实市场页面和服务端登记动作。

> **[安装资源](https://www.kitemc.asia/kitemarket/ui-development/templates.md#安装资源与包身份)**
>
> 独立命名空间、资源重建、下发及实际包身份。

> **[实现 Java 提供者](https://www.kitemc.asia/kitemarket/ui-development/java.md#安装资源与实现提供者)**
>
> 注册与注销、页面更新、显示刷新及真实示例。

## 自定义 IA 功能图标

功能按钮可使用自己注册的 IA 物品；真实 `subject()` 商品保留原样。

> **[功能图标配置](https://www.kitemc.asia/kitemarket/ui-development/templates.md#自定义-ia-功能图标)**
>
> Material 默认映射、物理槽位覆盖与只读图标绑定。

## 页面、动作与生命周期

原版 `menus` 使用逻辑页面 ID，IA `pages` 使用模板 ID。呈现器读取当前快照、动作令牌与输入范围。

> **[页面与动作清单](https://www.kitemc.asia/kitemarket/ui-development/pages.md#页面、动作与生命周期)**
>
> 完整页面与模板 ID、首页槽位、输入、动作及生命周期约定。

### 为完整交易流程提供主题

主题可以分别覆盖单品、整包、逐单批量、容器内容、来源领取、业务条件、社区、风险、自动化和管理页面。页面与模板 ID 由当前快照提供，不能按标题或按钮文字猜测。首页直接提供发布入口；个人中心集中收藏、订阅、历史、核对和按权限显示的管理功能。

配置主题继续使用 `schema: 1`，`pages.'*'` 提供通用背景，具体模板可覆盖字体图片、偏移和功能图标。结果页可按服务端 `result.status` 配置 `state-font-images`；数量、费用、资产去向和真实商品始终由主插件提供，不能烘焙成静态余额或成交状态。

IA 呈现器复用受保护的54槽库存和已登记动作。`UiPage` 中的商品槽已经是最终物理槽，不要再次将列表槽移位。真实 `subject()` 商品保留完整属性；主题仅替换功能图标与背景，输入仍使用服务端范围和聊天回退。

### 新页面、更新与安全回退

每次页面更新同时替换 token、pageVersion、动作与全部回调；同页倒计时刷新保持页面身份。切换主题、返回和刷新保留会话草稿，迟到结果不能覆盖新页面，旧动作不能重复提交。

自有 Java 呈现器可通过只读 `itemsAdderUnavailable(player, page, theme)` 检查本页资源；仅 `null` 表示就绪。检查不发送资源包、不改变偏好、不检查额外主题授权。资源缺失、页面不可用或提供者卸载时使用原版回退，保留玩家的后端与主题选择。

升级自有主题时逐项核对[全部页面及动作](https://www.kitemc.asia/kitemarket/ui-development/pages.md)，包括不同确认页的确认／取消位置。无效主题或配置候选不会替换现有有效配置。第三方提供者仍负责自己的实际引擎兼容性；完整页面声明和 SDK 注册成功不等于实服认证。

## 错误定位

先核对主题、provider 与实际包加载状态；页面过期时重新打开，不重放旧动作。

> **[查看错误定位表](https://www.kitemc.asia/kitemarket/ui-development/java.md#错误定位)**
>
> 主题、资源、占位标题、回调与重载问题。

## 安装与使用范围

服主使用自己的主题或取得第三方主题后，按[ItemsAdder 接入](https://www.kitemc.asia/kitemarket/dlc.md)安装资源并登记实际包身份；无需官方 DLC 商品 ID、签名或权益。

插件没有默认提供商业 IA 成品，主题不可用时保留原版界面。主插件自身仍按[网络授权](https://www.kitemc.asia/kitemarket/license.md)管理交易与资产退出。

[兼容状态](https://www.kitemc.asia/kitemarket/compatibility.md)分别记录基础插件、提供者和具体主题的证据。公开 SDK 和扩展注册不替代实际运行验收。


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