逐文件精读源码生成。行号基于当前工作区版本,仅用于快速定位。 本文件覆盖 16 个服务封装:account / config / proxy / cardConfig / dashboardConfig / theme / backgroundSettings / roleData / roleDetail / tab / tabSnapshot / tabIcons / messageStore / launcher / systemResource / tray。
职责:封装森空岛/游戏账户相关的全部 Tauri IPC 调用(登录、登出、刷新、扫码、验证码、选中账户、凭证刷新),并定义账户相关的 TS 类型。是前端访问账户后端的唯一入口层。
导出:类型 GameId、Account、SklandAccount、SklandGameScore、SklandPendant、SklandBackground、SklandUserStats、SklandGameInfo、SklandUserInfo、RoleDisplayInfo、LoginRequest、LoginResult、RefreshResult、SendCodeRequest、CodeLoginRequest、ScanLoginInfo、ScanStatus;函数 getAccounts、getSklandAccounts、saveSklandAccount、getSklandAccountRoles、getSklandUserInfo、getSklandUserInfoByCred、getSklandGames、addAccount、logoutAccount、batchLogout、refreshAccounts、sendVerificationCode、addAccountByCode、genScanLogin、scanStatus、addAccountByScan、saveSelectedRoles、getSelectedAccount、setSelectedAccount、checkAndRefreshCred、applyApiHealthSnapshot;别名常量 refreshAccountData、batchLogoutAccounts。
主要依赖:@tauri-apps/api/core 的 invoke、./logger 的 logger / logError、./startupProgress 的 trackStartupTask、./accountAvailability(clearAccountUnavailable / setAccountUnavailable / reasonFromApiKind)、./crashReporting 的类型 ApiHealthSnapshot。
| 符号 | 位置 | 说明 |
|---|---|---|
getAccounts |
accountService.ts:211 | invoke get_accounts,无参,返回 Account[];启动 Splash 跟踪期间计入初始任务;成功且非空时 clearAccountUnavailable(),失败 logError + setAccountUnavailable("unknown") 后返回 [](不阻塞进入应用) |
getSklandAccounts |
accountService.ts:223 | invoke get_skland_accounts,无参,返回 SklandAccount[];失败返回 [] |
saveSklandAccount |
accountService.ts:232 | invoke save_skland_account,参数 {cred, token, userId},返回 boolean;失败返回 false |
getSklandAccountRoles |
accountService.ts:245 | invoke get_skland_account_roles,参数 {userId},返回 LoginResult;失败返回 {success:false, errorMessage:String(error)} |
getSklandUserInfo |
accountService.ts:259 | invoke get_skland_user_info,参数 {userId},返回 SklandUserInfo;无 try/catch,错误向上抛 |
getSklandUserInfoByCred |
accountService.ts:460 | invoke get_skland_user_info_by_cred,参数 {cred, token},返回 SklandUserInfo | null(不读本地配置,用于「确认绑定森空岛账户」页展示头像/昵称);失败 logError 后返回 null |
getSklandGames |
accountService.ts:269 | invoke get_skland_games,参数 {userId, force}(force 默认 false,后端带缓存),返回 SklandGameInfo[];无 try/catch,错误向上抛 |
addAccount |
accountService.ts:281 | invoke add_account,参数 {loginRequest}(手机号+密码+可选 expectedUserId),返回 LoginResult;成功时 clearAccountUnavailable();失败返回 {success:false, errorMessage, account:undefined} |
logoutAccount |
accountService.ts:302 | invoke logout_account,参数 {accountId, keepDeviceToken}(默认 true,保留设备认证跳过新设备验证),返回 boolean;失败返回 false |
batchLogout |
accountService.ts:319 | invoke batch_logout,参数 {accountIds},返回 boolean;失败返回 false |
refreshAccounts |
accountService.ts:332 | invoke refresh_accounts,无参,返回 RefreshResult;成功且非空时 clearAccountUnavailable(),失败 setAccountUnavailable("unknown") 并返回 {success:false, errorMessage, accounts:[], refreshTime:当前ISO时间} |
refreshAccountData |
accountService.ts:350 | refreshAccounts 的别名导出(旧命名兼容),非独立实现 |
batchLogoutAccounts |
accountService.ts:351 | batchLogout 的别名导出(旧命名兼容),非独立实现 |
sendVerificationCode |
accountService.ts:358 | invoke send_verification_code,参数 {request}(SendCodeRequest),返回 boolean;失败返回 false |
addAccountByCode |
accountService.ts:372 | invoke add_account_by_code,参数 {loginRequest}(手机号+验证码+可选 expectedUserId),返回 LoginResult;成功时 clearAccountUnavailable();失败用 logger.error(..., "AccountService") 记录并返回 {success:false, errorMessage} |
genScanLogin |
accountService.ts:391 | invoke gen_scan_login,无参,返回 ScanLoginInfo | null;失败返回 null |
scanStatus |
accountService.ts:405 | invoke scan_status,参数 {scanId},返回 ScanStatus | null;失败返回 null |
addAccountByScan |
accountService.ts:420 | invoke add_account_by_scan,参数 {scanCode, expectedUserId}(后者为 null 时不校验账户),返回 LoginResult;成功时 clearAccountUnavailable();失败记录日志并返回 {success:false, errorMessage}。重新登录时传目标 userId:后端校验登录账户是否一致,不一致返回 ACCOUNT_MISMATCH:<实际userId> 且不落盘凭证 |
applyApiHealthSnapshot |
accountService.ts:447 | applyApiHealthSnapshot(snapshot):blocked 时用 reasonFromApiKind 把熔断原因写入账户不可用状态(账户页启动时经 invoke("get_api_health") 兜底调用) |
saveSelectedRoles |
accountService.ts:480 | invoke save_selected_roles,参数 {cred, token, userId, selectedRoles},返回 Account[](创建的账户列表);失败记录日志后重新 throw |
getSelectedAccount |
accountService.ts:498 | invoke get_selected_account,无参,返回 string | null(当前选中账户 ID);启动 Splash 跟踪期间计入初始任务;失败记录日志并返回 null |
setSelectedAccount |
accountService.ts:512 | invoke set_selected_account,参数 {accountId},返回 boolean;失败返回 false |
checkAndRefreshCred |
accountService.ts:526 | invoke check_and_refresh_cred,参数 {userId},返回 [cred, token] | null(null 表示无需刷新);失败记录日志后重新 throw |
deleteSklandAccount |
accountService.ts(新增) | invoke delete_skland_account,参数 {userId},返回 boolean(账号不存在为 false);彻底删除父账户 + 全部角色 + 全部凭据,与 logoutAccount(只解绑单角色)不同 |
authorizeRoleU8Token |
accountService.ts(新增) | invoke authorize_role_u8token,参数 {roleId},返回 RoleU8AuthResult(status ∈ authorized / failed,另有 message);失败返回 {status:"failed", message} |
revokeRoleU8Token |
accountService.ts(新增) | invoke revoke_role_u8token,参数 {roleId},返回 boolean(是否确实取消了授权);失败返回 false |
内部结构:
| 区间 | 内容 |
|---|---|
| accountService.ts:1-211 | 全部接口/类型定义(账户、森空岛资料、登录/扫码/验证码请求与结果;GameId、Account.game?、SklandAccount.phone、RoleDisplayInfo(含 game / bindingUid / channelName / u8Authorized)、RoleU8AuthStatus / RoleU8AuthResult、LoginRequest.expectedUserId、CodeLoginRequest.expectedUserId) |
| accountService.ts:203-536 | 各 IPC 包装函数实现(含新增的 authorizeRoleU8Token / revokeRoleU8Token) |
备注:
- 封装的 invoke 命令:
get_accounts、get_skland_accounts、save_skland_account、get_skland_account_roles、get_skland_user_info、get_skland_user_info_by_cred、get_skland_games、add_account、logout_account、delete_skland_account、batch_logout、refresh_accounts、send_verification_code、add_account_by_code、gen_scan_login、scan_status、add_account_by_scan、save_selected_roles、get_selected_account、set_selected_account、check_and_refresh_cred、authorize_role_u8token、revoke_role_u8token(共 23 个)。 - 游戏标识:
GameId = "endfield" | "arknights",对应后端models::role::GAME_*常量。Account.game?与RoleDisplayInfo.game?都是可选字段,缺失时按终末地处理(后端三处结构体都带#[serde(default = "default_game")])。明日方舟角色没有头像(avatarUrl为空串),也没有终末地那套角色数据接口。 - 抽卡授权:
authorizeRoleU8Token/revokeRoleU8Token是唯一入口,前端从不接触令牌明文 —— u8token 不落盘、每次同步由后端现换。官服与 B 服走同一条链路,没有「渠道服不支持」分支。 - 配置键:本文件不直接读写任何配置键;选中账户由后端命令
get_selected_account/set_selected_account管理(对应后端配置键在 Rust 侧,前端未出现字面量)。 - 缓存策略:无前端缓存,每次调用直接 IPC;森空岛游戏列表的缓存由后端负责(
getSklandGames的force参数控制强制刷新)。 - 错误处理不统一:
getSklandUserInfo、getSklandGames不捕获错误;saveSelectedRoles、checkAndRefreshCred记录日志后 rethrow;其余函数均吞掉错误并返回空值/false。 - 账户可用性:
getAccounts/refreshAccounts/三个登录入口在成功时清除不可用状态,失败时标记(详见src/utils/accountAvailability.ts)。
职责:通用键值配置读写层,封装 Tauri get_config/set_config/remove_config/get_all_configs/get_secret_storage_status,并在 Tauri 调用失败时自动降级到浏览器 localStorage(开发环境兜底)。
导出:getConfig、setConfig、removeConfig、getAllConfigs、getSecretStorageStatus;类型 SecretBackend、SecretStorageStatus。
主要依赖:@tauri-apps/api/core 的 invoke、@/utils/logger 的 logger。
| 符号 | 位置 | 说明 |
|---|---|---|
getConfig<T> |
configService.ts:10 | invoke get_config,参数 {key},返回 T | null(undefined 归一为 null);启动 Splash 跟踪期间会计入初始任务;失败时 logger.warn 并读取 localStorage 的 config_${key}(JSON.parse)作兜底 |
setConfig |
configService.ts:26 | invoke set_config,参数 {key, value},返回 void;失败时 logger.warn 并写入 localStorage config_${key}(JSON.stringify)。 |
removeConfig |
configService.ts:41 | invoke remove_config,参数 {key},返回 boolean;失败时 logger.warn、移除 localStorage 同名键并固定返回 true |
getAllConfigs |
configService.ts:55 | invoke get_all_configs,无参,返回 Record<string, any>;后端会剔除机密字段;失败时遍历 localStorage,取所有 config_ 前缀键、去掉前 7 个字符作为配置键并 JSON.parse 后返回 |
getSecretStorageStatus |
configService.ts:89 | invoke get_secret_storage_status,无参,返回 SecretStorageStatus | null(失败返回 null,不抛异常)。backend 为 'credential-store' / 'encrypted-file' / 'plaintext';degraded 表示未使用 OS 凭据库 |
内部结构:
| 区间 | 内容 |
|---|---|
| configService.ts:9-19 | getConfig(主 + localStorage 兜底) |
| configService.ts:26-49 | setConfig / removeConfig |
| configService.ts:55-74 | getAllConfigs(含 localStorage 扫描兜底) |
| configService.ts:79-97 | SecretBackend / SecretStorageStatus 类型与 getSecretStorageStatus |
备注:
- 封装的 invoke 命令:
get_config、set_config、remove_config、get_all_configs、get_secret_storage_status(共 5 个)。 - 配置键:键名由调用方传入,本文件不硬编码业务键;localStorage 命名空间为
config_${key},getAllConfigs通过key.startsWith('config_')+substring(7)还原。 - 缓存策略:无缓存,每次调用都走 IPC;降级路径与主路径可能不一致(Tauri 失败时读 localStorage,而成功写入只进 Tauri)。
- 机密字段的存储与保护见
docs/secure_storage.md。
职责:网络代理配置的前端封装层——读写 proxy_config、从系统读取代理、测试代理连通性、自动嗅探本地代理端口,并把后端返回的裸 JSON 收敛成带类型的 ProxyConfig。所有函数都返回显式的 ProxyResult<T>({ok:true,value} / {ok:false,error}),不抛异常。
导出:类型 ProxyType、ProxyConfig、SystemProxyInfo、ProxyTestResult、ProxyResult<T>;常量 DEFAULT_PROXY_CONFIG、DEFAULT_PROXY_PORT;函数 normalizeProxyConfig、getProxySettings、saveProxySettings、clearProxySettings、readSystemProxy、testProxyConnection、autoDetectProxy。
主要依赖:@tauri-apps/api/core 的 invoke、@/utils/logger(logger.warn)。
| 符号 | 位置 | 说明 |
|---|---|---|
ProxyType(type) |
proxyService.ts:4 | "http" | "socks5" |
ProxyConfig(interface) |
proxyService.ts:7-21 | enabled/type/host/port/username?/password?/remoteDns?/exclude?;enabled=false 时其余字段仅作草稿保留 |
SystemProxyInfo(interface) |
proxyService.ts:24-35 | enabled/proxy_type/host/port/username/password/pac_url/from_env |
ProxyTestResult(interface) |
proxyService.ts:38-41 | status(HTTP 状态码)、duration_ms |
DEFAULT_PROXY_CONFIG |
proxyService.ts:43-48 | {enabled:false, type:"http", host:"", port:8080} |
DEFAULT_PROXY_PORT |
proxyService.ts:50-53 | {http: 8080, socks5: 1080},切换协议时用作默认端口 |
ProxyResult<T>(type) |
proxyService.ts:56-58 | 显式成功/失败联合类型 |
fail<T>(error)(私有) |
proxyService.ts:60-65 | 统一转 {ok:false,error} 并 logger.warn |
normalizeProxyConfig(input) |
proxyService.ts:68-85 | 任意输入 → 合法 ProxyConfig:type 非法回落 http、host 去空格、端口夹取 1-65535(非法时按协议默认端口)、remoteDns 仅 SOCKS5 生效、exclude 去空格 |
getProxySettings() |
proxyService.ts:88-95 | invoke get_proxy_settings → normalizeProxyConfig |
saveProxySettings(config) |
proxyService.ts:98-109 | invoke save_proxy_settings(参数 { config }),返回保存后的配置(已归一) |
clearProxySettings() |
proxyService.ts:112-119 | invoke clear_proxy_settings,返回是否确实删除了配置(当前 UI 未使用,重置走保存默认值) |
readSystemProxy() |
proxyService.ts:122-140 | invoke read_system_proxy,并补齐 proxy_type/username/password/pac_url 的缺省值 |
testProxyConnection(config?, url?) |
proxyService.ts:143-156 | invoke test_proxy_connection(参数 {config: config ?? null, url: url ?? null});不传 config 时后端用已保存配置 |
autoDetectProxy() |
proxyService.ts:159-167 | invoke auto_detect_proxy(无参),返回嗅探到的可用配置(协议/主机/端口已填好) |
备注:
- 封装的 invoke 命令:
get_proxy_settings、save_proxy_settings、clear_proxy_settings、read_system_proxy、test_proxy_connection、auto_detect_proxy(共 6 个,全部为代理专用命令)。 - 配置键:
proxy_config(由后端ConfigService持久化;保存后后端会同步刷新全局代理缓存并把exclude写入no_proxy,所有 HTTP 请求即时生效)。 exclude字段为逗号分隔的主机名列表,经后端写入no_proxy环境变量后生效(reqwest 读取该变量)。- 本文件不使用
configService——代理配置有自己的专用命令,避免和通用键值路径混用。
职责:仪表盘卡片实例配置的统一读写服务(静态类),配置最终落在后端 app_config.json 的 card_settings 对象下,按 cardId 隔离。
导出:类 CardConfigService(静态方法 getCardSettings、saveCardSettings、updateCardSetting、removeCardSettings)。
主要依赖:@tauri-apps/api/core 的 invoke、@/utils/logger 的 logDebug/logError、@/types/card-settings 的 BaseCardSettings 类型。
| 符号 | 位置 | 说明 |
|---|---|---|
CardConfigService.getCardSettings<T> |
cardConfigService.ts:16 | invoke get_card_settings,参数 {cardId},返回 T(后端返回 null/undefined 时转为 {});失败 logError 并返回 {} as T(不抛) |
CardConfigService.saveCardSettings |
cardConfigService.ts:33 | invoke save_card_settings,参数 {cardId, settings}(Partial<BaseCardSettings>,与现有配置合并),返回 void;成功 logDebug,失败 logError 后重新 throw |
CardConfigService.updateCardSetting |
cardConfigService.ts:55 | 无独立命令:先 getCardSettings 读全量 → 展开合并 {[key]: value} → 调 saveCardSettings 落盘;返回 void;失败 logError 后重新 throw(读-改-写非原子) |
CardConfigService.removeCardSettings |
cardConfigService.ts:82 | invoke remove_card_settings,参数 {cardId},返回 void;成功 logDebug,失败 logError 后重新 throw |
内部结构:
| 区间 | 内容 |
|---|---|
| cardConfigService.ts:16-26 | getCardSettings(读) |
| cardConfigService.ts:33-76 | saveCardSettings / updateCardSetting(写与单字段更新) |
| cardConfigService.ts:82-90 | removeCardSettings(删) |
备注:
- 封装的 invoke 命令:
get_card_settings、save_card_settings、remove_card_settings(共 3 个)。 - 配置键:不直接使用
configService的键;数据位于后端app_config.json的card_settings对象,按cardId分片(见文件头注释 cardConfigService.ts:5-9)。 - 缓存策略:无前端缓存,每次读都发 IPC;
updateCardSetting依赖getCardSettings结果做合并,存在并发覆盖风险。
职责:单个标签页内卡片集合的增删改与布局计算(新增卡片自动寻位、拖拽换序、尺寸调整),数据实际持久化在标签页对象的 cards 字段中(经 tabService 存储)。
导出:getDashboardConfig、addCard、removeCard、moveCard、updateCardLayout。
主要依赖:@/types/dashboard 的 CardConfig/CardTypeId/DashboardConfig/DashboardTab、uuid 的 v4、@/components/cards/registry/loader 的 loadAllCards、./cardConfigService 的 CardConfigService、./tabService 的 getAllTabs/saveTabs。
| 符号 | 位置 | 说明 |
|---|---|---|
getDashboardConfig |
dashboardConfig.ts:21 | 不直接 invoke:内部 getTabById → getAllTabs(→ getConfig('dashboard_tabs'));标签不存在时返回 {cards:[], lastUpdated:Date.now()},否则返回 {cards, lastUpdated: tab.updatedAt} |
addCard |
dashboardConfig.ts:85 | 读取标签配置 → loadAllCards() 取卡片 meta 默认尺寸(options.w/h 优先,再 meta.defaultSize,最后 3×2)→ findBestPosition 找无碰撞坐标 → 生成 uuid 卡片对象 push → saveTabCards(→ setConfig('dashboard_tabs'));若传 options.settings 再调 CardConfigService.saveCardSettings;返回新 cardId。不捕获错误 |
removeCard |
dashboardConfig.ts:122 | 按 cardId 过滤卡片数组并重排 position(0..n-1),经 saveTabCards 持久化;返回 void。卡片不存在时也照常保存;不捕获错误 |
moveCard |
dashboardConfig.ts:131 | 将卡片从原索引 splice 出再插入 newPosition,重排所有 position 后保存;cardId 未找到时直接 return(不保存);不捕获错误 |
updateCardLayout |
dashboardConfig.ts:149 | 更新单卡片 x/y/w/h 后保存;卡片不存在时直接 return;不捕获错误 |
内部结构:
| 区间 | 内容 |
|---|---|
| dashboardConfig.ts:7-19 | 私有辅助 getTabById、saveTabCards(读/写标签页并刷新 updatedAt) |
| dashboardConfig.ts:21-30 | getDashboardConfig |
| dashboardConfig.ts:32-83 | 私有 findBestPosition:在 maxX+cardW+2 × maxY+cardH+2 范围内扫描无碰撞位置,取 x+y 最小者,命中 0 立即返回 |
| dashboardConfig.ts:85-164 | addCard / removeCard / moveCard / updateCardLayout |
备注:
- 封装的 invoke 命令:本文件不直接 invoke;实际 IPC 经由
tabService→configService的get_config/set_config(键dashboard_tabs),以及CardConfigService的save_card_settings。 - 配置键:
dashboard_tabs(间接读写)。文件中不存在dashboard_config_*形式的键。 - 缓存策略:无缓存,每次操作都全量读标签数组再整体写回(整对象覆盖式保存)。
职责:主题系统的单一数据源——预设色板、浅/深色模式与主题色(含用户自定义色)的应用函数。主窗口 main.tsx、设置页 appearance-settings.tsx、侧栏 theme-switch.tsx 与托盘面板入口 tray-panel.tsx 共用本模块,避免各入口重复实现(此前托盘窗口因此拿不到自定义主题色)。
导出:常量 DEFAULT_THEME_COLOR、PRESET_COLORS;类型 ThemeMode、ThemeColor、AppliedTheme;函数 isSystemDark、getAllColors、findColorByName、resolveThemeColor、pickForegroundOn、applyPrimaryTextColor、applyThemeColor、applyThemeMode、loadTheme。
主要依赖:@/utils/configService 的 getConfig。
⚠️ Liquid Glass 重构移除:DEFAULT_GLASS_CLARITY与applyGlassClarity()(旧「毛玻璃清晰度」0–100 →--glass-blur等运行时变量)已删除,loadTheme()不再读写glass_clarity配置键。新体系的模糊半径是globals.css的静态--lg-*令牌。
| 符号 | 位置 | 说明 |
|---|---|---|
ThemeMode(type) |
theme.ts:11 | "light" | "dark" | "system" |
ThemeColor(interface) |
theme.ts:13 | name、label 与 colors(50–900 + foreground),供预设与自定义色共用 |
DEFAULT_THEME_COLOR |
theme.ts:31 | "indigo",预设首项 |
PRESET_COLORS |
theme.ts:35 | 6 套预设色板:indigo / blue / emerald / rose / amber / slate |
isSystemDark() |
theme.ts:141 | prefers-color-scheme: dark |
getAllColors(customColors?) |
theme.ts:146 | 预设 + 自定义色板 |
findColorByName(name, customColors?) |
theme.ts:151 | 按名称查找,未命中返回 undefined |
resolveThemeColor(name, customColors?) |
theme.ts:162 | 自定义 → 预设 → 首项的兜底链,保证永远有可用色板(自定义色被删除后配置可能残留旧名称) |
applyThemeColor(colors) |
theme.ts:277 | 把 --primary-50…--primary-900、--primary 写入 <html> 内联样式;--primary-foreground 不再照抄配色表,改由 pickForegroundOn(#色调) 按亮度自动选黑/白;末尾调用 applyPrimaryTextColor 同步算出 --primary-text |
applyThemeMode(mode) |
theme.ts:305 | 给 <html> 切换 dark 类(globals.css 的 @custom-variant dark 依赖它),并在切完后重算 --primary-text(达标方向取决于底色深浅) |
pickForegroundOn(hex, fallback?) |
theme.ts:252 | 按 WCAG 相对亮度选黑/白。规则是白字优先:白字对比度 ≥3:1 就返回 #ffffff;否则仅当黑字比白字高 1.4 倍以上才反黑。不再用「黑白取更高者」——它在亮度交叉点会横跳(indigo #6366f1 白 4.47 / 黑 4.70 判黑,slate #64748b 判白),同一颗主按钮只因主题色微调就黑白翻转,深色界面上近黑字压在紫底上读不出。现在仅 emerald/amber/#00FFBC 这类亮底色才反黑 |
applyPrimaryTextColor(primary) |
theme.ts:267 | 计算并写入 --primary-text:浅色主题混黑、深色主题混白,逐步逼近直到与底色对比度 ≥4.5:1,只调明度不换色相。--primary-text 供 text-primary-text(文字)使用,--primary 仍供背景/边框 |
loadTheme() |
theme.ts:322 | 并行读 theme_mode/theme_color/theme_custom_colors,依次应用并返回 { mode, colorName };托盘面板入口靠它一次到位 |
备注:
- 封装的 invoke 命令:本文件不直接 invoke;配置读取经
configService.getConfig→get_config。本文件只读不写,写入仍由appearance-settings.tsx/theme-switch.tsx调setConfig完成。 - 配置键(只读):
theme_mode、theme_color、theme_custom_colors。 - 与
appearance-settings.tsx的关系:该文件的PRESET_COLORS、applyThemeColor、DEFAULT_THEME_COLOR、getAllColors、findColorByName、pickForegroundOn均从本模块导入;只有取色器专用的hexToHsl/hslToHex/hexToRgb/rgbToHex/hexToHsv/hsvToHex/generateColorScale仍留在设置页(generateColorScale的foreground字段改调pickForegroundOn(hex),自定义高亮色不会再配白字)。 - 顺序约束:切换主题(
appearance-settings.tsx的handleModeChange、theme-switch.tsx的toggleTheme)必须先applyThemeMode再dispatchEvent("themeChange")。反过来广播的话,订阅者(各 ECharts 组件)会在旧.dark状态下取--muted/--separator颜色,之后没有任何事件再让它们重算,深色主题下坐标轴文字会停在浅色值上。
职责:读取全局背景图设置(路径、透明度、模糊度),把背景图片字节读成 Blob URL 并同步写入 CSS 变量 --bg-image / --bg-image-opacity / --bg-blur。
导出:常量 DEFAULT_BG_IMAGE_OPACITY、DEFAULT_BG_BLUR;接口 BackgroundSettings;函数 loadBackgroundSettings。
主要依赖:@tauri-apps/api/core 的 invoke、@/utils/configService 的 getConfig。
| 符号 | 位置 | 说明 |
|---|---|---|
DEFAULT_BG_IMAGE_OPACITY |
backgroundSettings.ts:4 | 常量 0.5,背景图默认不透明度 |
DEFAULT_BG_BLUR |
backgroundSettings.ts:5 | 常量 16,默认模糊像素 |
loadBackgroundSettings |
backgroundSettings.ts:14 | 并行 getConfig 读 bg_image_path/bg_image_opacity/bg_blur(缺省用上述默认值),写入 CSS 变量并把 --bg-image 先置为 none;若 imagePath 存在则 invoke read_image_file(参数 {path},返回 number[])转 Blob(type:image/webp) → URL.createObjectURL → 设为 --bg-image;读图失败静默吞掉(保持空背景),最终返回 BackgroundSettings;本函数自身不捕获 getConfig 抛出的错误 |
内部结构:
| 区间 | 内容 |
|---|---|
| backgroundSettings.ts:4-12 | 默认常量与 BackgroundSettings 接口 |
| backgroundSettings.ts:14-42 | loadBackgroundSettings(配置读取 → CSS 变量 → 图片字节转 Blob URL) |
备注:
- 封装的 invoke 命令:
read_image_file(参数{path});间接经getConfig使用get_config。 - 配置键:
bg_image_path、bg_image_opacity、bg_blur(均通过configService.getConfig读取,本文件不写入)。 - 缓存策略:无缓存;每次调用都会新建 Blob URL,旧的
URL.createObjectURL未见revokeObjectURL调用(潜在内存泄漏)。
职责:角色数据统一查询服务(单例 RoleDataService),通过单一 IPC 命令 query_role_data 按 JSON 叶节点路径取数,并提供角色详情、干员、Wiki 物品目录等语义化封装;内置按查询键的 Promise 级内存缓存,避免组件重挂载重复 IPC。
导出:类型 QueryResult、类 RoleDataService、单例 roleDataService。
主要依赖:@tauri-apps/api/core 的 invoke、./logger 的 logDebug/logInfo/logError、./startupProgress 的 trackStartupTask。
| 符号 | 位置 | 说明 |
|---|---|---|
queryData |
roleDataService.ts:65 | invoke query_role_data,参数 {roleId, apiName, paths};返回 QueryResult | null(路径不存在为 null 值,键为请求路径)。先查 queryCache(命中直接返回缓存的 Promise);启动 Splash 跟踪期间计入初始任务;失败时从缓存删除该键、logError、返回 null |
clearCache |
roleDataService.ts:30 | 删除 queryCache 中 roleId|apiName|paths.join(",") 单条记录;返回 void |
clearAllCache |
roleDataService.ts:37 | queryCache.clear() 清空全部缓存;返回 void |
getFullCharDetail |
roleDataService.ts:108 | 内部 queryData(roleId,'char_detail',[]),返回 result.__full__;无结果返回 null |
getBaseInfo |
roleDataService.ts:124 | queryData(..., ['base']),返回 result.base;否则 null |
getRoleName |
roleDataService.ts:140 | queryData(..., ['base.name']),返回该字符串;否则 null |
getCharacter |
roleDataService.ts:157 | queryData(..., ['chars.${charIndex}']),返回该干员对象;否则 null |
getAllCharIds |
roleDataService.ts:173 | queryData(..., ['chars']),映射 char.charData?.id 并过滤空值;失败返回 [] |
batchQuery |
roleDataService.ts:192 | queryData(roleId, 'char_detail', paths) 的快捷封装,返回 QueryResult | null |
getWikiItemDetail |
roleDataService.ts:205 | queryData(roleId,'char_wiki_detail',[itemId]),按 raw.data.item → raw.data(brief) → raw.item → raw 顺序解包返回;否则 null |
getItemCatalog |
roleDataService.ts:222 | queryData(roleId,'wiki_catalog',[]) 取 __full__,遍历 data.catalog[].typeSub[].items[] 构建 Map<itemId,{name,cover}>;无 __full__ 或 data.catalog 非数组返回 null;内部用 console.log 输出诊断与前 3 条 item 原始结构 |
getWikiItemDetails |
roleDataService.ts:274 | 批量版:queryData(roleId,'char_wiki_detail',itemIds),逐 id 按与 getWikiItemDetail 相同的优先级解包进 Record;itemIds 为空或无结果返回 {} |
内部结构:
| 区间 | 内容 |
|---|---|
| roleDataService.ts:15-21 | QueryResult 类型、模块级 queryCache(Map<string, Promise>)与 cacheKey 拼接函数 |
| roleDataService.ts:30-39 | 缓存管理 clearCache / clearAllCache |
| roleDataService.ts:64-100 | 核心 queryData(缓存命中 + IPC + 失败删缓存) |
| roleDataService.ts:108-194 | 角色详情/基础信息/干员相关便捷方法 |
| roleDataService.ts:196-291 | Wiki 相关方法(getWikiItemDetail、getItemCatalog、getWikiItemDetails) |
| roleDataService.ts:295 | 单例导出 |
备注:
- 封装的 invoke 命令:仅
query_role_data(apiName取值出现:char_detail、char_wiki_detail、wiki_catalog)。 - 配置键:不读写任何配置键。
- 缓存策略:模块级
Map<string, Promise<QueryResult|null>>,键为${roleId}|${apiName}|${paths.join(",")};缓存 Promise 本身(并发去重),失败时删除对应键以便重试;paths顺序不同会生成不同缓存键。注意:成功结果(含null结果值)会长期驻留,需手动clearCache/clearAllCache。 - 异常点:
getItemCatalog内使用裸console.log(roleDataService.ts:227、233、257、263),与文件其余部分用 logger 的风格不一致,且遗留调试日志。
职责:《明日方舟》get_arknights_player_info 的类型化封装(2026-11 新增,供公开招募/基地数据卡片与 /recruitment /building /game-data 页面共用)。做两件事:游戏分流(resolveRoleGame 判别,非明日方舟账户直接返回 null,调用方渲染空态)与旧缓存自动迁移(缓存文件是「解析后的结构体落盘」,dataVersion < ARKNIGHTS_DATA_VERSION(当前 =3)说明是更早版本写的旧格式缓存、缺章节进度或训练室 level 等字段 —— 自动 force: true 联网刷新一次,失败时仍返回旧缓存内容并只记日志)。
导出:ArknightsDataOptions、fetchArknightsPlayerInfo({ roleId, force? })。
主要依赖:@tauri-apps/api/core(invoke)、@/types/arknights(ArknightsPlayerInfo、ARKNIGHTS_DATA_VERSION)、./roleGame(resolveRoleGame)、./logger。
| 符号 | 位置 | 说明 |
|---|---|---|
fetchArknightsPlayerInfo |
arknightsDataService.ts:38 | invoke get_arknights_player_info → 检测 info.dataVersion ?? 0 < ARKNIGHTS_DATA_VERSION(=3)且未强制时再刷一次 force: true(后端 refresh_player_info 会把新格式落盘,之后不再触发);强制刷新失败返回旧缓存;非 arknights 角色返回 null |
备注:
- 封装的 invoke 命令:仅
get_arknights_player_info。 - 后端标记来源:
ArknightsService::fetch_player_info解析成功后填data_version(models::arknights::ARKNIGHTS_DATA_VERSION),绑定/刷新/refresh_accounts都会写新格式缓存。 - 类型与后端
src-tauri/src/models/arknights.rs一一对应,见src/types/arknights.ts。
职责:角色详情与相关后端开关的轻量服务(单例 RoleDetailService),统一通过 query_role_data 取完整角色详情,并管理后端懒加载开关与当前激活角色 ID。
导出:类 RoleDetailService、单例 roleDetailService。
主要依赖:@tauri-apps/api/core 的 invoke、./logger 的 logDebug/logInfo/logError。
| 符号 | 位置 | 说明 |
|---|---|---|
getCharDetail |
roleDetailService.ts:12 | invoke query_role_data,参数 {roleId, apiName:'char_detail', paths:[]},返回 result.__full__ ?? null;失败 logError 并返回 null |
setLazyLoadEnabled |
roleDetailService.ts:30 | invoke set_lazy_load_enabled,参数 {enabled},返回 void;失败 logError 后重新 throw |
isLazyLoadEnabled |
roleDetailService.ts:43 | invoke is_lazy_load_enabled,无参,返回 boolean;失败 logError 并默认返回 true |
setCurrentRoleId |
roleDetailService.ts:56 | invoke set_current_role_id,参数 {roleId}(可为 null),返回 void;失败仅 logError,不抛 |
内部结构:
| 区间 | 内容 |
|---|---|
| roleDetailService.ts:12-25 | getCharDetail |
| roleDetailService.ts:30-63 | 后端开关与激活角色:setLazyLoadEnabled / isLazyLoadEnabled / setCurrentRoleId |
| roleDetailService.ts:67 | 单例导出 |
备注:
- 封装的 invoke 命令:
query_role_data、set_lazy_load_enabled、is_lazy_load_enabled、set_current_role_id(共 4 个)。 - 配置键:不读写前端配置键;懒加载状态与当前角色 ID 由后端保存。
- 缓存策略:无缓存(与
roleDataService不同,每次getCharDetail都发 IPC);与RoleDataService.getFullCharDetail功能重叠,但绕过了其 Promise 缓存。
职责:仪表盘标签页(Tab)的 CRUD,数据整体存放在配置键 dashboard_tabs,当前激活标签存放在 dashboard_active_tab。
导出:getAllTabs、saveTabs、getActiveTabId、setActiveTabId、addTab、removeTab、updateTab。
主要依赖:./configService 的 getConfig/setConfig/removeConfig、@/types/dashboard 的 DashboardTab、uuid 的 v4。
| 符号 | 位置 | 说明 |
|---|---|---|
getAllTabs |
tabService.ts:8 | getConfig<DashboardTab[]>('dashboard_tabs')(→ invoke get_config),无数据返回 [];配置读取失败由 getConfig 降级 localStorage |
saveTabs |
tabService.ts:13 | setConfig('dashboard_tabs', tabs)(→ invoke set_config),返回 void;失败由 setConfig 降级写 localStorage |
getActiveTabId |
tabService.ts:17 | getConfig<string>('dashboard_active_tab'),无数据返回 null |
setActiveTabId |
tabService.ts:22 | 传入非空 id 时 setConfig('dashboard_active_tab', id);传 null 时 removeConfig('dashboard_active_tab')(→ invoke remove_config);返回 void |
addTab |
tabService.ts:30 | 读全量 tabs → 新建 {id:uuidv4(), name, icon, tags, cards:[], defaultRoleId, createdAt, updatedAt}(tags 默认 [])→ saveTabs → 返回新 DashboardTab |
removeTab |
tabService.ts:53 | 按 tabId 过滤后保存;若被删的是激活标签则 setActiveTabId(null) 清除激活态;返回 void |
updateTab |
tabService.ts:63 | 局部更新 name/icon/tags/defaultRoleId 并刷新 updatedAt;tabId 不存在时直接 return(不保存);返回 void |
内部结构:
| 区间 | 内容 |
|---|---|
| tabService.ts:5-6 | 模块常量 TABS_KEY = 'dashboard_tabs'、ACTIVE_TAB_KEY = 'dashboard_active_tab'(未导出) |
| tabService.ts:8-28 | 标签读写与激活标签读写 |
| tabService.ts:30-76 | addTab / removeTab / updateTab |
备注:
- 封装的 invoke 命令(经
configService):get_config、set_config、remove_config。 - 配置键:
dashboard_tabs(DashboardTab[],含每个标签的cards)、dashboard_active_tab(当前激活标签 id)。 - 缓存策略:无缓存,整数组全量读写;
saveTabs是标签相关数据(含卡片布局)的唯一落盘出口。
职责:仪表盘标签页快照——离开当前标签页视图时截取主窗口内容区左上角画面并落盘,主界面卡片用其作缩略图。截图经后端 save_tab_snapshot(PrintWindow GDI),文件存 <app_data>/snapshots/<tabId>-<时间戳>.png,路径映射写配置键 dashboard_tab_snapshots。
导出:registerDashboardLeaveHandler、runDashboardLeaveHandler、captureTabSnapshot、getSnapshotPaths、deleteTabSnapshotFile。
主要依赖:@tauri-apps/api/core(invoke)、./configService、./platform(isWindowsPlatform)、./logger。
| 符号 | 位置 | 说明 |
|---|---|---|
SNAPSHOT_CONFIG_KEY |
tabSnapshotService.ts:7 | 配置键 "dashboard_tab_snapshots"({ [tabId]: PNG 路径 }) |
SNAPSHOT_CSS_WIDTH / SNAPSHOT_CSS_HEIGHT |
:10 / :11 | 截取区域 CSS 尺寸上限 640×420(乘以 devicePixelRatio 得物理像素,与后端 8192 上限一致) |
inflight |
:14 | Map<tabId, Promise>:同标签页截图进行中去重 |
registerDashboardLeaveHandler |
:22 | DashboardPage 挂载时注册 / 卸载时置 null 的「离开仪表盘」钩子 |
runDashboardLeaveHandler |
:28 | 侧栏导航守卫点击前 await 该函数,钩子不在时为空操作 |
captureTabSnapshot |
:46 | 核心:非 Windows / 无 tabId 直接 resolve;截图前把内容区滚回顶部(closest("main").scrollTop=0 + 等两帧 rAF);以 #dashboard-main 的视口矩形 × dpr 计算 (x,y,width,height)(宽/高钳到 640×420);invoke("save_tab_snapshot", { tabId, x, y, width, height }) 取回路径写入映射并 setConfig;失败仅 logError(静默降级,不阻塞导航) |
getSnapshotPaths |
:104 | 读映射(模块级 snapshotMap 缓存,首次从 config 加载) |
deleteTabSnapshotFile |
:109 | invoke("delete_tab_snapshot") + 从映射中移除该 tabId |
备注:
- invoke 命令:
save_tab_snapshot(tabSnapshotService.ts:78,参数{ tabId, x, y, width, height })、delete_tab_snapshot(:111,参数{ tabId });配置读写经get_config/set_config。 - 时序契约:所有调用点都保证「窗口画面仍是该标签页」时截图——DashboardPage 的
loadDashboard开头、handleBackToSelector、dashboardOpenSelector事件,以及侧栏handleNavClick/父节点点击(preventDefault后 await 再navigate,否则 Link 默认导航先于截图完成)。 - 文件命名带时间戳 + 写新删旧:
imageCacheManager/浏览器均按路径缓存图片,路径变化保证读到最新画面。 - 非 Windows 平台后端返回不支持,
captureTabSnapshot内部先行isWindowsPlatform()短路,主界面显示占位。
职责:标签页图标键到 React 图标组件的映射表,以及中英文图标名称表,提供按 key 取组件/取文案的工具函数。
导出:TAB_ICON_MAP、ICON_LABELS、getTabIcon、getIconLabel。
主要依赖:react、@/components/icons(HomeIcon、ChartIcon、UsersIcon、StarIcon、HeartIcon、BookmarkIcon、TagIcon、FolderIcon、CalendarIcon、BellIcon、SettingsIcon、AccountIcon、SearchIcon、DeveloperIcon、ProjectsIcon)。
| 符号 | 位置 | 说明 |
|---|---|---|
TAB_ICON_MAP |
tabIcons.tsx:20 | Record<string, ComponentType>,15 个图标键:home、chart、users、star、heart、bookmark、tag、folder、calendar、bell、settings、account、search、developer、projects |
ICON_LABELS |
tabIcons.tsx:38 | 与 TAB_ICON_MAP 同 key 的 {zh, en} 双语名称表 |
getTabIcon |
tabIcons.tsx:56 | 按 iconKey 取组件,未命中回退 HomeIcon;无 IPC、无异常路径 |
getIconLabel |
tabIcons.tsx:60 | 按 iconKey + lang('zh' | 'en')取文案,未命中回退显示 iconKey 本身;无异常路径 |
内部结构:
| 区间 | 内容 |
|---|---|
| tabIcons.tsx:1-18 | import 图标组件 |
| tabIcons.tsx:20-54 | 两个静态映射表 |
| tabIcons.tsx:56-62 | 两个取值辅助函数 |
备注:
- 封装的 invoke 命令:无。
- 配置键:无(图标 key 由
DashboardTab.icon字段携带,最终存于dashboard_tabs)。 - 缓存策略:静态模块常量,无缓存逻辑。注意
getIconLabel的lang参数未做合法性校验,非zh/en会走回退分支。
职责:全局应用内消息(通知中心)的内存状态仓库,提供订阅式增删改查、未读统计、按 tag 去重与 sessionStorage 持久化,通过 messagesChanged 自定义事件 + listener 双通道通知 UI。
导出:类型 MessageType、AppMessageAction、AppMessage;函数 getMessages、getUnreadCount、hasUrgentUnread、addMessage、updateMessage、markRead、markAllRead、clearMessages、removeMessage、removeMessagesByTag、subscribeMessages。
主要依赖:无外部依赖(仅浏览器 sessionStorage、crypto.randomUUID、window.dispatchEvent)。
| 符号 | 位置 | 说明 |
|---|---|---|
getMessages |
messageStore.ts:59 | 返回内存消息数组;为空时先 load() 从 sessionStorage['app_messages'] 惰性加载;无异常路径 |
getUnreadCount |
messageStore.ts:64 | 统计 read === false 的条数 |
hasUrgentUnread |
messageStore.ts:68 | 是否存在未读且 type === 'urgent' 的消息 |
addMessage |
messageStore.ts:72 | 补齐 id=crypto.randomUUID()、timestamp=Date.now()、read 默认 false、dismissable 默认 true;若有 tag 先移除同 tag 旧消息(去重),插入队首并截断到 MAX_MESSAGES=80,随后 persist() + emit(),返回新条目 |
updateMessage |
messageStore.ts:92 | 按 id 局部更新 title/body/type/actions/progress,持久化并通知;id 不存在则无变化 |
markRead |
messageStore.ts:101 | 按 id 置 read=true,持久化并通知 |
markAllRead |
messageStore.ts:107 | 全部置 read=true,持久化并通知 |
clearMessages |
messageStore.ts:113 | 清空全部消息,持久化并通知 |
removeMessage |
messageStore.ts:119 | 按 id 删除,持久化并通知 |
removeMessagesByTag |
messageStore.ts:125 | 按 tag 删除同标签消息,持久化并通知 |
subscribeMessages |
messageStore.ts:131 | 注册回调到 listeners,返回取消订阅函数(从数组移除该 fn);emit() 时逐个调用并额外派发 window 事件 messagesChanged |
内部结构:
| 区间 | 内容 |
|---|---|
| messageStore.ts:1-21 | 类型定义(MessageType 仅 info/warn/urgent) |
| messageStore.ts:23-27 | 模块常量 STORAGE_KEY='app_messages'、MAX_MESSAGES=80 与内存状态 messages/listeners |
| messageStore.ts:29-57 | 私有 emit()、persist()(截断到 80 条写 sessionStorage)、load()(含旧类型迁移:发现 success/error/warning 即丢弃整份数据并移除键) |
| messageStore.ts:59-136 | 全部导出查询/变更/订阅函数 |
备注:
- 封装的 invoke 命令:无(纯前端状态库)。
- 配置键/存储键:
sessionStorage键app_messages(非configService命名空间)。 - 缓存策略:单例内存数组
messages,读时惰性加载;每次变更同步写 sessionStorage。 - 异常点:
load()对含 legacy 类型的消息采取「整表作废」而非仅迁移;persist()的JSON.stringify异常被空catch吞掉。
职责:游戏启动器(安装/更新/校验修复/预下载/渠道切换/启动/进程控制/公告背景资源)的全部 Tauri IPC 封装 + 三个进度事件监听 + 渠道/阶段标签与字节格式化工具。
导出:类型 GameChannel、GameId、GameStatus、ActiveOperation、RemotePackage、DownloadProgress、BackgroundMedia、LauncherResult、PayloadState、BannerItem、AnnouncementItem、LauncherNoticeContent、SidebarItem、FileScanResult、DiskSpace、GamePlaytime、LaunchExportOptions、SteamShortcutOptions、SteamShortcutDefaults、AddSteamShortcutResult、LauncherGame;函数 checkGameStatus、installOrUpdate、verifyAndRepair、getProcessReadBytes、getRemoteVersion、getPayloadState、cancelDownload、preloadDownload、installPreload、resetDownloadCancel、hasDownloadCache、getBanners、getAnnouncements、getNoticeContent、getBackgroundImage、startGame、syncSilentLaunchConfig、restoreLaunchConfig、getGameLaunchCommand、createGameShortcut、getSteamShortcutDefaults、pickSteamIcon、pickSteamIconSource、extractSteamIcon、addSteamShortcut、browseFolder、checkExecutable、checkGameRunning、killGame、getGamePlaytime、detectChannel、scanInstallDir、getDiskSpace、switchChannel、cancelSwitch、cancelAll、onLauncherProgress、onProgress、onSwitchProgress、formatBytes、switchableChannels、gameConfigKey、gameOfChannel、readGameInstallPath、readGameChannel、persistDetectedInstall、persistInstallPath;常量 CHANNEL_LABELS、CHANNEL_SHORT、CHANNEL_GAME、GAME_CHANNELS、GAME_ORDER、ALL_CHANNELS、DEFAULT_CHANNEL、STAGE_LABELS、LAUNCH_TOKEN_KEYS、LAUNCH_WARNING_TITLE_KEYS、KILL_TOKEN_KEYS;函数 splitLaunchToken(解析 <token>: <detail> 契约串)。
主要依赖:@tauri-apps/api/core 的 invoke、@tauri-apps/api/event 的 listen / 类型 UnlistenFn。
类型备注:RemotePackage(launcherService.ts:38)除 version / resource_base_url 外还带补丁与预下载信息:has_patch、patch_total_bytes、has_patch_whole、patch_is_delta、preload_total_bytes(后端 RemotePackage 另含 preload_parts / patch_parts,前端未用)。解密密钥 cd_key 只存在后端,不下发前端。
按游戏分区(配置键):安装路径 / 渠道 / DX11 每个游戏各存一份——终末地沿用 launcher_install_path / launcher_channel / launcher_dx11,明日方舟用同名 _arknights 后缀键。gameConfigKey(base, game) 统一拼键名,readGameInstallPath / readGameChannel 负责带头默认值地读取;startGame / syncSilentLaunchConfig / restoreLaunchConfig 都按游戏逐个读写,后端 commands/startup.rs::LauncherGame 用同一套规则。当前选中的游戏保存在 stores/launcherGame.ts(键 launcher_game,带订阅)。
目录与渠道必须同属一个游戏:分区里存的是「安装路径 + 渠道」一对,两者必须指向同一个游戏,否则后端 check_status 会拿错渠道去拼 exe 名(Endfield.exe / Arknights.exe),is_installed 恒为 false,界面一直要求下载游戏。三条约束把住这个不变量:
persistDetectedInstall(installPath, detected)— 识别出渠道后统一落盘。按渠道的归属游戏写launcher_install_path[_arknights]与launcher_channel[_arknights],并清掉另一个分区里指向同一目录的旧路径与那个「不属于自己」的渠道(识别错游戏时写歪的残留)。localStorage 与后端 config(app_config.json)同时写——后端那一份是静默启动 / 快捷方式的真正依据,只改 localStorage 会被下次启动的restoreLaunchConfig搬回旧值。返回该渠道所属的游戏,供调用方同步launcherGame。persistInstallPath(installPath, game)— 只记目录、不动渠道,用于「目录已选好但还没识别出渠道」(游戏还没装)的情况;同样两边都写。syncSilentLaunchConfig/restoreLaunchConfig— 同步与回灌时都校验「渠道属于该游戏」,不匹配就跳过,避免把外来渠道带进分区。
渠道分组:GameChannel 同时承载两个游戏——official / bilibili / global / google_play 属《明日方舟:终末地》,arknights / arknights_bilibili 属《明日方舟》。GAME_CHANNELS(按游戏分组)、GAME_ORDER(展示顺序)、CHANNEL_GAME(渠道 → 游戏)、CHANNEL_SHORT(圆形徽标文字)供界面分组渲染;switchableChannels(from) 返回同游戏内除当前渠道外的全部候选(两个游戏都支持换服:实测 2026-11-08,渠道差异都完整落在各自清单里,明日方舟官↔B 约 706 MB diff)。
| 符号 | 位置 | 说明 |
|---|---|---|
checkGameStatus |
launcherService.ts:109 | invoke launcher_check_status,参数 {channel, installPath},返回 GameStatus;无本地错误处理(错误上抛) |
installOrUpdate |
launcherService.ts:155 | invoke launcher_install_or_update,参数 {channel, installPath, maxConcurrent ?? null, resume ?? true},返回 LauncherResult;无本地错误处理 |
verifyAndRepair |
launcherService.ts:169 | invoke launcher_verify_and_repair,参数 {channel, installPath, maxConcurrent ?? null, quick ?? false, resume ?? true};若 result.success === false 则 throw result.message(抛字符串),否则返回 LauncherResult |
getProcessReadBytes |
launcherService.ts:144 | invoke launcher_get_process_read_bytes,无参,返回 number(进程已读字节) |
getRemoteVersion |
launcherService.ts:148 | invoke launcher_get_remote_version,参数 {channel},返回 RemotePackage |
getPayloadState |
launcherService.ts:154 | invoke launcher_get_payload_state,参数 {channel},返回 PayloadState | null |
cancelDownload |
launcherService.ts:160 | invoke launcher_cancel_download,参数 {installPath ?? null},返回 void |
preloadDownload |
launcherService.ts:209 | invoke launcher_preload_download,参数 {channel, installPath, maxConcurrent ?? null, resume ?? true},返回 LauncherResult |
installPreload |
launcherService.ts:223 | invoke launcher_install_preload,参数 {channel, installPath, maxConcurrent ?? null, resume ?? true},返回 LauncherResult |
resetDownloadCancel |
launcherService.ts:176 | invoke launcher_reset_download_cancel,无参,返回 void |
hasDownloadCache |
launcherService.ts:180 | invoke launcher_has_download_cache,参数 {installPath},返回 boolean |
getBanners |
launcherService.ts:184 | invoke launcher_get_banners,参数 {channel},返回 BannerItem[] |
getAnnouncements |
launcherService.ts:190 | invoke launcher_get_announcements,参数 {channel},返回 AnnouncementItem[] |
getNoticeContent |
launcherService.ts:196 | invoke launcher_get_notice_content,参数 {channel},返回 LauncherNoticeContent(横幅 + 公告 + 右侧栏 sidebars 合并结构) |
getBackgroundImage |
launcherService.ts:204 | invoke launcher_get_background_image,参数 {channel},返回 BackgroundMedia | null |
startGame |
launcherService.ts:280 | invoke launcher_start_game,参数 {installPath, channel, dx11?},返回 LauncherResult;dx11 为 true 时后端给游戏进程追加 -force-d3d11,省略时后端读取配置 launcher_dx11;失败时 message 为 <token>: <detail>(token 见 LAUNCH_TOKEN_KEYS),回退直接启动或 Steam 未提权时的提示在 warning 字段(标题见 LAUNCH_WARNING_TITLE_KEYS) |
syncSilentLaunchConfig |
launcherService.ts:297 | 从 localStorage 将 launcher_install_path、launcher_channel、launcher_dx11 通过 set_config 写入 app config |
restoreLaunchConfig |
launcherService.ts:318 | 反向同步:invoke get_config 读取 app config 中非空的 launcher_install_path、launcher_channel 与布尔 launcher_dx11 回写 localStorage;后端不可用时静默保留 localStorage 现状。修复静默命令行启动后打开完整版时游戏面板因 localStorage 缺失而显示「定位游戏」的问题 |
getGameLaunchCommand |
launcherService.ts:343 | invoke get_game_launch_command,返回包含 exe 路径与 --silent --launch-game 的完整命令(--dx11 由前端按开关追加展示) |
createGameShortcut |
launcherService.ts:351 | invoke create_game_shortcut,参数 LaunchExportOptions {dx11?}(缺省读后端配置 launcher_dx11);弹出用户选定保存位置的对话框,返回 .lnk 路径或 null(取消)。不再接受 closeAfterLaunch |
getSteamShortcutDefaults |
launcherService.ts:387 | invoke steam_shortcut_defaults,无参,返回 SteamShortcutDefaults(名字、默认 .ico、是否提取成功、游戏是否存在、DX11、两项 Overlay 选项、开始菜单快捷方式数量、当前是否已提权) |
pickSteamIcon |
launcherService.ts:391 | invoke pick_steam_icon,无参,返回图标路径或 null(取消) |
pickSteamIconSource |
launcherService.ts:395 | invoke pick_steam_icon_source,无参,返回用于提取图标的 exe 路径或 null |
extractSteamIcon |
launcherService.ts:399 | invoke extract_steam_icon,参数 {exePath},返回生成的 .ico 路径 |
addSteamShortcut |
launcherService.ts:403 | invoke add_steam_shortcut,参数 {options: SteamShortcutOptions}(name/icon_path/dx11/create_admin_shortcut/elevate_start_menu,调用处把 camelCase 转成后端字段名);返回 AddSteamShortcutResult {shortcuts_path, admin_shortcut, elevated_start_menu}。允许 Steam 运行中写入,成功后需重启 Steam 才可见 |
browseFolder |
launcherService.ts:363 | invoke launcher_browse_folder,无参,返回 string | null(用户选择的目录) |
checkExecutable |
launcherService.ts:226 | invoke launcher_check_executable,参数 {installPath, channel},返回 boolean |
checkGameRunning |
launcherService.ts:236 | invoke launcher_check_game_running,参数 {channel},返回 boolean |
killGame |
launcherService.ts:456 | invoke launcher_kill_game,参数 {channel},返回 boolean(true = 已结束,false = 本来就没有进程)。失败时 reject,错误串为 <token>: <detail>(token 为 cancelled / kill_failed / unknown,文案见 KILL_TOKEN_KEYS(:81));后端在未提权时会经 UAC 以管理员权限终止进程(process::terminate_processes),因此这里可能弹出提权确认;就地终止判定为 AccessDenied 时才弹,响应几乎即时 |
getGamePlaytime |
launcherService.ts:365 | invoke launcher_get_game_playtime,无参,返回 GamePlaytime {total_seconds, session_seconds, running}(累计总时长 + 当前会话 + 运行态) |
detectChannel |
launcherService.ts:252 | invoke launcher_detect_channel,参数 {installPath},返回 GameChannel | null |
scanInstallDir |
launcherService.ts:258 | invoke launcher_scan_install_dir,参数 {channel, installPath},返回 FileScanResult(损坏/缺失文件清单与字节统计) |
getDiskSpace |
launcherService.ts:268 | invoke launcher_get_disk_space,参数 {path},返回 DiskSpace {total, free} |
switchChannel |
launcherService.ts:272 | invoke launcher_switch_channel,参数 {fromChannel, toChannel, installPath},返回 string(结果消息) |
cancelSwitch |
launcherService.ts:284 | invoke launcher_cancel_switch,无参,返回 void |
cancelAll |
launcherService.ts:288 | invoke launcher_cancel_all,无参,返回 void |
onLauncherProgress |
launcherService.ts:294 | listen<DownloadProgress>('launcher-progress', ...),参数为回调,返回 Promise<UnlistenFn>;事件名为 launcher-progress(无 ://) |
onProgress |
launcherService.ts:302 | listen<ActiveOperation>('launcher://progress', ...),返回 Promise<UnlistenFn> |
onSwitchProgress |
launcherService.ts:310 | listen<DownloadProgress>('launcher://switch-progress', ...),返回 Promise<UnlistenFn> |
formatBytes |
launcherService.ts:486 | 纯函数:1024 进制格式化为 B/KB/MB/GB/TB(保留 2 位小数),0 返回 "0 B" |
LAUNCH_TOKEN_KEYS |
launcherService.ts:60 | 启动结果 <token> → i18n 文案键的映射;新增 overlay_unavailable → launcher.launch_overlay_unavailable |
LAUNCH_WARNING_TITLE_KEYS |
launcherService.ts:72 | warning 的标题映射:fallback → launcher.launch_fallback_title、overlay_unavailable → launcher.launch_overlay_title;缺省沿用 fallback 标题 |
splitLaunchToken |
launcherService.ts:77 | 按第一个 : 拆成 {token, detail};无冒号时 token=""、detail=原文 |
persistDetectedInstall |
launcherService.ts:733 | 识别出渠道后统一落盘(async):按渠道的归属游戏写 launcher_install_path[_arknights] 与 launcher_channel[_arknights](localStorage + 后端 set_config 双写),并清掉另一个分区里指向同一目录的旧路径与那个「不属于自己」的渠道。返回该渠道所属的 LauncherGame,供调用方同步 launcherGame store。目录与渠道必须同属一个游戏,否则 check_status 会拿错 exe 名判安装、is_installed 恒为 false |
persistInstallPath |
launcherService.ts:781 | 只记安装目录、不动渠道(async,localStorage + 后端 set_config 双写):用于「目录已选好但还没识别出渠道」(游戏还没装)的情况,路径留在当前游戏的分区里,渠道留给用户选 |
内部结构:
| 区间 | 内容 |
|---|---|
| launcherService.ts:8-105 | 全部类型定义(渠道、状态、进度、包信息、公告、扫描结果、磁盘空间) |
| launcherService.ts:109-290 | IPC 封装函数(27 个命令包装) |
| launcherService.ts:294-316 | 三个事件监听器 |
| launcherService.ts:320-351 | 常量 CHANNEL_LABELS(4 渠道中英标签)、ALL_CHANNELS、formatBytes、STAGE_LABELS(8 个阶段中英标签) |
备注:
- 封装的 invoke 命令:
launcher_check_status、launcher_install_or_update、launcher_verify_and_repair、launcher_get_process_read_bytes、launcher_get_remote_version、launcher_get_payload_state、launcher_cancel_download、launcher_preload_download、launcher_install_preload、launcher_reset_download_cancel、launcher_has_download_cache、launcher_get_banners、launcher_get_announcements、launcher_get_notice_content、launcher_get_background_image、launcher_start_game、launcher_browse_folder、launcher_check_executable、launcher_check_game_running、launcher_kill_game、launcher_get_game_playtime、launcher_detect_channel、launcher_scan_install_dir、launcher_get_disk_space、launcher_switch_channel、launcher_cancel_switch、launcher_cancel_all(共 27 个)。 - 监听的 Tauri 事件:
launcher-progress、launcher://progress、launcher://switch-progress(注意前两者命名风格不一致,属两套事件源)。 - 配置键:本文件不读写任何
configService配置键(安装路径、渠道等由调用方传入)。 - 缓存策略:无前端缓存;远程版本/资源的缓存由后端负责。除
verifyAndRepair外所有函数都不捕获错误,异常直接上抛给调用方;verifyAndRepair在业务失败时抛出的是字符串result.message而非Error对象。
职责:系统资源采集命令的封装,以及全局「系统资源卡片」默认值的读写。
导出:SystemResourceService(静态类)、SnapshotResult(interface)、getSystemResourceDefaults()、setSystemResourceDefaults(patch),并再导出类型 SystemSnapshot。
主要依赖:@tauri-apps/api/core 的 invoke、@/utils/logger、@/utils/configService(getConfig/setConfig)、@/types/system-resource。
| 符号 | 说明 |
|---|---|
SystemResourceService.getSnapshot() |
invoke("get_system_snapshot"),返回 {ok:true,data};异常转 {ok:false,error}(记录 logWarn),调用方据此渲染友好提示 |
SystemResourceService.safeSnapshot() |
仅返回数据或 null,供历史曲线等非关键路径使用 |
getSystemResourceDefaults() |
读配置键 system_resource_defaults,与 DEFAULT_SYSTEM_RESOURCE_DEFAULTS 合并;首次读取时按 system_resource_defaults_version 做一次性迁移(v2:showSparklines 默认改为 true)并写回 |
setSystemResourceDefaults(patch) |
读-改-写合并保存 |
备注:封装的 invoke 命令:get_system_snapshot;配置键:system_resource_defaults、system_resource_defaults_version(另经 configService 间接使用 get_config/set_config)。
职责:托盘悬浮面板数据的唯一组装点——拉 char_detail + 账号列表 → 拼 TrayUserInfo → update_tray_user_data 写入配置键 tray_user_info 并触发 tray-user-info-updated 广播。抽出来是为了让 main.tsx(启动 5 秒后刷新)与 pages/settings.tsx(切换托盘显示角色)共用同一份字段映射,避免两处各写一遍漏字段。
导出:TrayUserInfo(interface)、refreshTrayUserData(roleId)、setTrayUser(roleId)、isTrayAvailable()。
主要依赖:@tauri-apps/api/core 的 invoke、@/utils/logger、@/utils/roleDataService、@/utils/accountService(getAccounts)。
| 符号 | 位置 | 说明 |
|---|---|---|
TrayUserInfo(interface) |
:18 | 与后端 crate::tray::TrayUserInfo(camelCase,字段均 Option)一一对应;nickname/avatar 允许 null;accountLevel(:23)= 游戏账号等级,bpCurLevel/bpMaxLevel = 通行证等级。components/tray-panel.tsx 复用该类型,不再各自声明 |
TrayQueryResult(私有 interface) |
:39 | query_role_data 返回的是**「路径字符串 → 值」的扁平映射**,所以叶子路径写作 "base.level" 键(result["base.level"]),不是嵌套对象;dungeon 的数值是字符串,统一 Number(...) || 0 兜底 |
refreshTrayUserData(roleId) |
:54 | 移动端(isMobileApp())直接返回 false 不发起 IPC。桌面:查询 char_detail 的 base.level/dungeon/bpSystem/dailyMission/weeklyMission → getAccounts() 取昵称头像 → invoke("update_tray_user_data")。accountLevel 优先取 base.level,取不到回退账号列表缓存的 level。空 roleId 直接返回 false;异常仅 logger.error 后返回 false,不上抛 |
setTrayUser(roleId) |
:110 | 移动端直接返回(无系统托盘)。桌面:invoke("set_tray_user")(失败忽略)+ refreshTrayUserData(roleId);设置页切换托盘账号用 |
isTrayAvailable() |
:130 | 移动端恒返回 false(Android/iOS 无系统托盘)。桌面:invoke<boolean>("tray_available") 并缓存结果;查询失败按 true 处理(后端 minimize_to_tray 自身仍有无托盘兜底)。Linux 无 StatusNotifier 宿主时为 false,标题栏、内嵌浏览器与设置页据此禁用「最小化到托盘」 |
备注:
- 封装的 invoke 命令:
update_tray_user_data、set_tray_user、tray_available;配置键:tray_user_info(写入侧),tray_user_role_id(由调用方读取后传入)。 - 右上角「等级」徽标显示
accountLevel(游戏账号等级),不是bpCurLevel;通行证等级只在面板的「通行证」MetricRow里显示。改字段时三处需同步:本文件、crate::tray::TrayUserInfo、面板组件。