Sphinx 文档图片点击放大-CSDN博客

本文链接：https://blog.csdn.net/qq_31362767/article/details/147673798

文章目录

在使用 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);