Read the Docs 项目中的悬浮菜单功能详解

Read the Docs 项目中的悬浮菜单功能详解

readthedocs.org The source code that powers readthedocs.org 项目地址: https://gitcode.com/gh_mirrors/re/readthedocs.org

什么是悬浮菜单

悬浮菜单是 Read the Docs 文档平台提供的一项便捷功能，它以浮动按钮的形式出现在文档页面的角落位置（默认右下角）。这个菜单整合了多个实用功能，让用户无需离开当前页面就能快速访问各种文档操作。

悬浮菜单的核心功能

悬浮菜单主要包含以下几个实用模块：

1. 版本切换器：展示项目所有可用版本，方便用户在不同版本间快速切换
2. 语言切换器：当文档支持多语言时，可在此切换不同语言版本
3. 离线文档下载：提供当前文档版本的HTML、PDF等格式下载选项
4. 项目控制台链接：快速跳转到项目的管理控制台
5. 文档搜索：内置的服务器端全文搜索功能

悬浮菜单的配置选项

版本排序方式

在项目设置中，管理员可以自定义版本显示的排序方式：

• SemVer排序（默认）：采用Read the Docs定制实现的语义化版本排序
• Python包排序：按照Python包管理系统的版本排序规则
• CalVer排序：基于日历日期的版本排序方式
• 字母顺序：简单的字母表顺序排列
• 自定义模式：支持自定义版本排序规则

管理员还可以设置是否让"latest"和"stable"这两个特殊版本显示在列表最前面。

菜单位置调整

悬浮菜单支持多种显示位置配置：

1. 默认位置：遵循文档主题的设定，若无则使用Read the Docs默认位置（右下角）
2. 左下角：将菜单固定在浏览器窗口左下角
3. 右下角：将菜单固定在浏览器窗口右下角
4. 左上角：将菜单固定在浏览器窗口左上角
5. 右上角：将菜单固定在浏览器窗口右上角

对于主题开发者，可以通过在HTML中直接定义readthedocs-flyout组件的位置属性来预设菜单位置。

高级定制与集成

对于需要深度定制的开发者，Read the Docs提供了通过JavaScript CustomEvent获取悬浮菜单数据的接口。这意味着开发者可以：

1. 获取完整的菜单数据（包括版本、语言、下载选项等）
2. 将这些数据集成到自己的文档主题导航中
3. 创建完全自定义的菜单样式和交互方式

虽然目前这个API的响应格式尚未正式文档化，但开发者可以通过检查返回的JSON数据结构来了解其组织形式。未来Read the Docs会正式文档化这个API并保证其向后兼容性。

最佳实践建议

1. 对于普通用户：直接使用默认悬浮菜单即可获得完整功能体验
2. 对于项目管理员：根据项目特点配置合适的版本排序方式和菜单位置
3. 对于主题开发者：考虑将菜单数据集成到主题导航中，提供更原生的用户体验
4. 对于高级开发者：可以通过监听CustomEvent实现完全自定义的菜单交互逻辑

悬浮菜单是Read the Docs提供的一项强大而灵活的功能，既开箱即用又支持深度定制，能够满足不同层次用户的需求。

readthedocs.org The source code that powers readthedocs.org 项目地址: https://gitcode.com/gh_mirrors/re/readthedocs.org