飞书文档一级目录折叠助手(优化版)

功能简介

这是专为飞书文档（Feishu Wiki）设计的目录管理增强脚本，核心解决长文档一级目录展开过多、浏览不便的问题，支持自动折叠+快捷键控制，适配飞书SPA动态加载特性，兼顾操作效率与视觉反馈。

• 自动折叠：页面加载完成后自动折叠所有一级目录，支持20秒内动态监听目录加载，适配飞书异步渲染逻辑
• 快捷键控制：Ctrl+Alt+-（减号）一键切换所有一级目录的展开/收起状态
• 视觉反馈：顶部悬浮提示框显示目录状态（收起/展开），2秒自动消失，颜色区分状态（蓝色=收起，红色=展开）
• 智能重试：折叠/展开操作后验证状态，失败自动标记并提示，避免操作无效
• 防重复处理：通过目录文本内容去重，避免重复点击同一目录项
• ⚠️ 已知问题：上滑侧边目录栏会触发自动折叠逻辑，暂未找到最优解决方案

功能特点

核心目录控制

• 🎯 精准定位：仅针对一级目录（indent-level-1.heading-1）生效，不影响二级/多级目录
• 🔄 状态切换：自动检测当前目录状态，快捷键一键在“全部收起”和“全部展开”间切换
• 🕒 异步适配：最长20秒等待目录加载，连续3次检测目录数量稳定后执行折叠，解决SPA加载延迟问题
• ✅ 操作验证：点击折叠/展开后验证状态，控制台输出详细执行日志，便于排查问题
• 🚫 去重处理：通过目录文本内容生成唯一标识，避免重复处理同一目录项

交互体验优化

• 🖥️ 悬浮提示：固定位置的状态提示框，淡入淡出动画，不遮挡核心内容
• ⌨️ 快捷键设计：Ctrl+Alt+- 组合键，避免与飞书原生快捷键冲突
• 📝 详细日志：控制台输出每个目录项的处理状态（成功/失败/重试），方便调试
• 🔍 DOM监听：MutationObserver监听目录节点变化，动态加载的目录也能自动处理

兼容性

• 🌐 域名适配：支持所有飞书文档域名（https://*.feishu.cn/wiki/*）
• 🧩 无侵入性：仅添加样式和事件监听，不修改飞书文档原生DOM结构和逻辑
• 🕦 延迟执行：document-idle 时机运行，避免阻塞页面加载

安装方法

1. 确保浏览器已安装用户脚本管理器扩展：

   • Tampermonkey (推荐)
   • Violentmonkey
   • 脚本猫 (国产，中文友好)

2. 点击下方链接安装脚本：
   

3. 或者手动创建新脚本，复制上述完整代码并保存

适用页面

• https://*.feishu.cn/wiki/*

操作说明

注意：

1. 快捷键触发时确保焦点不在输入框内，避免无效
2. ⚠️ 已知问题：上滑侧边目录栏会触发自动折叠，临时解决方案可手动按快捷键恢复展开状态

技术细节

核心配置

// 核心配置参数
const maxWaitTime = 20000; // 最大等待目录加载时间(ms)
const checkInterval = 500; // 目录数量检测间隔(ms)
const stableThreshold = 3; // 目录数量稳定次数阈值
const statusShowTime = 2000; // 状态提示显示时长(ms)
const shortcutKey = '-'; // 快捷键（Ctrl+Alt+减号）

核心功能实现

// 1. 折叠所有一级目录核心逻辑
function collapseAll() {
    const items = document.querySelectorAll('li.catalogue__list-item.indent-level-1.heading-1.collapsible');
    let processedItems = new Set(); // 去重集合
    let hasUnprocessed = false;

    items.forEach(item => {
        const collapseSpan = item.querySelector('span.catalogue__item-collapse:not(.collapsed)');
        const textSpan = item.querySelector('span.text');
        if (collapseSpan && textSpan) {
            const itemId = textSpan.textContent;
            if (!processedItems.has(itemId)) {
                processedItems.add(itemId);
                collapseSpan.click(); // 执行折叠
                // 验证折叠状态
                setTimeout(() => {
                    if (!item.querySelector('span.catalogue__item-collapse.collapsed')) {
                        hasUnprocessed = true; // 标记失败项
                    }
                }, 100);
            }
        }
    });
    return !hasUnprocessed;
}

