DeepChat 启动体验Splash Experience设计与实现从 Logo 加载动画到数据库解锁的透明窗口方案【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat导读启动画面是桌面应用留给用户的第一印象也是承载数据库解锁这类关键安全交互的必经入口。本文以 DeepChat 仓库中的 Splash Experience 规格文档 为核心深入剖析其Logo 动画加载 圆形系统解锁 矩形手动解锁的三态启动体验设计并结合 splashWindow.ts、loading.vue 等真实源码讲解透明 BrowserWindow 的创建参数、渲染进程四态切换、IPC 解锁契约以及 reduced-motion 无障碍降级等落地细节。读完本文你将掌握一套启动画面与安全解锁 UI 一体化的 Electron 实现范式。一、用户需求为什么启动画面需要一次重新设计规格文档首先明确了问题边界启动时应当呈现一个可识别的 DeepChat 加载画面同时必须在自动系统解锁与手动数据库解锁之间保持清晰的视觉区分对应 spec.md 的 User Need 一节。深层矛盾在于传统的纯文本加载进度文案既没有品牌感又无法承载是否需要用户输入密码这一语义。DeepChat 的方案是把启动画面升级为一个同时具备加载与解锁两种职责的状态机界面——它不只是一个 Logo还是一个安全交互入口。二、设计目标四态界面与圆形/矩形视觉语言规格文档列出的 Goals 可以归纳为四件事用基于 Logo 的动画替代文本加载进度animated logo-based splash加载态与系统凭据解锁态使用圆形 DOM 构图circular DOM compositions手动密码解锁保持矩形、功能完整square and functional不改变既有数据库解锁的 IPC 行为preserve existing IPC behavior。落到代码里渲染进程 loading.vue 用一个moderef 维护四个互斥状态见第 176 行const mode refloading | system-unlock | unlock | recovery(loading)mode视觉容器交互内容触发场景loading圆形loader-stage--orb无纯动画应用初始化、启动加载system-unlock圆形unlock-stage--orb无等待系统凭据从系统凭据库读取保存的密码unlock矩形unlock-stage--manual密码输入框 Unlock / Quit需要用户手动输入 SQLite 密码recovery矩形unlock-stage--manual密码输入 / Start empty / Quit数据库损坏、无法读取等恢复场景圆形与矩形的区分在模板中非常直观加载态与系统解锁态挂载--orb变体类由aurora-background渲染出一个 340px 的圆形边框容器手动解锁与恢复态挂载--manual变体类使用不透明表单面板unlock-panel--manual去除背景与阴影回归透明表单。三、验收标准逐条落地3.1 加载态Logo 分层光效 reduced-motion验收标准第一条要求加载态使用 DeepChat Logo、分层光效并支持 reduced-motion。代码中对应logo-loader容器内的一组元素div classlogo-loader aria-hiddentrue span classlogo-bloom/span span classlogo-bloom logo-bloom--inner/span span classcore-flare/span span classspeed-line speed-line--one/span span classspeed-line speed-line--two/span div classlogo-mark logo-mark--dark v-htmldarkLogo / div classlogo-mark logo-mark--light v-htmllightLogo / /div这些元素分别承担外层光晕扩散bloom-deploy、内层闪光inner-bloom-flash、核心高光core-flare、左右两道速度线speed-scan以及 Logo 主体的机械式组装mech-frame-arrive/mech-body-lock/mech-tail-fold。reduced-motion 支持在文件末尾的媒体查询中完整实现loading.vuemedia (prefers-reduced-motion: reduce) { .aurora-ribbon, .aurora-pool, .logo-bloom, .core-flare, .speed-line, .logo-mark, .logo-mark :deep(path), .unlock-logo, .unlock-logo :deep(path) { animation: none; } .speed-line { display: none; } }所有动画在系统开启减弱动态效果时被整体关闭速度线直接隐藏符合无障碍最佳实践。3.2 圆形背景由 DOM/CSS 绘制而非窗口形状验收标准第二条非常关键圆形背景必须由渲染进程 DOM/CSS 创建而不是依赖 BrowserWindow 的 shape 配置。查看 splashWindow.ts 中窗口创建参数可以确认窗口本身只是一个 420×340 的矩形透明窗口this.splashWindow new BrowserWindow({ width: 420, height: 340, icon: iconFile, resizable: false, movable: false, frame: false, alwaysOnTop: true, center: true, show: false, // 先隐藏窗口等待 ready-to-show 以避免白屏 autoHideMenuBar: true, skipTaskbar: true, transparent: true, backgroundColor: #00000000, webPreferences: { nodeIntegration: false, contextIsolation: true, preload: path.join(__dirname, ../preload/splash.mjs), sandbox: false, devTools: is.dev } })圆形效果完全由 loading.vue 的 CSS 承担.loader-stage--orb .aurora-background, .unlock-stage--orb .aurora-background { top: 50%; left: 50%; width: 340px; height: 340px; border: 1px solid rgb(148 163 184 / 26%); border-radius: 50%; box-shadow: inset 0 1px rgb(255 255 255 / 10%); transform: translate(-50%, -50%); }这种透明矩形窗口 DOM 圆形构图的取舍让窗口无需依赖平台 shape API 即可呈现任意形状同时保留了alwaysOnTop、center、skipTaskbar等窗口语义跨平台表现一致。3.3 手动解锁保持矩形且密码控件可用第三条验收标准要求手动解锁使用矩形 DOM 背景并保留密码控件。unlock/recovery两个状态下的表单包含密码输入框unlock-inputtypepasswordautocompletecurrent-passwordautofocus、主按钮Unlock、辅助按钮Quit恢复态另有Start empty带二次确认文案Confirm start empty。手动解锁态输入框自动聚焦input事件实时控制提交按钮的disabled状态未输入密码时无法提交。3.4 真实解锁请求与进度事件驱动状态流转第四条要求真实的解锁请求与进度事件仍能驱动状态迁移、提交与取消。这条由主进程 → preload → 渲染进程的完整链路保证详见下文第四节。四、主进程 SplashWindow生命周期与显示策略4.1 窗口创建与三段式显示门控src/main/app/splashWindow.ts 中的SplashWindow类管理整个启动画面的生命周期。窗口创建后并不立即显示而是等待三个条件同时满足maybeShowSplash第 381-393 行splashReadyToShowBrowserWindow 触发ready-to-showsplashShowDelayElapsed距离创建已过去 200msSPLASH_SHOW_DELAY_MS 200第 28 行suppressSplashShow为 false未被主窗口创建事件抑制。这套延迟机制用于避免启动画面一闪而过白屏闪烁或与主窗口出现竞态。forceShowSplash第 395-424 行则用于解锁请求场景当数据库解锁/恢复请求到来时跳过延迟立即显示skipDelay: true即使渲染进程尚未加载完成也会在splashLoadPromise完成后补显。4.2 渲染器加载的三级回退链loadSplashRenderer第 447-487 行按优先级依次尝试三种加载来源开发模式下先尝试ELECTRON_RENDERER_URL下的/splash/index.html与/splash/其次加载打包后的本地文件../renderer/splash/index.html最后回退到buildInlineFallbackSplashUrl()生成的内联data:text/html兜底页面第 556-771 行。兜底页面内置了完整的手动解锁、恢复、系统解锁与加载四种 UI并在密码提交逻辑上与正式页面保持一致——这意味着即便渲染资源加载失败解锁流程依然可用。兜底页还通过.shell--manual-unlock类切换不透明背景与正式实现的视觉语义相同。4.3 关闭流程与平滑过渡close()第 225-257 行默认会 resolve 未决的解锁/恢复请求传null表示取消并清理pendingUnlockProgress如果窗口当前可见且未指定skipTransition会先等待 500ms 再关闭为主窗口出现留出平滑过渡时间。调试场景关闭则使用skipTransition: true立即关闭。五、IPC 契约解锁请求的完整闭环规格文档强调不得改变既有数据库解锁 IPC 行为这些通道定义在 src/shared/contracts/databaseSecurity.tsexport const DATABASE_UNLOCK_REQUEST_CHANNEL database-security:unlock-request export const DATABASE_UNLOCK_SUBMIT_CHANNEL database-security:unlock-submit export const DATABASE_UNLOCK_CANCEL_CHANNEL database-security:unlock-cancel export const DATABASE_UNLOCK_PROGRESS_CHANNEL database-security:unlock-progress export const DATABASE_RECOVERY_REQUEST_CHANNEL database-security:recovery-request export const DATABASE_RECOVERY_SUBMIT_CHANNEL database-security:recovery-submit export const DATABASE_RECOVERY_CANCEL_CHANNEL database-security:recovery-cancel对应的载荷类型同样由该文件定义export type DatabaseUnlockReason | manual-required | safe-storage-unavailable | system-key-missing | invalid export type DatabaseUnlockRequestPayload { requestId: string reason: DatabaseUnlockReason safeStorageAvailable: boolean } export type DatabaseUnlockProgressPayload { active: boolean safeStorageAvailable: boolean } export type DatabaseRecoveryRequestPayload { requestId: string kind: DatabaseStartupFailureKind // true-corruption | unreadable | orphaned-sidecar preservedPath: string invalidPassword?: boolean quarantineFailed?: boolean }5.1 主进程侧请求注册与 IPC 校验主进程在requestDatabaseUnlocksplashWindow.ts中为每次解锁生成带时间戳与随机数的requestId将resolve回调挂入unlockRequest字段随后forceShowSplash({ skipDelay: true })并广播状态。渲染进程提交密码后监听器第 270-336 行会做三重校验发送者校验isSplashSender检查event.sender.id必须等于 splash 窗口的 webContents id防止其他窗口伪造提交requestId 校验载荷中的requestId必须与当前挂起请求一致类型校验密码必须是 string 且非空。满足条件后才调用resolve(password)或resolve(null)取消从而把 Promise 的结果交还给数据库启动流程。恢复请求的提交同样经过parseRecoverySubmit第 793-811 行对start-empty/password两种 action 做白名单解析。5.2 preload 桥接上下文隔离下的安全暴露splash-preload.ts 通过contextBridge.exposeInMainWorld(deepchatSplash, splashApi)暴露最小 API渲染进程window.deepchatSplash上只有六个事件订阅方法与四个提交/取消方法onUnlockRequest/onUnlockProgress/onRecoveryRequest/onDebugModesubmitUnlock/cancelUnlock/submitRecovery/cancelRecoverygetLanguageState经 configGetLanguageRoute 获取语言状态用于 splash 页 i18n。注意 preload 对提交载荷同样做了前置校验如密码非 string 直接丢弃未通过校验的消息不会发往主进程形成第二道防线。窗口加载完成后还会通过webFrame.setVisualZoomLevelLimits(1, 1)与setZoomFactor(1)锁定缩放保证 splash 布局尺寸精确。5.3 渲染进程侧事件驱动的状态机渲染进程在onMounted中注册四个监听loading.vue由handleUnlockRequest、handleUnlockProgress、handleRecoveryRequest、handleDebugMode分别驱动状态迁移handleUnlockProgress({ active: true })→ 切到system-unlock此时显示Unlocking local database / reading the saved password from the system credential storehandleUnlockProgress({ active: false })且当前为system-unlock→ 回到loadinghandleUnlockRequest→ 切到unlock根据reason展示不同提示system-key-missing提示凭据缺失需重新输入safeStorageAvailablefalse提示当前设备不支持系统解锁等handleRecoveryRequest→ 切到recovery按kind展示数据库无法读取 / 残留 journal 文件 / 数据库损坏等差异化文案unreadable时聚焦密码框。六、Logo 素材受信任的本地 SVG 与路径级动画约束条件要求仅使用受信任的本地原始 SVG 素材。两份 Logo 位于 src/renderer/src/assets/splash/logo-v3-dark.svg 与logo-v3-light.svg通过 Vite 的?raw导入为字符串后经v-html内联import darkLogo from /assets/splash/logo-v3-dark.svg?raw import lightLogo from /assets/splash/logo-v3-light.svg?raw深色/浅色两套 Logo 分别对应prefers-color-scheme: dark/lightCSS 中.logo-mark--dark与.logo-mark--light互为显隐。更重要的是SVG 内部把海豚 Logo 拆成了四个带 class 的独立路径.logo-wake尾部水痕、.logo-body身体、.logo-tail尾巴、.logo-eye眼睛配合 CSS 的:deep(path)选择器可以让每一条原始路径独立运动模板注释明确写道Trusted local SVG sources are inlined so each original path can move independently。例如尾巴折叠使用transform-box: view-box; transform-origin: 688px 515px定位旋转轴第 673-676 行组装完成后进入native-tail-idle与eye-blink的待机循环动画。七、调试与测试开发态场景预览7.1 DEV-only 的调试路由规格文档将开发版 splash 预览控件明确列为 Non-Goal但仓库仍保留了开发态专用的调试入口。路由契约定义在 src/shared/contracts/routes/debug.routes.tsexport const debugShowSplashScenarioRoute defineRouteContract({ name: debug.showSplashScenario, input: z.object({ mode: z.enum(SPLASH_DEBUG_MODES) }), output: z.object({ shown: z.boolean() }) }) export const debugCloseSplashScenarioRoute defineRouteContract({ name: debug.closeSplashScenario, input: z.object({}), output: z.object({ closed: z.boolean() }) })其中SPLASH_DEBUG_MODES定义于 src/shared/contracts/splash.tsexport const SPLASH_DEBUG_MODES [loading, system-unlock, unlock, recovery] as const export type SplashDebugMode (typeof SPLASH_DEBUG_MODES)[number]路由处理位于 src/main/app/routes.ts当import.meta.env.DEV且应用未打包!app.isPackaged时才真正调用splash.showDebugScenario(input.mode)并返回{ shown: true }否则直接返回{ shown: false }。调试模式下渲染进程会进入isDebugPreview true密码提交被禁用password.disabled/submit.disabled并在 hint 处显示Development preview — password submission is disabled从机制上杜绝调试误触提交。调试关闭走closeDebugScenario()skipTransition: true立即关闭。7.2 自动化测试显示契约的守护启动画面的显示逻辑有专门的测试覆盖test/main/app/splashWindow.display.test.ts。该测试使用 JSDOM Mock BrowserWindowmock 了show/focus/close/loadURL/loadFile/webContents.send等验证包括BrowserWindow 创建参数透明、无边框、置顶、尺寸等是否符合约束200ms 显示延迟与ready-to-show门控解锁/恢复请求到来时的forceShowSplash强制显示路径IPC 监听器对非 splash 发送者、错误 requestId 的拒绝行为关闭流程对未决请求的 resolve 与过渡延迟。这套测试把保持窗口尺寸、形状、阴影与启动时序这条约束从口头约定变成了可回归验证的契约。八、约束清单回顾规格文档的 Constraints 与实现一一对应约束实现证据透明窗口 透明画布加载/系统解锁态使用透明文档根index.html 中html, body { background: transparent }splashWindow.ts 的transparent: true, backgroundColor: #00000000手动解锁与恢复保留不透明表单背景.unlock-panel--manual透明化--orb圆形容器内嵌极光背景兜底页用.shell--manual-unlock { background: #020817 }保留窗口尺寸、形状、阴影与启动时序420×340、frame: false、alwaysOnTop、center、200ms 延迟门控、500ms 关闭过渡仅使用受信任的本地原始 SVG?raw内联logo-v3-dark.svg/logo-v3-light.svg不泄露机密、不改解锁授权行为contextIsolation: true、最小 preload API、发送者 requestId 类型三重校验、IPC 通道与载荷契约原样保留九、总结一份可复用的启动画面架构回到规格文档本身Splash Experience 的 Non-Goals 划定了清晰的边界——不做开发预览控件、不改 splash 生命周期时序、不改数据库解锁架构。这意味着本次演进是一次纯视觉与信息架构层面的重构窗口语义、IPC 契约、解锁授权逻辑全部保持不变改动的只是渲染层如何表达状态。从实现角度看这套方案的价值在于三点视觉与安全职责合一启动画面不只是品牌展示还承载了系统解锁、手动解锁、数据库恢复三类安全交互且通过圆形/矩形构图完成了语义传达分层清晰的进程协作主进程窗口生命周期 IPC 校验→ preload最小桥接 API→ 渲染进程四态状态机 CSS 动画每一层职责单一、可独立测试健壮的降级策略渲染资源加载失败时回退到内联 HTML且兜底页面同样具备完整解锁能力。对于需要在 Electron 应用中实现品牌化启动画面 数据库安全解锁的开发者这套从规格到实现的完整链路值得直接借鉴。相关文件索引规格文档docs/features/splash-experience/spec.md主进程窗口管理src/main/app/splashWindow.ts渲染进程四态组件src/renderer/splash/loading.vue渲染入口与 HTMLsrc/renderer/splash/main.ts、src/renderer/splash/index.htmlpreload 桥接src/preload/splash-preload.tsIPC 契约src/shared/contracts/databaseSecurity.ts调试模式契约src/shared/contracts/splash.ts、src/shared/contracts/routes/debug.routes.tsLogo 素材src/renderer/src/assets/splash/logo-v3-dark.svg、src/renderer/src/assets/splash/logo-v3-light.svg显示契约测试test/main/app/splashWindow.display.test.ts【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考