文件夹网页化预览工具 - 使用说明

📖 脚本简介

文件夹网页化预览工具是一个基于Python的本地Web应用，能够将文件夹结构以美观的树形界面展示在浏览器中。该工具提供了强大的文件浏览、预览和管理功能，支持多种文件类型的在线预览，让您轻松管理和查看本地文件。

✨ 主要功能

🌳 树形结构展示

层级显示：以清晰的树形结构展示文件夹层级关系
图标识别：为不同文件类型自动分配对应图标
展开控制：支持任意层级的展开和折叠操作
深度限制：可设置最大展开深度，避免过深目录结构影响性能

🔍 智能搜索功能

实时搜索：输入关键词即时过滤文件和文件夹
路径匹配：支持按文件名或完整路径进行搜索
高亮显示：搜索结果自动高亮标记
搜索状态保持：搜索时自动展开相关路径

👁️ 多类型文件预览

文本文件：支持多种编程语言和文档格式的语法高亮预览
图片文件：支持JPG、PNG、GIF、BMP、SVG等格式的图片预览
视频文件：支持MP4、AVI、MOV、WebM等格式的在线播放
音频文件：支持MP3、WAV、FLAC、AAC等格式的在线播放
CSV表格：智能解析CSV文件并以表格形式展示，支持大文件预览

⭐ 收藏管理功能

一键收藏：将重要文件或文件夹添加到收藏列表
快速访问：通过收藏下拉菜单快速访问常用文件
持久化存储：收藏列表自动保存到本地存储
收藏状态显示：已收藏项目在界面上有明显标识

🚀 便捷操作功能

文件打开：一键使用系统默认程序打开文件
位置定位：在系统文件管理器中快速定位文件
路径复制：一键复制文件完整路径到剪贴板
内容复制：文本文件预览时支持一键复制全部内容

🎛️ 参数配置说明

必选参数

选择文件夹：选择要分析和展示的目标文件夹路径

可选参数

显示隐藏文件（默认：关闭）
- 开启后将显示以点(.)开头的隐藏文件和文件夹
- 建议在需要查看系统配置文件时开启
服务器端口（默认：12888，范围：1024-65535）
- Web服务器监听的端口号
- 如果默认端口被占用，可修改为其他可用端口
自动打开浏览器（默认：开启）
- 启动服务后是否自动在默认浏览器中打开页面
- 关闭后需要手动访问提示的URL地址
最大深度限制（默认：10层，范围：1-20层）
- 文件夹遍历的最大深度限制
- 防止过深的目录结构导致性能问题
预览文件大小限制（默认：100MB，范围：1-1024MB）
- 可预览的单个文件最大大小限制
- 超过限制的文件将无法预览，但仍可进行其他操作

🖥️ 界面功能详解

左侧面板 - 文件树浏览

搜索框：实时搜索文件和文件夹
展开深度控制：通过+/-按钮或直接输入调节展开层数
- 0：全部折叠
- 1：仅展开第一层
- 2：展开前两层
- 以此类推...
收藏按钮：显示收藏数量并提供快速访问下拉菜单
文件树区域：显示文件夹的完整层级结构

右侧面板 - 详情和预览

信息标签页：显示选中文件/文件夹的详细信息和操作按钮
预览标签页：提供多种文件类型的在线预览功能

顶部导航栏

标题显示：当前分析的文件夹路径
全局刷新：重新扫描文件夹结构并刷新界面

📝 使用方法

基本使用流程

启动脚本：在kuai客户端中配置参数并启动脚本
选择文件夹：指定要分析的目标文件夹路径
配置选项：根据需要调整显示选项和服务器设置
运行脚本：脚本会自动启动Web服务并打开浏览器
浏览文件：在Web界面中浏览、搜索和预览文件

常用操作指南

浏览文件：点击文件夹前的箭头展开/折叠，点击文件名查看详情
搜索文件：在搜索框中输入关键词进行实时搜索
预览文件：选中文件后切换到"预览"标签页查看内容
管理收藏：使用收藏按钮添加/移除收藏，通过收藏菜单快速访问
调节深度：使用深度控制按钮调整树形结构的展开层数

🎯 支持的文件类型

文本文件

编程代码：.py, .js, .html, .css, .java, .cpp, .c, .cs, .php, .rb, .go, .rs等
配置文件：.json, .xml, .yaml, .yml, .ini, .cfg, .conf等
文档文件：.txt, .md, .log, .sql等

图片文件

常用格式：.jpg, .jpeg, .png, .gif, .bmp, .webp等
矢量图形：.svg, .ico等

音视频文件

视频格式：.mp4, .avi, .mov, .wmv, .mkv, .flv, .webm等
音频格式：.mp3, .wav, .flac, .aac, .ogg, .wma等

数据文件

表格数据：.csv（自动解析分隔符，支持中文编码）

⚠️ 注意事项

系统要求

Python版本：需要Python 3.11.0或更高版本
操作系统：主要针对Windows 11优化，其他系统也可使用
浏览器支持：推荐使用现代浏览器（Chrome、Firefox、Edge等）

使用限制

文件大小：超过设定大小限制的文件无法预览
目录深度：过深的目录结构可能影响加载性能
权限问题：某些系统文件夹可能因权限不足而无法访问

性能优化建议

合理设置深度限制：避免一次性展开过多层级
适当调整预览大小限制：根据系统性能调整文件预览限制
及时关闭服务：使用完毕后可通过Ctrl+C停止服务

🔧 技术特性

核心技术

HTTP服务器：基于Python标准库的http.server模块
响应式设计：支持桌面和移动设备的自适应布局
实时交互：前端JavaScript实现的动态交互功能
文件编码检测：自动检测文本文件编码格式

安全特性

本地服务：仅在本机启动Web服务，不对外网开放
路径验证：防止路径遍历攻击，确保只能访问指定目录
文件类型检查：严格的文件类型验证，防止恶意文件执行

用户体验

流畅动画：界面元素的平滑过渡和动画效果
快速响应：优化的搜索和渲染性能
直观操作：符合用户习惯的交互设计
状态记忆：自动保存用户的操作偏好和收藏列表

🆘 常见问题

Q: 无法访问Web界面怎么办？

A: 检查防火墙设置，确保指定端口未被占用，或尝试更换端口号。

Q: 为什么收藏的文件不见了？

A: 可能清理了浏览器缓存，或者服务端口号变动了。

Q: 文件预览显示乱码怎么解决？

A: 脚本会自动检测文件编码，如仍有问题，可能是不支持的编码格式。

Q: 为什么某些文件无法预览？

A: 检查文件大小是否超出限制，或文件类型是否在支持列表中。

版本信息：kuai格式 1.0
适用系统：Windows 11（其他系统也可使用）
Python版本：3.11.0+

文件夹网页化预览