Background Image Control

中文 | English

中文

为 VS Code 界面设置背景图：3 步引导，一键完成。整个界面统一半透明，背景图静默透出，让代码窗口看起来像一张壁纸。

界面文案跟随 VS Code 显示语言（简体中文 / English），无需手动切换。

效果预览（界面不透明度 60% · 主题 GitHub Dark · 蓝色壁纸）

功能特性

• 3 步引导：选择图片 → 调节界面不透明度 → 应用。也可以直接按 Ctrl+Alt+I 调出。
• 界面相对背景的透明度：一条设置让整个界面（编辑器 / 侧边栏 / Chat / 菜单…所有区域）统一透出背景图，数值越低背景图越清晰。
• 窗口按钮同步透明：自动把右上角最小化 / 最大化 / 关闭切换为 VS Code 自绘按钮，与界面一起透出背景（移除背景图时自动恢复原样；代价：失去 Win11 悬停“贴靠布局”菜单）。
• 调节即时生效：改透明度 / 换图 / 移除均实时生效（约 0.1 秒），无需重载窗口；仅首次应用需重载一次。
• 图片不透明度与模糊：单独控制背景图本身的浓淡，轻微模糊可提升文字可读性。
• 多种填充方式：铺满 / 完整显示 / 平铺 / 居中原大小。
• 本地与网络图片：本地图片直接引用原文件；网络图片自动下载缓存（离线可用）。
• 轻量稳定：样式表仅数 KB、图片直连，不做大文件内嵌，窗口启动无额外负担。
• 状态栏快速调节：点击状态栏「背景图: xx%」即可换图、增减透明度、重新应用。
• 自动维护：VS Code 更新导致注入失效时，启动后自动检测并恢复（无需管理员权限时静默完成）。
• Remote-SSH 同样生效：本扩展运行在本地客户端（UI 扩展），所有窗口同步显示背景图。
• 可随时还原：移除背景图无需权限；卸载扩展前可运行「彻底还原系统文件」把 VS Code 恢复原样。

使用方法

3 步引导（推荐）

命令面板（Ctrl+Shift+P）→ 输入 背景图 → 选择「背景图: 开始设置（3 步引导）」，或直接按 Ctrl+Alt+I：

1. 选择图片：本地图片（png / jpg / gif / webp / bmp / avif）或图片网址；
2. 界面不透明度：从 100%（看不到背景图）到 15%（背景图最清晰）任选，或输入自定义数值；
3. 应用：自动完成注入，点击通知里的「立即重载窗口」即可看到效果。

状态栏

点击右下角状态栏的 背景图: xx%：

设置项

可在设置界面搜索「Background Image Control」进行配置。修改设置即时生效（首次应用后）。

工作原理

VS Code 的界面无法由扩展直接绘制，本扩展采用业界通行做法：

1. 样式资产单独存放：样式表生成在扩展根目录的 background-image-control-assets\bg.css（用户区可写，改配置无需管理员权限）；图片直接引用原文件或网络缓存，不做内嵌；
2. 注入一行链接：在 VS Code 安装目录的 workbench.html 中注入 <link rel="stylesheet" href="vscode-file://…/bg.css">，同时按官方算法修复 product.json 校验和，避免「安装已损坏」提示；
3. 整层统一透明：背景图贴在最底层；对界面根容器设置一个整体不透明度（一条规则作用于所有面板与浮层，与窗口透明度扩展同思路），全窗口径一致地透出背景，不依赖逐面板选择器；
4. 注入前自动备份原始文件（workbench.html.bak-bgimage），「彻底还原」命令可随时恢复。

修改的是 VS Code 程序文件，因此：若安装目录无写入权限（如默认装在 C:\Program Files），首次应用会弹出一次管理员（UAC）授权请求；装在用户目录（如 %LOCALAPPDATA%）或可写目录则无感完成。

VS Code 升级会覆盖 workbench.html，扩展启动时会自动检测：可写则静默恢复；需要权限时给出一条「重新应用」提示。

常见问题

• 背景图没有生效？ 首次应用后需要「重载窗口」一次（命令面板 → Developer: Reload Window）；之后改透明度 / 换图 / 移除均即时生效。
• 曾出现「Code 安装似乎损坏。请重新安装」提示？ 1.3.1 已修复：该提示源于 VS Code 启动完整性校验与扩展自动修复的时序冲突（1.3.1 起自动修复推迟到启动完成后执行，不再误报）；亦可直接在弹窗中选择「不再显示」。
• 升级 VS Code 后失效？ 状态栏显示「待应用」时，点击运行「重新应用」即可。
• 某个区域仍较暗、不透？ 正常不应再出现（整层统一透明）。如遇到请先「重新应用 + 重载窗口」；仍有问题欢迎反馈截图。
• 窗口按钮（最小化 / 最大化 / 关闭）不透明？ 应用时扩展会自动把 window.controlsStyle 切为 custom（重载窗口后生效）。若更想要 Win11 的贴靠布局悬停菜单，可手动把它改回 native。
• 不想用了？ 「移除背景图」即刻停用；卸载扩展前建议先运行「彻底还原系统文件」。
• 网络图片不显示？ 检查网址是否可访问；图片会被下载到扩展本地缓存，下载失败会在通知中提示。

兼容性

