本文将分享一个简单而有效的解决方案，通过添加少量的 JavaScript 代码，为 Sphinx 文档中的所有图片添加点击放大功能，大大提升用户体验。
问题描述
当我们在 Markdown 文件中添加图片时，生成的 HTML 中的图片标签通常如下所示：
1
| <img alt="image-20250502161335681" src="../../../_static/images/blog/test_some.png">
|
默认情况下，用户只能看到页面中嵌入的图片，无法通过点击查看原始大小的图片。
解决方案
我们可以通过添加一个简单的 JavaScript 文件，为所有图片添加点击放大功能，无需更改现有的 Markdown 文件或 Sphinx 配置。
步骤 1：创建 JavaScript 文件
首先，在 Sphinx 项目的 _static/js 目录下创建一个名为 image-click.js 的文件（如果目录不存在，需要先创建）：
1
2
| mkdir -p _static/js
touch _static/js/image-click.js
|
步骤 2：编写 JavaScript 代码
将下面的代码添加到 image-click.js 文件中：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
| 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('./')) {
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 文件：
1
2
3
4
5
6
7
|
html_static_path = ['_static']
html_js_files = [
'js/image-click.js',
]
|
高级定制
如果想要进一步定制这个功能，可以考虑以下改进：
为所有图片添加点击功能
如果想为文档中的所有图片（而不仅仅是 alt 属性以 “image-“ 开头的图片）添加点击功能，只需修改选择器：
1
| var images = document.querySelectorAll('.document img');
|
添加缩放控制
可以在模态框中添加缩放按钮，允许用户进一步放大或缩小图片：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
|
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);
|
总结
通过添加少量的 JavaScript 代码，我们成功为 Sphinx 文档中的图片添加了点击放大功能，大大提升了用户体验。这个解决方案的优点包括：
- 易于实现：只需添加一个 JavaScript 文件
- 无需修改现有内容：不需要更改已有的 Markdown 文件
- 轻量级：不依赖任何外部库
- 可定制：可以根据需要轻松扩展功能
无论是在编写技术文档、API 文档还是教程，这个简单的改进都能让图片更加实用，让用户能够方便地查看图片中的所有细节。