HoverImage Preview

效果预览 · 功能特性

VS Code 扩展：在编辑器中鼠标悬浮即可预览图片，支持完整 URL、变量拼接、模板字符串，以及 React 组件预览。

效果预览

模板字符串悬浮预览

悬浮在 `${CDN}/path/image.png` 等模板字符串上，自动解析变量并展示图片：

组件悬浮预览

为 React 组件配置预览图后，悬浮在 JSX 标签上即可查看组件效果，无需启动项目：

功能特性

• 标准 URL 预览 — 悬浮在完整图片链接上即可预览
• 模板字符串 — 识别 `${CDN}/path/image.png` 格式
• 变量拼接 — 识别 CDN + "/path/image.png" 格式
• 组件预览 — 为 React 组件配置预览图，悬浮在 JSX 标签上即可查看
• 高度可配置 — 自定义变量映射、预览宽度、支持格式、外部配置文件

安装

从源码克隆安装（推荐）

git clone https://github.com/hottaiger/hoverimage-preview.git ~/.vscode/extensions/hoverimage-preview

克隆完成后重启 VS Code 即可生效。若扩展目录已存在旧版本，先删除再重新克隆。

平台	VS Code 扩展目录
macOS	~/.vscode/extensions/
Windows	%USERPROFILE%\.vscode\extensions\
Linux	~/.vscode/extensions/

从 VS Code Marketplace 安装

1. 打开 VS Code
2. 按 Cmd+Shift+X / Ctrl+Shift+X 打开扩展面板
3. 搜索 HoverImage Preview 并安装

或直接访问：Marketplace 页面

安装到其他 IDE

本扩展基于 VS Code Extension API，兼容 Cursor、Windsurf 等 VS Code 系 IDE。由于 Marketplace 版本可能未及时同步，推荐同样使用源码克隆方式安装。

各 IDE 扩展目录如下：

IDE	macOS	Windows	Linux
VS Code	~/.vscode/extensions/	%USERPROFILE%\.vscode\extensions\	~/.vscode/extensions/
Cursor	~/.cursor/extensions/	%USERPROFILE%\.cursor\extensions\	~/.cursor/extensions/
Windsurf	~/.codeium/windsurf/extensions/	%USERPROFILE%\.codeium\windsurf\extensions\	~/.codeium/windsurf/extensions/

让 AI 帮你安装

将以下提示词复制到 Cursor、Copilot Chat 等 AI 助手中，替换 {IDE} 和 {扩展目录} 后发送即可：

请帮我安装 HoverImage Preview 扩展：

1. 克隆仓库到扩展目录：
   git clone https://github.com/hottaiger/hoverimage-preview.git {扩展目录}/hoverimage-preview

2. 如果 {扩展目录}/hoverimage-preview 已存在，先删除旧目录再重新克隆

3. 完成后告诉我需要重启 {IDE}

我的 IDE 是 Cursor，扩展目录是 ~/.cursor/extensions/

示例（Cursor 用户可直接使用）：

请帮我安装 HoverImage Preview 扩展：

1. 克隆仓库：git clone https://github.com/hottaiger/hoverimage-preview.git ~/.cursor/extensions/hoverimage-preview
2. 若目录已存在则先删除再克隆
3. 完成后提醒我重启 Cursor

开发调试

1. 用 VS Code 打开本项目
2. 按 F5 启动扩展开发主机
3. 在新窗口中测试插件

快速开始

1. 安装扩展
2. 在设置中配置变量映射（若项目使用 CDN 常量）：

{
  "hoverImagePreview.variables": {
    "CDN": "https://cdn.example.com",
    "ASSETS": "https://assets.example.com"
  }
}

3. 打开包含图片地址的代码文件，将鼠标悬浮在 URL 或变量表达式上即可预览

配置说明

在 VS Code 设置（Cmd+, / Ctrl+,）中搜索 hoverImagePreview。

基本配置

配置项	类型	默认值	说明
hoverImagePreview.width	string	"230"	预览图片宽度（像素）
hoverImagePreview.extensions	array	["jpeg", "jpg", "png", "gif", "webp"]	支持的图片格式

变量映射

将代码中的常量名映射到实际域名或 CDN 地址：

{
  "hoverImagePreview.variables": {
    "CDN": "https://cdn.example.com",
    "IMAGE_HOST": "https://images.example.com"
  }
}

组件预览

支持内联配置和外部配置文件两种方式。

内联配置 — 在 hoverImagePreview.components 中设置：

{
  "hoverImagePreview.components": {
    "HeroBanner": "https://cdn.example.com/previews/hero-banner.png",
    "ProductCard": "https://cdn.example.com/previews/product-card.png"
  }
}

外部配置文件（推荐） — 适合团队共享、组件较多的项目。

1. 在项目中创建配置文件，例如 .vscode/hover-image-preview.json：

{
  "HeroBanner": "https://cdn.example.com/previews/hero-banner.png",
  "ProductCard": "https://cdn.example.com/previews/product-card.png"
}

也支持带 components 字段的格式：

{
  "components": {
    "HeroBanner": "https://cdn.example.com/previews/hero-banner.png"
  }
}

2. 在设置中指定路径：

{
  "hoverImagePreview.configPath": ".vscode/hover-image-preview.json"
}

外部配置会覆盖内联配置中的同名组件。文件修改后会自动重新加载。

使用示例

标准 URL

const imageUrl = "https://cdn.example.com/assets/banner.png";
// 鼠标悬浮在 URL 上即可预览

模板字符串

const CDN = "https://cdn.example.com";

export const images = {
  headerBg: `${CDN}/assets/header-bg.png`,
  footerLogo: `${CDN}/assets/logo.png`,
};

变量拼接

const headerBg = CDN + "/assets/header-bg.png";

React 组件预览

配置组件预览图后，悬浮在 JSX 标签上即可查看：

import { HeroBanner } from "./components";

function App() {
  return (
    <div>
      <HeroBanner />
      {/* 悬浮在 HeroBanner 标签上即可预览 */}
    </div>
  );
}

工作原理

扩展通过 Hover Provider 监听鼠标悬浮，按以下优先级匹配：

1. 组件标签 — 需在配置中映射组件名与预览图
2. 完整 URL — https://...
3. 模板字符串 — `${VAR}/path`
4. 变量拼接 — VAR + "/path"

匹配成功后，根据变量映射拼接完整 URL，在悬浮框中渲染图片预览。

许可证

ISC License

更新日志

v1.1.0

• 新增 React 组件预览
• 支持外部配置文件
• 优化匹配逻辑与默认配置

v1.0.0

• 初始版本
• 支持 URL、模板字符串、变量拼接预览