PWA / 离线

Known 应用（Web / 桌面宿主）可作为 PWA 部署：可安装到桌面、离线打开、启动时展示 splash。 框架组件本身对 PWA 无感知；一切在宿主侧配置。

三件套

manifest.webmanifest

{
  "name": "My Known App",
  "short_name": "MyApp",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#090E18",
  "theme_color": "#2F5BFF",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

在 index.html（或 App.razor 的 <head>）里挂 <link rel="manifest" href="/manifest.webmanifest" />。

Service Worker

// sw.js
self.addEventListener('install', e => { /* 预缓存 app shell */ });
self.addEventListener('fetch', e => { /* 网络优先，失败回落缓存 */ });

注册：

@inject IJSRuntime JS
protected override async Task OnAfterRenderAsync(bool first)
{
    if (first) await JS.InvokeVoidAsync("KnownPwa.registerServiceWorker");
}

wwwroot/js/web.js 里 KnownPwa.registerServiceWorker 是一个薄封装。

主题色 & 图标

图标要求：192/512 常规 + maskable 各一；theme_color 与 --brand 保持一致， 系统桌面 tile 才与站点视觉统一。

离线策略

• App shell 缓存：index.html app.css app.js 首次访问即入 CacheStorage。
• API 响应：网络优先，失败回落上次缓存；不承诺数据实时。
• 鉴权 Cookie：SameSite=Lax 保证 SW fetch 携带；离线时已登录用户仍可浏览上次数据。
• 强更：SW 版本 bump 时下次访问强制刷新缓存；known-studio.webmanifest 的 revision 字段驱动。

营销站要不要 PWA

不要。www.known.org.cn 是营销站 + 文档站，一次性访问、无账户态、无需安装； 加 PWA 反而增加 SW 缓存维护成本（内容改动后要 SW 强制刷新）。

有意不做

• Push 通知：尚未提供。
• Background Sync：网络恢复时自动重试离线写操作；规划中。
• 文件编辑（File System Access API）：宿主侧本地文件读写；规划中。

相关

• 部署形态与 sw.js 缓存策略相关，见Linux 部署指南。
• 主题色与 PWA theme_color 一致性见深浅色主题。