服务配置
一、功能介绍
服务配置能让插件感知 Pilot 端的运行时配置。当前开放的是语言配置:插件可以查询 Pilot 当前使用的语言,并监听用户在 Pilot 里切换语言的事件,从而让插件界面的文案跟随 Pilot 保持一致,实现多语言联动。
1.1 能力总览
| 能力 | 描述 |
|---|---|
| 查询当前语言 | 获取 Pilot 当前使用的语言 |
| 监听语言变更 | 注册监听器,实时接收 Pilot 语言切换事件 |
| 移除监听 | 按注册返回的 ID 取消语言变更监听 |
1.2 应用场景
- 文案联动:Pilot 切换语言时同步切换插件界面文案
- 首屏适配:插件启动时按 Pilot 当前语言加载对应资源
二、接口调用示例
以下示例假设你已完成 SDK 初始化,且插件与 Pilot 已连接就绪(连接状态获取见插件连接状态文档)。所有接口都通过管理器单例 RemoteServerConfigManager.getInstance() 调用。
2.1 查询当前语言与监听变更(getCurrentLanguage / addLanguageObserver)
推荐的初始化模式是「先查一次当前语言做首屏同步,再注册监听后续变更」。addLanguageObserver 返回一个监听器 ID,供后续按 ID 取消:
val configManager = RemoteServerConfigManager.getInstance() // 获取管理器单例
// 1. 首屏同步:查询当前语言(未收到配置或未知时返回 null)
val current: RemoteLanguage? = configManager.getCurrentLanguage()
current?.let { applyLanguage(it) } // 按当前语言加载资源
// 2. 注册监听后续变更,保存返回的监听器 ID
val listenerId: Int = configManager.addLanguageObserver { language ->
applyLanguage(language) // Pilot 切换语言时回调
}
RemoteLanguage 的取值覆盖 Pilot 支持的语言,每个值带一个语言 tag:
| 枚举 | tag | 枚举 | tag |
|---|---|---|---|
ZH_HANS | zh-Hans | ZH_HANT | zh-Hant |
EN | en | JA | ja |
FR | fr | DE | de |
RU | ru | KO | ko |
ES | es | TR | tr |
说明:
addLanguageObserver注册后不会立即回调当前语言。首屏同步请显式调用一次getCurrentLanguage()(如上例第 1 步)。相同语言不会重复通知,只有真实切换才回调。
2.2 移除监听(removeLanguageObserver)
页面销毁时用注册返回的 ID 取消监听:
override fun onDestroy() {
super.onDestroy()
configManager.removeLanguageObserver(listenerId) // 传入 2.1 保存的监听器 ID
}
三、API 参考
以下接口方法的完整定义(含枚举)请查看 API 文档:IRemoteServerConfigManager。
IRemoteServerConfigManager 是服务配置管理接口总入口,对外开放以下方法:
| 项 | 说明 |
|---|---|
IRemoteServerConfigManager | 服务配置管理接口总入口 |
getCurrentLanguage | 获取当前语言(未知时返回 null) |
addLanguageObserver | 注册语言变更监听,返回监听器 ID |
removeLanguageObserver | 按 ID 取消语言变更监听 |
四、常见问题(FAQ)
Q1:getCurrentLanguage() 返回 null 怎么办?
表示尚未收到 Pilot 的语言配置(如连接刚建立),或语言 tag 未识别。此时可以先用插件默认语言兜底,待 addLanguageObserver 回调到语言变更后再切换。
Q2:注册监听后为什么没有立即收到当前语言?
这是设计行为。addLanguageObserver 只负责后续变更通知,不主动回调当前值。首屏同步请显式调用一次 getCurrentLanguage(),两者配合即可覆盖「首次 + 后续」。
Q3:为什么用 ID 而不是监听器对象来取消注册?
addLanguageObserver 用一个自增 ID 标识每次注册,removeLanguageObserver(id) 按 ID 精确取消。请务必保存注册时返回的 ID,在页面销毁时传回,避免监听长期驻留导致文案回调持有页面引用。
附录:说明
该模块的方法不使用错误码回调:getCurrentLanguage 直接返回枚举或 null,监听注册 / 取消也无错误码。连接未就绪时 getCurrentLanguage 会返回 null,按 Q1 兜底即可。