> ## 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.

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

<span id="界面、主题与第三方开发" />

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

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

<Info>
  **版本与获取**

  本页对应 `1.0.0` 的公开 UI SDK。接口源码和示例通过[公开仓库](https://github.com/KiteMC/KiteMarket)提供，运行包、SDK 和示例文件名见[下载页](/kitemarket/download)。

  固定 Paper1.21.11／Java21／ItemsAdder4.0.16组合已有自有配置主题与 Java 市场示例的真实打开记录，具体范围见[兼容说明](/kitemarket/compatibility)，不推及其他版本或 Folia。
</Info>

<h2 id="快速开始">
  快速开始
</h2>

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

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

<Steps>
  <Step title="取得示例">
    从公开仓库取得 `examples/ui/themes/example-ia` 的配置示例；或者在公开发行后下载 `KiteMarket-Examples-1.0.0.zip` 中的 Java IA 例。
  </Step>

  <Step title="安装资源与主题">
    按[IA 接入](/kitemarket/dlc)安装自己的命名空间和主题文件，重建资源包并登记实际 UUID、SHA-1。
  </Step>

  <Step title="加载配置或插件">
    Java 示例还需将示例 JAR 放入 `plugins/`，正常重启；配置主题只需 `/km reload`。
  </Step>

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

<h2 id="java-示例-github-packages">
  Java 示例：GitHub Packages
</h2>

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

<Card title="查看 Java 示例依赖" href="/kitemarket/ui-development/java#java-示例-github-packages">
  Gradle、Maven、Packages 认证及 Release 下载备用方式。
</Card>

<h2 id="玩家选择与服务器默认值">
  玩家选择与服务器默认值
</h2>

玩家使用 `/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` 并回退，保留原偏好。

<h2 id="自有主题描述">
  自有主题描述
</h2>

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

<Card title="配置主题与 IA 资源" href="/kitemarket/ui-development/templates#自有主题描述">
  完整 YAML 示例、主题 ID 规则、状态背景及包加载确认。
</Card>

<h2 id="安装资源与实现提供者">
  安装资源与实现提供者
</h2>

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

<Columns cols={2}>
  <Card title="安装资源" href="/kitemarket/ui-development/templates#安装资源与包身份">
    独立命名空间、资源重建、下发及实际包身份。
  </Card>

  <Card title="实现 Java 提供者" href="/kitemarket/ui-development/java#安装资源与实现提供者">
    注册与注销、页面更新、显示刷新及真实示例。
  </Card>
</Columns>

<h2 id="自定义-ia-功能图标">
  自定义 IA 功能图标
</h2>

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

<Card title="功能图标配置" href="/kitemarket/ui-development/templates#自定义-ia-功能图标">
  Material 默认映射、物理槽位覆盖与只读图标绑定。
</Card>

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

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

<Card title="页面与动作清单" href="/kitemarket/ui-development/pages#页面、动作与生命周期">
  完整35页、首页槽位、数量规则、输入与生命周期约定。
</Card>

<h2 id="错误定位">
  错误定位
</h2>

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

<Card title="查看错误定位表" href="/kitemarket/ui-development/java#错误定位">
  主题、资源、占位标题、回调与重载问题。
</Card>

<h2 id="安装与使用范围">
  安装与使用范围
</h2>

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

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

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


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