// 2. 快捷键监听核心
document.addEventListener('keydown', function (e) {
    if (e.ctrlKey && e.altKey && e.key === '-') {
        toggleAll(); // 切换目录状态
        e.preventDefault();
        e.stopPropagation();
    }
}, true);

// 3. DOM变化监听核心
const observer = new MutationObserver(mutations => {
    mutations.forEach(mutation => {
        if (mutation.addedNodes.length) {
            // 检测新加载的一级目录并折叠
            const hasNewItems = Array.from(mutation.addedNodes).some(node => {
                return node.nodeType === 1 && node.matches('li.catalogue__list-item.indent-level-1.heading-1.collapsible');
            });
            if (hasNewItems && !initCollapse) {
                setTimeout(collapseAll, 300);
            }
        }
    });
});

执行流程

1. 页面空闲时初始化脚本，创建状态提示框
2. 3秒后开始检测一级目录，最长等待20秒
3. 连续3次检测目录数量稳定后，执行自动折叠
4. 监听DOM变化，动态加载的目录自动折叠
5. 监听快捷键Ctrl+Alt+-，一键切换目录状态
6. 操作后显示状态提示，控制台输出详细日志

已知问题与临时解决方案

常见问题

Q: 脚本没有自动折叠目录怎么办？

A:

1. 检查控制台（F12）是否有“达到最大等待时间”提示
2. 确认飞书文档有一级目录（heading-1）
3. 手动按Ctrl+Alt+-快捷键触发折叠
4. 刷新页面重试（飞书SPA可能加载异常）

Q: 状态提示框遮挡内容怎么办？

A:

1. 修改脚本中#feishu-collapsor-status的样式，调整top/left值：

   top: 120px; /* 向下调整 */
   right: 20px; /* 改为右侧显示 */
   

2. 保存修改后刷新飞书文档页面

Q: 可以自定义快捷键吗？

A:

1. 找到脚本中快捷键监听代码：

   if (e.ctrlKey && e.altKey && e.key === '-')
   

2. 将e.key === '-'改为想要的按键（如e.key === '['）
3. 建议选择不与飞书原生快捷键冲突的组合

更新日志

v1.1

• ✨ 新增状态提示：悬浮提示框显示目录状态，颜色区分收起/展开
• 🕒 优化等待逻辑：延长最大等待时间至20秒，增加目录数量稳定检测
• ✅ 操作验证：折叠/展开后验证状态，标记失败项并提示
• 🚫 去重处理：避免重复处理同一目录项
• 🐞 BUG修复：解决动态加载目录不折叠的问题

v1.0

• 🎉 初始版本：实现一级目录自动折叠和快捷键切换功能
• ⚡ SPA适配：基本支持飞书文档动态加载
• ⌨️ 快捷键控制：Ctrl+Alt+- 切换目录状态

免责声明

本脚本仅供学习交流使用，请勿用于商业用途。脚本仅模拟人工点击操作，未修改飞书文档核心功能，使用脚本产生的一切后果由使用者自行承担。

反馈与支持

如果您在使用过程中遇到问题或有改进建议，请通过以下方式反馈：

• 在脚本评论区留言
• 提交Issue到脚本仓库
• 反馈飞书文档页面结构变化导致的脚本失效问题

温馨提示：

1. 飞书文档页面结构可能更新，如脚本失效请关注最新版本
2. 已知的“上滑触发折叠”问题待优化，如有更好的解决思路可反馈
3. 使用过程中如遇问题，可按F12查看控制台日志定位问题