• Windows 平台（使用 PowerShell 与 Windows 的 VS Code 安装布局）。
• VS Code 1.90 及以上（同时兼容新旧两种安装目录布局；已在 1.138 实机验证）。
• 扩展根目录需可写（用于存放样式资产）；VS Code 默认安装方式下均为可写。

English

Put a background image behind the VS Code UI: a 3-step guided setup, one click to finish. The whole UI becomes uniformly translucent so the image shows through, making the code window look like a wallpaper.

UI text follows the VS Code display language (English / Simplified Chinese); no manual switch needed.

Preview (UI opacity 60% · GitHub Dark theme · blue wallpaper)

Features

• 3-step guided setup: choose an image → set UI opacity → apply. You can also just press Ctrl+Alt+I.
• UI opacity relative to the background: a single setting makes the entire UI (editor / sidebar / Chat / menus — every area) show the image through it; the lower the value, the clearer the image.
• Window buttons follow suit: the minimize / maximize / close buttons are switched to VS Code's own DOM buttons so they become translucent too (restored automatically when you remove the image; trade-off: you lose the Win11 snap-layouts hover menu).
• Changes apply instantly: changing opacity / image / removing takes effect in about 0.1 s without reloading the window; only the very first apply needs one reload.
• Image opacity and blur: control how strong the image itself is; a slight blur improves text readability.
• Multiple fill modes: cover / contain / tile / center.
• Local and web images: local files are referenced directly; web images are downloaded to a local cache and work offline afterwards.
• Lightweight: a few KB of CSS, images streamed directly (nothing embedded), so window startup is not slowed down.
• Status bar control: click Background: xx% in the status bar to change the image, nudge the opacity or re-apply.
• Self-maintaining: if a VS Code update wipes the injection, the extension detects it on startup and restores it (silently when no elevation is needed).
• Works over Remote-SSH too: it is a UI extension running on the local client, so every window shows the same background.
• Reversible at any time: removing the image needs no privileges; before uninstalling, run "Restore original files" to leave VS Code untouched.

Usage

3-step guided setup (recommended)

Command Palette (Ctrl+Shift+P) → type Background Image → pick "Background Image: Start Setup (3 steps)", or simply press Ctrl+Alt+I:

1. Choose an image: a local file (png / jpg / gif / webp / bmp / avif) or an image URL;
2. UI opacity: pick anything from 100% (image invisible) down to 15% (image clearest), or type a custom value;
3. Apply: the injection is done for you — click "Reload Window" in the notification to see the result.

Status bar

Click Background: xx% in the bottom-right status bar:

Settings

Search for "Background Image Control" in the Settings UI. Setting changes apply instantly (after the first apply).

How it works

Extensions cannot draw the VS Code UI themselves, so this extension uses the common community approach:

1. Style assets live outside the install folder: the stylesheet is generated at background-image-control-assets\bg.css next to the extension folder (user-writable, so changing settings needs no administrator privileges); images are referenced directly or served from the local cache instead of being embedded;
2. Inject one link: a <link rel="stylesheet" href="vscode-file://…/bg.css"> line is injected into workbench.html in the VS Code installation, and the product.json checksums are fixed with the official algorithm to avoid the "installation appears to be corrupt" prompt;
3. One uniform layer of transparency: the image sits at the very bottom and a single opacity rule is applied to the UI root container (all panels and overlays at once — the same idea as the window opacity extension), so the background shows through consistently without per-panel selectors;
4. The original file is backed up before injecting (workbench.html.bak-bgimage), and the "Fully restore" command brings it back at any time.

Because this modifies VS Code program files: if the installation folder is not writable (e.g. the default C:\Program Files), the first apply triggers one administrator (UAC) prompt; installs in user-writable locations (e.g. %LOCALAPPDATA%) finish silently.

A VS Code update overwrites workbench.html; the extension checks on startup and restores the injection silently when it can, or shows a "Re-apply" prompt when it needs privileges.

FAQ

• The background image is not showing. The first apply needs a window reload (Command Palette → Developer: Reload Window); afterwards changing opacity / image / removing all apply instantly.
• I saw "Your Code installation appears to be corrupt. Please reinstall." Fixed in 1.3.1: it was a timing conflict between VS Code's startup integrity check and the extension's auto-repair (since 1.3.1 the repair runs after startup completes, so the prompt no longer appears). You can also pick "Don't show again" in that dialog.
• It stopped working after a VS Code upgrade. When the status bar shows "pending apply", click Re-apply.
• Some area is still dark / opaque. It should not happen (the transparency is applied to the whole layer). If it does, run Re-apply + reload the window, and please report it with a screenshot.
• The window buttons (minimize / maximize / close) are opaque. When applying, the extension switches window.controlsStyle to custom (takes effect after a reload). If you prefer the Win11 snap-layouts hover menu, set it back to native manually.
• I want to stop using it. "Remove background image" disables it immediately; before uninstalling, run "Fully restore system files".
• A web image is not displayed. Check that the URL is reachable; images are downloaded to the extension's local cache and a failed download is reported in a notification.

Compatibility

• Windows (uses PowerShell and the Windows VS Code installation layout).
• VS Code 1.90 and later (supports both the old and the new installation layouts; verified on 1.138).
• The extension folder must be writable (style assets live next to it), which is the case for default VS Code installations.