点击按钮切换视图后启动intro.js教程的异常问题排查

问题描述 #

我有一个全局侧边栏，里面的下拉菜单可以选择intro.js制作的引导教程，「快速开始」功能正常。现在需要给下拉菜单添加对应视图的选项，点击后跳转到目标视图并启动对应教程，但只有通过这个下拉菜单触发才启动教程，从其他途径进入视图时不能自动触发。目前遇到的问题是：JS函数能切换视图，但教程只短暂显示就停止。

现有代码 #

下拉菜单HTML #

<div class="language-selector">
    <!-- Dropdown Trigger -->
    <a id="tutorial" class="dropdown-trigger sidebar-links a" href="#" data-target="tutorialDropdown">
        <span style="display: flex; align-items: center;">
            <i class="fas fa-question-circle"></i>
                {% trans "Tutorial" %}
            <i class="fas fa-caret-down"></i>
        </span>
    </a>    
    <!-- Dropdown Structure -->
    <ul id="tutorialDropdown" class="dropdown-content">
        <li>
            <button class="start-tour-button" onclick="startTourAndRedirect('quick-start', '')">
                Quick Start
            </button>
        </li>
        <li>
            <button class="start-tour-button" onclick="startTourAndRedirect('review-panel', '{% url 'validate' %}')">
                 Review Panel
            </button>
        </li>   
    </ul>
</div>

原JS函数 #

function startTourAndRedirect(tourName, url) {
    if (url !== "") {
        window.location.href = url;
    }

    let steps = [];

    if (tourName == "quick-start") {
        steps = [
            /* steps for quic-start */
        ];
    } else if (tourName == "review-panel") {
        steps = [
            /* steps for review-panel */
        ];
    } 
    console.log(steps);
    if (steps.length > 0) {
        introJs()
            .setOptions({
                steps: steps,
                showProgress: true,
                showBullets: false,
                disableInteraction: true,
            })
            .start();
    }
    else {
        console.log("No steps found");
    }
}

问题根源 #

当执行window.location.href = url跳转页面时，当前页面的所有JS代码会立即终止，所以你在跳转后启动教程的逻辑根本不会完整执行，导致教程刚启动就随着页面刷新而停止。

解决方案 #

步骤1：修改跳转逻辑，传递教程标识参数 #

把教程名称通过URL查询参数传递给目标页面，原函数只负责带参数跳转，不在当前页面启动教程：

function startTourAndRedirect(tourName, url) {
    if (url !== "") {
        // 拼接查询参数，把tourName传递到目标页面
        const targetUrl = new URL(url, window.location.origin);
        targetUrl.searchParams.set('startTour', tourName);
        window.location.href = targetUrl.toString();
        return; // 跳转后终止函数执行
    }

    // 处理无需跳转的快速开始教程
    let steps = [];
    if (tourName == "quick-start") {
        steps = [
            /* steps for quick-start */
        ];
    }
    if (steps.length > 0) {
        introJs()
            .setOptions({
                steps: steps,
                showProgress: true,
                showBullets: false,
                disableInteraction: true,
            })
            .start();
    } else {
        console.log("No steps found");
    }
}

步骤2：在目标页面添加教程启动逻辑 #

在每个需要支持教程的目标页面（比如validate视图对应的页面），添加以下JS代码，页面加载完成后检查URL参数，存在则启动对应教程：

// 页面加载完成后执行
document.addEventListener('DOMContentLoaded', function() {
    // 获取URL中的startTour参数
    const urlParams = new URLSearchParams(window.location.search);
    const tourName = urlParams.get('startTour');
    
    if (!tourName) return; // 无参数则不执行
    
    // 移除URL中的参数，避免刷新页面再次触发教程
    urlParams.delete('startTour');
    window.history.replaceState({}, document.title, window.location.pathname + urlParams.toString());

    // 加载对应教程步骤
    let steps = [];
    if (tourName === "review-panel") {
        steps = [
            /* steps for review-panel */
        ];
    }

    if (steps.length > 0) {
        introJs()
            .setOptions({
                steps: steps,
                showProgress: true,
                showBullets: false,
                disableInteraction: true,
            })
            .start();
    } else {
        console.log("No steps found for this tour");
    }
});

关键说明 #

• 通过URL参数传递教程标识，确保只有从下拉菜单跳转时才会携带该参数，其他途径进入视图不会触发教程
• 启动教程后立即移除URL参数，避免用户刷新页面时重复触发教程
• 目标页面的教程逻辑只在页面加载时检查一次参数，完全符合需求

内容的提问来源于stack exchange，提问作者suribe06