# browser **Repository Path**: adxb/browser ## Basic Information - **Project Name**: browser - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-15 - **Last Updated**: 2026-11-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # myBrowser(C# + WebView2) 一个自绘界面的多页签浏览器:页签可以是**普通网页**,也可以显示**本地 WPS 文档**。 文档同样是一个网页页签,页面是 `embed.html`,宿主的 WPS 原生窗口(`SetParent` 搬进来) 实时贴在那个页面里的 iframe 上——**没有单独的"文档页签"形态**。页签切换是 "一个显示、另一个隐藏",不重新加载、不丢状态。 无边框窗口:系统标题栏被移除,地址栏和页签栏是 **WPF 原生控件**(暗色主题, `ElementHost` 承载),窗口按钮、边缘缩放热区与拖动一并由它们负责。 ## 运行 ```bash dotnet run --project src/myBrowser -c Release ``` 需要:Windows 10+、本机装有 WPS Office、WebView2 Runtime(Win10/11 一般自带)。 所有文档都通过 `/embed.html` 打开(「打开文档」按钮、地址栏里的本地路径、示例页), 宿主不再有“文档页签”这种独立形态。 ## 版本检测与升级 发版与升级的完整操作手册(含精确的 git 命令、Gitee/GitLab/自建 Git 发版步骤、 排错与回滚):[docs/RELEASE.md](docs/RELEASE.md)。 启动 3 秒后按设置页「首页设置 → 版本检测地址」查询最新发行版:有新版本就弹框, 确认后下载附件、在退出后替换安装目录里的文件并自动重启;也可以「跳过此版本」 (记录在 `app_settings.json` 的 `update_skipped`,出新版本仍会提示)。 检查开关与地址都在设置页里,配置项写在 `app_settings.json`: | 键 | 说明 | | --- | --- | | `update_check` | 启动时是否检查(默认 `true`) | | `update_url` | 返回发行版 JSON 的完整地址;留空用默认 Gitee | | `update_skipped` | 跳过的版本 tag | 默认地址:`https://gitee.com/api/v5/repos/adxb/browser/releases/latest`。 换托管平台时只改这一条地址,各平台的最新发行版接口: | 平台 | 地址 | | --- | --- | | Gitee | `https://gitee.com/api/v5/repos///releases/latest` | | GitLab | `https://gitlab.com/api/v4/projects/<组>%2F<仓库>/releases?per_page=1`(取第一条) | | Gitea / 自建(Forgejo 同接口) | `https://<域名>/api/v1/repos///releases/latest` | | GitHub | `https://api.github.com/repos///releases/latest` | GitLab 自建实例挂在子路径下时用完整地址,例如 `https://<域名>/gitlab/api/v4/projects/<组>%2F<仓库>/releases?per_page=1`。 判断方法:浏览器直接打开这条地址能看到 `{"tag_name": …}` 就说明正确;404 = 还没有发行版。 返回结构兼容两种:Gitee/Gitea/GitHub 的 `tag_name + assets[].browser_download_url`, 以及 GitLab 的 `tag_name + assets.links[]`。只填 `owner/repo` 时按 Gitee 拼一次(兼容旧配置)。 发版约定: 1. 改 `src/myBrowser/myBrowser.csproj` 的 ``(如 `1.1.0`); 2. 发布单文件: `dotnet publish src/myBrowser/myBrowser.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -o publish/win-x64` 3. 把 `myBrowser.exe` 和 `wwwroot/` 打成一个 zip(升级会整包覆盖,页面资源才不会停旧版); 4. 在 Gitee 建发行版:tag 用 `v1.1.0`(与 `` 一致),附件上传该 zip。 ## 架构 ``` MainForm(WinForms,无边框,PerMonitorV2) ├─ ChromeBar(WPF,经 ElementHost Dock=Top,高 80 DIP:页签条 40 + 工具栏 40) │ ├─ 页签行:W 标志 / 页签 / "+" / 拖动填充 / 最小化-最大化-关闭 │ └─ 工具行:后退-前进-刷新 / 地址框(铺满整行) / 打开文档-星标-下载-设置(钉右) ├─ shell WebView2(Dock=Fill,内容区;页面来自 wwwroot,虚拟域名 http://app.local) │ └─ 只画内容区:新页签面板 / 缩放带(b/l/r/bl/br) ├─ 网页页签:每个页签一个 WebView2,铺在 #viewport 矩形上(WebTabs) └─ 嵌入的文档:WPS 窗口(SetParent 进来的原生子窗口,贴在 embed.html 里 iframe 的 矩形上,WpsHost)——「打开文档」/地址栏本地路径/远程 url 都开成 embed.html 页签 ↑ chrome.webview.postMessage 桥(无 HTTP、无端口、消息保序) ``` 三个坐标系只有一个真相:页面用 `getBoundingClientRect()` 量出 CSS 像素矩形连同 `devicePixelRatio` 一起发上来,宿主用 `ViewportOrigin()`(实测 `Chrome_RenderWidgetHostHWND` 的位置)换算成客户端物理像素,再交给 `SetWindowPos`。网页页签和文档占位走的是同一条换算路径,所以 125% 缩放下也严丝合缝。 ### 页签、页面与嵌入窗口怎么对齐 - 页面是唯一的页签所有者,宿主是唯一的窗口所有者;页面用**声明式**消息让两者对齐: - `webtabs`:所有"有网址的网页页签" + 当前活动页签 + 内容区矩形; - `chromeview`:把页签列表、状态文字、地址框内容推给 WPF 栏渲染。 - `embed.html` 自己上报 iframe 的矩形(`open/rect/close/ping`),宿主的 `WpsHost` 把 WPS 窗口摆到那个矩形上;iframe 被隐藏 → 窗口隐藏,从 DOM 移除 → 窗口按关闭策略收掉。 - WPF 栏 → 页面的命令也走桥:`newTab / openUrl / activate / closeTab / closeLeft / closeRight / closeAll / reorderTabs / navBack / navFwd / navReload / open / addr / download / settings`——页面仍是唯一状态所有者,WPF 栏是纯视图 + 输入转发。 - 每条消息都是全量状态,宿主做的是"让现实匹配",因此不存在需要额外对账的增量状态。 - 网页页签的浏览器在 shell 内容区之上,WPS 窗口再靠 `HWND_TOP` 压在最上面; WPF 栏(ElementHost)与内容区严格不重叠(Dock=Top + 其余 Dock=Fill),绕开 airspace。 ### 页签的右键菜单与拖拽排序 - **右键菜单**(关闭左侧 / 关闭右侧 / 关闭所有):WPF 栏只报告"哪个页签被右键、 它的 index 与总数、菜单应出现的屏幕坐标",真正的菜单是宿主侧的 WinForms `ContextMenuStrip`(暗色 `ProfessionalColorTable`)。不用 WPF `ContextMenu` 是实测结论:在 ElementHost 里它的 Popup 会错位、被裁剪、样式失控——原生 HWND 菜单没有这些问题。菜单项经 chrome 通道下发,页面批量 `closeTab`(关到嵌入了文档的 页签时走宿主那边的关闭语义),关空后照常自动补一个新页签。 - **拖拽排序**在 WPF 栏内完成:按下页签即捕获鼠标,移动超过 6 px 进入拖拽 (页签半透明),松开时按视觉顺序发 `reorderTabs`;页面把新顺序纳入 `tabs` (顺序只影响显示,激活/几何/可见性都按 id 寻址,无需额外对账)。拖拽期间 到达的 chromeview 批量会推迟,合并时保留拖出来的顺序。**普通单击也走这条推迟 路径**——`FinishReorder` 的非拖拽分支必须把推迟的批量刷出来,否则单击激活的 高亮(就在那份 chromeview 里)会被吞掉,表现为"点了页签但高亮不切换"。 - 非活动页签必须**仍然上色**(`InactiveTabBrush` 底色 + `LineBrush` 描边): 全透明的页签在暗色条上不可见,条看起来像一串松散的标题而非等宽的页签槽, 会被误报成"页签宽度不受控"。 - 一个踩过的坑:页签项的事件处理器捕获了 `for` 循环变量,所有页签都看到循环 结束后的 index(== count),菜单禁用态因此全错——循环体内先拷贝到局部变量。 ### sessionStorage 的同源继承 每个网页页签是独立 WebView2 实例:Cookie 和 HTTP 缓存靠共享的 Environment 打通, 但 `sessionStorage` 是"每实例 + 每源"的,Chromium 对 `window.open` 弹窗的自动继承 在这里不成立。宿主手工补齐:`NewWindowRequested` 时若目标与 opener 当前文档 **同源**(或目标是 about:blank,按定义继承),先把 opener 的 `sessionStorage` `ExecuteScriptAsync` 出来挂到目标 URL 上;新页签的 WebView2 在首次 `ContentLoading`(早于页面脚本的正常工作时机)写回。dump 晚于页面加载也能补写, 一次性标志防重复。跨域弹窗、地址栏/Ctrl+T 开的新页签一律不复制。 弹窗页签不是追加到条尾,而是**插在 opener 页签后面**(`wpopup` 消息带着 opener id,页面在 `tabs` 里移位后重推 chromeview);opener 已关闭/未知时回退为追加。 ## 无边框窗口是怎么做的 - `FormBorderStyle` 保留 `Sizable`:`WS_THICKFRAME` 是系统原生缩放循环(吸附、 动画、边缘阻力)的前提,`FormBorderStyle.None` 会把它一起拿掉。 - `WM_NCCALCSIZE` 直接返回 0,声明"整个窗口都是客户区",于是系统一个像素都不画, 界面完全由 WPF 栏 + 内容区页面拥有。 - **页签栏就是标题栏(WPF 原生实现)**:没有独立的标题栏行——最顶部一行是 WPF 页签行,左侧是页签和"+"按钮,右侧尽头是最小化/最大化/关闭三个按钮(类 Chrome)。 页签行空白区即拖动区(按下后进入 `DragStarted` → 宿主 `ReleaseCapture()` + `HTCAPTION`),双击空白最大化(`ClickCount >= 2`),按钮 hover 有独立高亮 (关闭键 hover 红)。按钮落在 WPF 内,天然不与任何缩放热区抢命。 - WPF 栏用代码构建(不走 XAML,免去 csproj 配置):扁平按钮 = `ControlTemplate` 里的 `Border` + **必须**有 `ContentPresenter`(否则内容根本不渲染,这是踩过的坑); 默认 Aero 模板会自己画 hover 底色,盖掉暗色主题,所以全部换掉。 - **页签宽度(内容自适应,cap 220)**:`Measure(infinite)` 取内容期望宽,`width = min(期望宽, 220)`, 下限 80(MinWidth);长标题在 `MaxWidth=180` + 省略号处截断。页签少时不铺满条—— "+" 紧跟最后一个页签;页签变多挤压到滚动区(隐藏滚动条、滚轮横滚),"+" 固定在窗口按钮前。 页签内部用 DockPanel:图标靠左、标题占中间、**关闭 X 钉在右缘**(MinWidth 撑出的空隙由 标题列吸收),X 字形加粗。 - **页签外形对齐 Edge**(2026-11-15):页签条 40 DIP、工具栏 40 DIP(总高 80,125% 下正好 100 物理像素);页签 36 DIP **贴顶**、只有上圆角、彼此紧挨(间距 0),两个相邻的**非活动** 页签之间靠 1px 左边框画分隔线(贴着活动页签的那侧不画);关闭 X 只在**活动页签或悬停** 时显示(用 Opacity 隐藏,位置保留,标题不会因为悬停而跳动)。 - **条宽来源是宿主直喂,不信 ElementHost**:实测最大化→还原后 ElementHost 向 WPF 传导的宽度可能停在最大化尺寸(页签按旧宽渲染、窗口按钮被挤出窗外且不再自愈)。 所以 `MainForm` 在 `Resize`/`OnDpiChanged` 里把 `ClientSize.Width × 96 / DeviceDpi` 喂给 `ChromeBar.SetHostWidth()`,`UpdateTabArea` 用它并**显式钉死 `row0.Width`**, 彻底绕开 HwndSource 的陈旧约束。 - 最大化时 WinForms 给的窗口矩形是"工作区外扩一圈边框"(为有边框的窗口准备的), 所以在 `WM_NCCALCSIZE` 里把客户区收回到工作区——窗口矩形仍向屏幕外溢 9 px(不可见), 客户区正好等于工作区,任务栏不被盖住。这是唯一一处需要按 DPI 反复验证的地方。 - 拖动与缩放由 WPF 栏和页面共同发起:`mousedown` 落在 WPF 页签行空白处 → `DragStarted` 事件 → 宿主 `ReleaseCapture()` + `SendMessage(WM_NCLBUTTONDOWN, HTCAPTION)`; 落在 WPF 栏两端/上缘的透明矩形 → `ResizeStarted(边码)`;落在内容区边缘的 缩放带 → 发 `win.resize` 并带上码(`l/r/b/bl/br`,顶缘归 WPF)。这样进入的是 **系统自己的**模态尺寸循环,行为和普通窗口完全一致,而不是自己模拟一套。 - 边缘的缩放热区:顶缘三段(t/tl/tr,横跨 5 列)由 WPF 栏自己的透明矩形拥有; 内容区外侧 10 px 留白里的 l/r/b/bl/br 拖拽带仍是页面 `position:fixed` 元素。 **顶边不留留白**(`#viewport` 的 inset 是 `0 10px 10px`),内容直接贴着工具栏, 否则工具栏和网页之间会多出一条 10px 的缝。 原生窗口(网页 WebView2 / WPS)永远压在 DOM 之上,热区绝不能和它重叠; 最大化状态下全部隐藏。 ## 为什么嵌入是稳定的 WPS 是独立进程,随时会改自己的窗口样式、大小、可见性,还会把别的文档合并进当前窗口。 所以宿主不信任"设置一次就完事",而是每 200 ms 重申四个不变量(`WpsHost.Enforce`): 1. 窗口还活着(`IsWindow`); 2. 还是我们的子窗口(`GetParent`,WPS 换文档时会自己脱管); 3. 样式仍是"无标题栏的子窗口"(WPS 会把 `WS_CAPTION` 改回去); 4. 几何位置正确、可见性正确(WPS 加载时会自己改大小/隐藏)。 外加几条由观察得来的行为修正: - **文档由 COM 打开,窗口由 Win32 托管**:打开/关闭/只读一律走 `MudTools.OfficeInterop`(`KWPS.Application` / `KET.Application` / `KWPP.Application`)——COM 自动化库管得了文档,管不了窗口,所以 `SetParent` 那一层仍然是我们自己的。文档名、是否已关闭(`Documents.Count == 0`) 都从 COM 读,不再靠窗口标题猜。 - **一个槽位一个 Application 实例**:WPS 会把同一个实例里的文档塞进一个带页签的 框架窗口,共用一个实例就没法按槽位分别嵌入。代价是每个文档一个 WPS 进程。 - **帧窗口类按模块区分**:Writer=`OpusApp`、表格=`XLMAIN`、演示=`PP12FrameClass` (WPS 刻意模仿 Office 的类名)。PPT 的 `ActiveWindow.HWND` 返回的是内层 `mdiClass`,要沿 `GetParent` 走到已知帧类名,否则拿不到能嵌入的那一层。 - **页面切换文档**:在 WPS 里换到另一篇文档时(同实例内换页签),页签名跟着变 (`retitled`);文档被关掉时页签自动移除(`lost`)。 - **阴影图层残留**:WPS 用顶层 popup 图层画无边框窗口的阴影(owner 指向框架)。 窗口被嵌入后 WPS 把 owner 改指宿主窗体并停止维护该图层,它会带着旧快照停在 过期的屏幕坐标上,把"残影线条"画到其他应用程序上。宿主每轮扫描:类名以 `KLite` 开头且 owner 链根指向本窗体的可见阴影层一律隐藏。 - **页签栏遮罩**:WPS 自己的页签栏(UIA 里的 `KPromeHeaderBar`,40 DIP)上盖着 一层 30% 黑色半透明子窗口。不盖的话用户点 WPS 那个 X 会绕过宿主的关闭语义, 在我们背后把文档关掉。遮罩是 `WS_EX_LAYERED` 子窗口(alpha 77,取 0 就连鼠标 一起穿透),靠 `SetWindowPos(HWND_TOP)` 保持压住 WPS 帧,切页签时跟着显示/隐藏。 ## 地址栏 - 输入网址回车:当前页签是网页就在本页跳转。 - 不含点、不含空格的输入当作搜索词(Bing)。 - 看起来像 Windows 路径(`C:\…`、`\server…`、或常见文档扩展名)则**新开一个 `embed.html` 页签**打开它(默认 `onclose=ask`),不再有单独的文档页签。 - 「打开文档」按钮同理:先弹文件对话框拿路径,再按同一条 `embed.html` 链接打开。 - **改了一半可以反悔**:在地址栏里改了还没回车,按 `Esc` 或让焦点离开地址栏,内容会 恢复成当前页签的真实地址(`RevertAddress`)。点建议项或回车才是提交。 ## 关闭语义 关闭策略由 URL 参数 `onclose` 决定,只影响**有未保存修改**的文档;没有修改时一律直接关。 - **`ask`(默认)**:弹宿主自己的确认框「保存 / 不保存 / 取消」。保存走 COM `Save()`, 失败就保持原样;不保存 = 关闭并丢弃;取消 = 页签和文档都留着。 - **`close`**:直接结束 WPS、丢弃修改。只读(`ro=1`)和远程临时副本强制用它。 - **`save`**:先 `Save()` 再关;保存失败则保持原样。 - **`return`**:把窗口交还桌面,文档继续开着(页签关闭)。 **为什么不用 WPS 自己的保存提示**:那是另一个进程的模态窗口,宿主只能 `WM_CLOSE` 再猜 结果——弹框期间拖窗口会整块变白、用户点取消后请求还挂着。换成宿主原生对话框之后, 结果由 `ShowDialog` 直接返回;确认框开着时心跳看门狗会暂停(否则会被误判成页面失联)。 判断“有没有修改”仍看 COM 的 `Saved`,读失败按“有修改”处理(宁可多问一句)。 ## 网页里嵌入文档(embed.html) `http://127.0.0.1:60000/embed.html` 可以让任意网页(典型是 Vue SPA 里的 iframe) 嵌一份 WPS 文档:页面只放占位区,宿主把原生 WPS 窗口贴上去。 | 参数 | 取值 | 默认 | 说明 | | --- | --- | --- | --- | | `file` | 本地文件路径(含中文/空格的路径先 `encodeURIComponent`) | 无 | 打开本地文件;与 `url` 二选一,两个都给时以 `file` 为准 | | `url` | `http(s)` 链接 | 无 | 宿主下载成临时副本再打开,同一链接缓存一天 | | `ro` | `1` = 只读;`0` / 省略 = 可写 | **可写** | 只读打开(COM 的 readOnly,不改文件属性) | | `onclose` | `close` = 直接关闭丢弃;`ask` = 问用户(保存 / 不保存 / 取消);`save` = 先保存再关;`return` = 交还桌面 | **ask** | 没有未保存修改时一律直接关闭;`ro=1` / 远程副本强制按 `close` | | `mask` | `1` = 显示页签栏遮罩;`0` = 不显示 | **1** | 遮罩盖住 WPS 自己的页签栏(0.3 黑色),见上面的遮罩说明 | 布尔参数 `ro` / `mask` 不区分大小写、忽略首尾空白;只写参数名(如 `?ro`)按「省略」处理。 `onclose` 只认 `close` / `ask` / `save` / `return`,其它值按 `ask`。旧参数 `noreturn` 仍可用作别名:`0` → `return`、`1` → `close`、`2` → `ask`。 页面会自动附带实例号(`eid`),调用方不必传。 ``` embed.html?file=<路径> 默认 onclose=ask:有修改就弹确认框 embed.html?file=<路径>&onclose=close 有修改也直接关、丢弃 embed.html?file=<路径>&onclose=save 有修改就先保存再关 embed.html?file=<路径>&onclose=return 有修改就把窗口交还桌面 embed.html?file=<路径>&ro=1 只读;强制按 close 处理 embed.html?file=<路径>&mask=0 不盖页签栏遮罩 - **页签名**:`file` 直接取文件名;`url` 先取响应头 `Content-Disposition` 的附件名, 取不到再从链接提取(`fileUrl=` 这类内层参数优先)。附件名可能是纯文本、百分号编码 或 RFC 2047 编码字,三条路都会解码——绝不显示临时副本名(`embed_xxxx.xlsx`)。 - **生命周期接入方零代码**:iframe 被隐藏 → 窗口隐藏;iframe 从 DOM 移除 → 文档按 上面的关闭语义收摊。钩子是注入到父页面的 `pagehide` + MutationObserver,只信任 127.0.0.1 / localhost 来源。 - 演示页:`/embed_demo.html`(2×2 四个 iframe)、`/embed_spa_demo.html`(模拟 SPA 页签,可切换、可关闭)。 ## 快捷键 在网页内容里也有焦点时同样生效:`Ctrl+T` 新页签、`Ctrl+W` 关页签、`Ctrl+L` 定位 地址栏、`Ctrl+Tab` / `Ctrl+Shift+Tab` 切换、`Ctrl+1..9` 跳到第 n 个页签。 网页内容里的按键先到浏览器进程,页面 JS 和 WinForms 都看不见,所以宿主装了 `IMessageFilter`(`Application.AddMessageFilter`),在消息到达目标窗口之前截获。 (`CoreWebView2Controller.AcceleratorKeyPressed` 也能做同样的事,但 WinForms 控件 没有暴露那个事件,反射私有字段不值得为它冒版本升级的风险。) ## 内置静默打印服务(一比一复刻 tabbrowser 的 Go 实现) 应用启动时在内置 HTTP 服务里提供第三方软件依赖的打印接口(`PrintHttpService.cs` + `PrintNative.cs` + `ZplConvert.cs` + `FetchFileHandler.cs`),协议行为与 Go 版逐条对齐: - **端口策略**:默认 60000。启动时先探测 60000..60031 的 `/v2/version`——返回有效 JSON 且 version 非空 → 已有实例提供服务,直接复用不再监听;否则从 60000 起绑定 (占用则自增,`http://+:port/` 无权限时退回本机回环前缀)。可用 `no_proxy=1` 环境或 探测端明确绕过系统代理(探测目标是回环,走代理会慢到不可用)。 - **接口**(GET/POST 均可,`/directprint` 仅 POST;CORS 全开 + `X-Trace-Id`): - `/ping` → `pong`(不受开关影响); - `/version` → `{"version":"2.3.4"}`(版本可配置,默认 2.3.4); - `/v2/version` → `{"version":..,"app":..,"appVersion":..,"appBuild":..}`(app 为配置的应用名; 不受开关影响,探测/复用端口就靠它); - `/port` → 当前端口(纯文本); - `/printerlist` → 字符串数组,每项为内嵌 JSON `{"name":..,"def":"true|false"}`; - `/directprint`:表单 `file_source / source_type(http|LocalFile|Base64|RawText) / file_type / print_method(sys|pdf) / printer / zoom_type(0 自动适配纸张|1 原始大小|2 指定宽高) / width / height / rotate(0-3,斑马未传默认 2) / fastprint(忽略) / sn`; 斑马打印机(名称含 zebra/zdesigner/ztechnologies)走 **PDFtoZPL** 转 `^GFA`(阈值 128、 十六进制游程压缩、无抖动)后按参考实现包装 `^PO/^PW/^LL/^LT-25/^LS5` 以 winspool RAW 发送并等作业离队(90s);普通打印机优先 GDI 静默(CreateDCW("WINSPOOL") + HALFTONE 等比居中),失败回退 `ShellExecute "printto"/"print"`;返回 `{"code":"ok|error","sn":..,"message":..}`; - `/FetchFile[/list|/{name}]`:`dir` 必填;`list` 返回 `[{fileName,size}]`;不带 `backup_file` 时只读(默认取第一个文件时 content 为空 base64);带 `backup_file` (可含子目录 `\6\7186144405-1.jpg`)时读源文件 → 写入 `dir\backup\...` → 删源文件 → 返回 base64。响应为 `{"code":0|1,"msg":..,"files":..,"fileName":..,"content":..}` (camelCase,空值字段省略),code 0 失败 / 1 成功。 - **开关只管打印类接口**:设置页的「静默打印」关掉后,`/version`、`/port`、`/printerlist` 返回 `{"error":"打印服务未启用"}`,`/directprint` 返回 `{"code":"error","sn":..,"message":"打印服务未启用"}`,`/FetchFile*` 返回 `{"code":0,"msg":"打印服务未启用"}`。**监听器和 `/ping`、`/v2/version` 常驻**—— 端口探测、OpenCode 测试页和嵌入页都靠这个服务,不能随开关启停。 - **同一个监听端口还提供页面与其它 API**(不受打印开关影响): `/embed.html`、`/embed_demo.html`、`/embed_spa_demo.html`、`/opencode_test.html`, `/api/opencode`(GET 查询串或 POST JSON:`model / model_text / files / prompt / format_json`,`files` 必须是逗号分隔字符串,不接受数组;返回 `{"success":..,"model":..,"output":..,"command":..,"traceId":..}`), `/api/localstorage`(给指定域名的页签写 `localStorage`:`domain`(或 `host`)+ `key` + `value`,成功返回 `{"success":true,"tab":..,"url":..,"key":..,"value":..}`)。 - **配置**:exe 同目录 `app_settings.json`(缺失即默认),设置页写的字段都会落在这里: `{"name":"应用名","print_version":"2.3.4","print_enabled":true,"theme":"dark", "homepage":"","password_autosave":true,"window_x":..,"window_y":..,"window_width":.., "window_height":..,"window_maximized":false}`(`print_enabled` 默认关、`password_autosave` 默认开;文件里不认识的键会原样保留)。 ## 开发辅助 - `--demo`:启动后自动打开两份示例文档。 - 宿主日志:`%TEMP%\wps-embed-host.log`(open/guard/ready/retitle/lost/restore/webtab 时间线,以及未处理异常与退出原因)。 - 示例文档生成在 `%TEMP%\myBrowser-demo\`。 ## 成熟方案调研结论(为什么不用别的) - **WPS 官方没有"把本地客户端窗口嵌进网页"的 API**。开放平台提供的是 JS 加载项(扩展 WPS 自身)、COM/JSAPI 自动化(控制文档内容,不提供窗口嵌入)、 以及 WebOffice 云方案(JS-SDK + 服务端,399 元/人/年起,文件须存到服务端)。 要在本地嵌客户端窗口,`SetParent` 承载是业界通行做法。 - **WebView2 必须用窗口化宿主,且外层别用 WPF**:WPF 的 WebView2 是 HwndHost, 永远压在 WPF 内容之上(经典 airspace 问题),混入原生子窗口后 z 序不可控。 WinForms 里 WebView2 和 WPS 窗口是同一父窗口下的普通兄弟 HWND,z 序确定。 - 多页签浏览器为什么"每页一个 WebView2"而不是单实例多导航:每个页签独立的历史、 独立的滚动位置、独立的崩溃域,切换只是 `ShowWindow`;代价是每页一个渲染进程。