企业官网建设流程全解析

如何为MLB-LED-Scoreboard开发插件：bullpen API三件套与实战案例

【免费下载链接】mlb-led-scoreboardAn LED scoreboard for Major League Baseball :baseball:项目地址: https://gitcode.com/gh_mirrors/ml/mlb-led-scoreboard

如果你想在 MLB-LED-Scoreboard 这块 LED 记分牌上显示大联盟比赛之外的内容（新闻、天气、战绩表甚至地铁到站信息），只需实现 bullpen 插件 API 的"三件套"——配置类、数据类、渲染器。本指南带你用最少的代码完成一个可用的插件开发。

认识 bullpen：记分牌插件框架

MLB-LED-Scoreboard 从 9 版本开始支持插件机制。bullpen是项目内置的插件开发框架（API 位于 bullpen/src/bullpen/），它把"一块屏幕"抽象成三个职责清晰的组件，整个接口都带有完整的类型提示，IDE 会自动补全，对新手非常友好。

三个类分别负责：

第一步：编写 Config 配置类

Config构造时接收一个MLBConfig对象，其中plugin_config字典来自用户config.json里plugins.你的插件名的键值。

建议在这里完成所有校验和预处理——它只会被构造一次，之后会被反复访问。官方示例里 Config 只有一行核心代码：从plugin_config中取出step并设置默认值 1，可参考 bullpen/example-plugin/src/mlb_led_scoreboard_example_plugin/init.py。

第二步：编写 Data 数据类

Data构造时接收你的 Config 实例，唯一必须实现的方法是update()，它返回一个UpdateStatus枚举（成功、失败、推迟三种状态）。

⚠️最重要的新手陷阱：update()每秒会被调用多次！如果你的数据来自网络请求，务必像内置的 news 和 standings 插件一样，加一个"距上次刷新是否足够长时间"的判断。例如 standings 插件就把刷新间隔硬编码为 15 分钟（见 standings/src/mlb_led_scoreboard_standings/standings.py 中的STANDINGS_UPDATE_RATE）。

当update()返回失败时，记分牌会显示红色感叹号，提醒用户网络出了问题——这个提示机制是框架免费提供的。

第三步：编写 Renderer 渲染类

渲染器是最"花功夫"的部分，构造时接收 Config、Layout（布局/字体信息）和Color（配色信息）三个对象。它需要实现：

• render()：绘制单帧画面，会连续被多次调用，千万不要在里面写自己的渲染循环。它依次接收 Data 对象、Canvas 画布、graphics 绘图模块、当前滚动文本位置；如果用了滚动文本，需返回新的滚动位置
• wait_time()：两次render()调用的间隔秒数，有滚动文本时建议返回用户配置的scrolling_speed，否则 1 秒左右即可

可选的两个方法：

• can_render(data)：返回False时，本轮轮播直接跳过你的插件（适合"没有数据就不显示"的场景）
• reset()：记分牌轮播离开你的屏幕时调用，用来清理内部状态

绘图时直接用graphics.DrawText/DrawLine/DrawCircle等方法操作 Canvas，完整示例见 news/src/mlb_led_scoreboard_news/renderer.py——新闻插件同时展示了时钟、天气图标和滚动标题的绘制方式。

注册插件：通过 entry point 接入

类写好了，还需要告诉记分牌"怎么找到你"。定义一个load()函数返回三个类，再在pyproject.toml中注册到bullpen.mlbled.plugin入口点：

[project.entry-points.'bullpen.mlbled.plugin'] "example" = "mlb_led_scoreboard_example_plugin:load"

def load() -> api.PLUGIN_DEFINITION: return Config, Data, Renderer

完整注册语法直接抄 bullpen/example-plugin/pyproject.toml 即可。

实战案例：向内置插件学经验

项目自带的news和standings屏幕本身就是用 bullpen API 写的插件，是最佳的参考实现：

• 📰news 插件（news/src/mlb_led_scoreboard_news/）：展示了网络请求限速、15x15 天气图标绘制、scrolling_text滚动文本的完整用法
• 📊standings 插件（standings/src/mlb_led_scoreboard_standings/）：展示了如何轮播多个大区的战绩表，以及如何调用 MLB StatsAPI 获取数据

开发前建议先pip install这两个包阅读源码，它们比任何教程都直观。

善用 bullpen 内置工具

写插件前别重复造轮子，框架自带两个高频助手：

• 日志：bullpen/src/bullpen/logging.py 中的LOGGER会根据用户的debug设置决定是否输出详细信息
• 滚动文本：bullpen/src/bullpen/util.py 中的scrolling_text专门处理超出屏幕宽度的长文本，还有center_text_position辅助居中

快速上手检查清单

1. ✅ 克隆项目：git clone https://gitcode.com/gh_mirrors/ml/mlb-led-scoreboard
2. ✅ 通读 bullpen/README.md（官方 API 文档，很短）
3. ✅ 复制 bullpen/example-plugin/ 作为插件骨架
4. ✅ 实现 Config、Data、Renderer 三个类，update()中做好限速
5. ✅ 在pyproject.toml注册bullpen.mlbled.plugin入口点
6. ✅ 提醒用户：在config.json的screens轮播中加入你的屏幕，并在plugins键下提供配置

完成这些，你的自定义屏幕就会出现在记分牌的轮播列表里。祝开发顺利，大联盟休赛期也不再无聊 ⚾

【免费下载链接】mlb-led-scoreboardAn LED scoreboard for Major League Baseball :baseball:项目地址: https://gitcode.com/gh_mirrors/ml/mlb-led-scoreboard