服务配置

2026-09-20评分加载中…

一、功能介绍

服务配置能让插件感知 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_HANSzh-HansZH_HANTzh-Hant
ENenJAja
FRfrDEde
RUruKOko
ESesTRtr

说明: addLanguageObserver 注册后不会立即回调当前语言。首屏同步请显式调用一次 getCurrentLanguage()(如上例第 1 步)。相同语言不会重复通知,只有真实切换才回调。

2.2 移除监听(removeLanguageObserver)

页面销毁时用注册返回的 ID 取消监听:

override fun onDestroy() {
    super.onDestroy()
    configManager.removeLanguageObserver(listenerId)            // 传入 2.1 保存的监听器 ID
}

三、API 参考

以下接口方法的完整定义(含枚举)请查看 API 文档:IRemoteServerConfigManageropen in new window。

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 兜底即可。

最近修改: