当前位置：首页 > news >正文

Sphinx 文档图片点击放大

news 2025/7/4 19:12:56

文章目录

- 问题描述
- 解决方案
- - 步骤 1：创建 JavaScript 文件
  - 步骤 2：编写 JavaScript 代码
  - 步骤 3：更新 Sphinx 配置
- 高级定制
- - 为所有图片添加点击功能
  - 添加缩放控制
- 总结

在使用 Sphinx 生成技术文档时，我们经常需要在文档中嵌入截图和示意图。然而，Sphinx 默认的图片显示方式有一个明显的缺点： 图片无法点击放大。这意味着当图片中包含重要的细节信息时，用户无法清晰地查看。

一个简单而有效的解决方案，通过添加少量的 JavaScript 代码，为 Sphinx 文档中的所有图片添加点击放大功能，大大提升用户体验。

问题描述

当我们在 Markdown 文件中添加图片时，生成的 HTML 中的图片标签通常如下所示：

<img alt="image-20250502161335681" src="../../../_static/images/blog/test_some.png">

默认情况下，用户只能看到页面中嵌入的图片，无法通过点击查看原始大小的图片。

解决方案

我们可以通过添加一个简单的 JavaScript 文件，为所有图片添加点击放大功能，无需更改现有的 Markdown 文件或 Sphinx 配置。

步骤 1：创建 JavaScript 文件

首先，在 Sphinx 项目的 _static/js 目录下创建一个名为 image-click.js 的文件（如果目录不存在，需要先创建）：

mkdir -p _static/js
touch _static/js/image-click.js

步骤 2：编写 JavaScript 代码

将下面的代码添加到 image-click.js 文件中：

document.addEventListener('DOMContentLoaded', function() {// 为所有图片添加点击事件var images = document.querySelectorAll('img[alt^="image-"]');images.forEach(function(img) {img.style.cursor = 'pointer';img.addEventListener('click', function() {// 创建模态框var modal = document.createElement('div');modal.style.position = 'fixed';modal.style.top = '0';modal.style.left = '0';modal.style.width = '100%';modal.style.height = '100%';modal.style.backgroundColor = 'rgba(0,0,0,0.8)';modal.style.display = 'flex';modal.style.alignItems = 'center';modal.style.justifyContent = 'center';modal.style.zIndex = '1000';// 获取绝对路径var imgSrc = img.getAttribute('src');// 如果是相对路径,需要处理一下if(imgSrc.startsWith('../') || imgSrc.startsWith('./')) {// 基于当前页面URL构建绝对路径var basePath = window.location.href.substring(0, window.location.href.lastIndexOf('/') + 1);imgSrc = new URL(imgSrc, basePath).href;}// 创建大图var fullImg = document.createElement('img');fullImg.src = imgSrc;fullImg.style.maxWidth = '90%';fullImg.style.maxHeight = '90%';fullImg.style.objectFit = 'contain';// 点击关闭modal.onclick = function() {document.body.removeChild(modal);};modal.appendChild(fullImg);document.body.appendChild(modal);});});
});

代码解释：

选择所有 alt 属性以 “image-” 开头的图片（指定文档中的图片命名）
为每个图片添加点击事件
点击时创建一个全屏模态框，显示原始图片
处理相对路径，确保图片在模态框中正确显示
允许用户通过点击模态框任意位置关闭它

步骤 3：更新 Sphinx 配置

在 conf.py 文件中添加以下配置，确保 Sphinx 加载这个 JavaScript 文件：

# 添加静态目录路径
html_static_path = ['_static']# 添加 JavaScript 文件
html_js_files = ['js/image-click.js',
]

高级定制

如果想要进一步定制这个功能，可以考虑以下改进：

为所有图片添加点击功能

如果想为文档中的所有图片（而不仅仅是 alt 属性以 “image-” 开头的图片）添加点击功能，只需修改选择器：

var images = document.querySelectorAll('.document img');

添加缩放控制

可以在模态框中添加缩放按钮，允许用户进一步放大或缩小图片：

// 创建缩放控制按钮
var zoomControls = document.createElement('div');
zoomControls.style.position = 'absolute';
zoomControls.style.bottom = '20px';
zoomControls.style.left = '50%';
zoomControls.style.transform = 'translateX(-50%)';
zoomControls.style.zIndex = '1001';var zoomIn = document.createElement('button');
zoomIn.textContent = '+';
zoomIn.style.margin = '0 10px';
zoomIn.style.padding = '5px 10px';
zoomIn.onclick = function(e) {e.stopPropagation();var currentScale = parseFloat(fullImg.style.transform.replace('scale(', '').replace(')', '') || 1);fullImg.style.transform = 'scale(' + (currentScale + 0.1) + ')';
};var zoomOut = document.createElement('button');
zoomOut.textContent = '-';
zoomOut.style.margin = '0 10px';
zoomOut.style.padding = '5px 10px';
zoomOut.onclick = function(e) {e.stopPropagation();var currentScale = parseFloat(fullImg.style.transform.replace('scale(', '').replace(')', '') || 1);fullImg.style.transform = 'scale(' + Math.max(0.1, currentScale - 0.1) + ')';
};zoomControls.appendChild(zoomOut);
zoomControls.appendChild(zoomIn);
modal.appendChild(zoomControls);