商店排版提供器（开发者指南）

商店排版提供器系统允许开发者自定义商店告示牌的结构及渲染方式。

截至 6.2.0.11，商店布局已不再为硬编码。 它们可以通过 IShopLayoutProvider 接口控制，这可以：

• 自定义告示牌文本行顺序
• 不同商店类型不同排版（购买、出售、冻结或其他自定义类型）
• 解决动态排版问题
• 完全代替默认排版系统

本章节教程会解释如何获取、覆写或实现自定义排版提供器。

---

概览

排版提供器决定了商店告示牌的排布方式。

以前为硬编码：

第一行 → 标题
第二行 → 交易信息
第三行 → 交易物品 第四行 → 价格

系统现在完全可以通过以下方式自定义内容：

• 配置文本中的排版定义
• IShopLayoutProvider 自定义实现
• 运行时覆写

默认实现为 SimpleShopLayoutProvider。

---

获取排版提供器

返回当前排版提供器：

ShopManager manager = api.getShopManager();
IShopLayoutProvider provider = manager.shopLayoutProvider();

用自定义提供器代替原本排版提供器：

ShopManager manager = api.getShopManager();
manager.shopLayoutProvider(new MyCustomLayoutProvider());

替换后，你的实现就可以控制商店排版的样式。

---

理解 IShopLayoutProvider

IShopLayoutProvider 决定了排版数据的返回与解析方式。

它负责：

• 提供每个商店类型的排版配置
• 选择使用的排版
• 提供格式化的行键名
• 允许未来扩展性

默认实现会从配置文本读取排版定义，并按商店类型显示不同内容。

---

默认排版示例

基于配置的默认排版示例如下：

layout:

  BUYING:
    line1: "header"
    line2: "trading"
    line3: "item"
    line4: "price"

  FROZEN:
    line1: "header"
    line2: "trading"
    line3: "item"
    line4: "price"

  SELLING:
    line1: "header"
    line2: "trading"
    line3: "item"
    line4: "price"

每一行都与排版组件关键词匹配。

填入空字符串（""）表示空行。

排版提供器会将它们解析为自定义的告示牌内容。

---

创建自定义样式提供器

你可以通过实现 IShopLayoutProvider 覆写默认行为。

示例最小实现：

public class MyCustomLayoutProvider implements IShopLayoutProvider {

    @Override
    public ShopLayout provideLayout(Shop shop) {

        ShopLayout layout = new ShopLayout();

        layout.setLine(1, "自定义标题");
        layout.setLine(2, "店主：" + shop.getOwnerName());
        layout.setLine(3, shop.getItem().getType().name());
        layout.setLine(4, "$" + shop.getPrice());

        return layout;
    }
}

然后注册：

ShopManager manager = api.getShopManager();
manager.shopLayoutProvider(new MyCustomLayoutProvider());

现在，你的布局就可以改变所有的商店告示牌。

---

不同类型的排版控制

因为这个系统不再依赖旧版本的 ShopType 常量，排版现已支持：

• 内置类型（购买、出售、冻结）
• 自定义商店类型
• 附属定义的商店类型

你的提供器可以动态决定排版逻辑：

@Override
public ShopLayout provideLayout(Shop shop) {

    if (shop.getShopType().key().equals("FROZEN")) {
        return frozenLayout(shop);
    }

    return defaultLayout(shop);
}

这使得条件格式、本地化排版适应或者特殊事件排版成为可能。

---

进阶自定义

自定义排版提供器可以：

• 从外部插件获取数据
• 注入动态变量
• 不同玩家不同排版
• 实现格式逻辑
• 覆盖颜色样式
• 应用基于区域的格式
• 实现动态告示牌

因为排版提供器在运行时解析，你可以动态计算排版而非读取静态配置。

---

代替与拓展默认提供器的区别

你有两个选择：

完全代替：

manager.shopLayoutProvider(new MyCustomLayoutProvider());

或者拓展默认的实现：

public class ExtendedLayoutProvider extends SimpleShopLayoutProvider {

    @Override
    public ShopLayout provideLayout(Shop shop) {
        ShopLayout base = super.provideLayout(shop);

        base.setLine(1, "[Extended] " + base.getLine(1));

        return base;
    }
}

如果只需要小部分修改内容，考虑拓展更加合适。

---

最佳做法

保持排版代码简洁。

避免：

• 大量数据库调用
• 阻塞读写
• 复杂的网络调用

在商店更新与告示牌刷新事件时生成排版。

安全处理空值。

确保每一行排版都不超出告示牌字数限制。

非必要不硬编码商店类型。

若排版支持自定义商店类型，请正确验证键名。

---

示例完整注册

public class LayoutAddon {

    public void register(QuickShopAPI api) {

        ShopManager manager = api.getShopManager();

        manager.shopLayoutProvider(new MyCustomLayoutProvider());
    }
}

---

总结

商店排版提供器系统允许完全控制告示牌的显示内容。

通过获取：

ShopManager manager = api.getShopManager();

以及设置：

manager.shopLayoutProvider(new MyCustomLayoutProvider());

你可以重新设置服务器上每个商店的显示内容。

这个系统旨在支持：

• 扩展性
• 自定义商店类型
• 本地化
• 动态格式
• 未来的扩展