Rails 7 Footnotes 技术文档

本文档将详细介绍如何安装、使用以及配置 Rails 7 Footnotes，帮助您更好地理解和使用这个项目。

1. 安装指南

要安装 Rails 7 Footnotes，请按照以下步骤操作：

1. 将以下代码添加到您的 Gemfile 文件中：

   bundle add rails-footnotes
   

2. 运行以下命令来安装依赖项：

   bundle install
   

3. 使用以下命令生成初始化文件：

   bin/rails generate rails_footnotes:install
   

   这将在默认配置和示例的基础上创建一个初始化文件。

2. 项目使用说明

Rails 7 Footnotes 会在您的应用程序中显示脚注，以便于调试，例如会话、请求参数、cookies、过滤器链、路由、查询等。

配置

您可以通过编辑 config/initializers/rails-footnotes.rb 文件来自定义脚注的行为。

例如，您可以在脚注评估之前和之后运行代码块：

Footnotes.setup do |config|
  config.before do |controller, filter|
    filter.notes = (controller.class.name =~ /Message/ && controller.action_name == 'index' ? [:assigns] : [])
  end

  config.after do |controller, filter|
    filter.notes |= [:params] if controller.class.name =~ /Profile/ && controller.action_name == 'edit'
  end
end

编辑器链接

默认情况下，文件链接会设置为在 TextMate 中打开，但您可以使用任何具有 URL 协议的编辑器。以下是一些其他编辑器的示例：

MacVim

在 config/initializers/rails-footnotes.rb 文件中，设置：

f.prefix = 'mvim://open?url=file://%s&line=%d&column=%d'

Sublime Text 3

安装 subl 后，使用：

f.prefix = 'subl://open?url=file://%s&line=%d&column=%d'

在 Docker、Vagrant 或其他虚拟机中使用

如果您的应用程序在容器或虚拟机中运行，您会发现编辑链接无法工作，因为路径指向虚拟机的目录而不是本地目录。为了解决这个问题，您可以使用 lambda 表达式来修改路径。

例如：

f.prefix = ->(*args) do
  filename = args[0].sub '/docker', '/Users/name/projects/myproject'
  "subl://open?url=file://#{filename}&line=#{args[1]}&column=#{args[2]}"
end

脚注显示选项

默认情况下，脚注会附加在页面底部，并带有默认的样式表。如果您想更改它们的位置，可以在 HTML 中定义一个带有 id 为 "footnotes_holder" 的 div，或者通过关闭脚注样式表来定义自己的样式表：

f.no_style = true

您还可以将脚注锁定在窗口顶部，默认隐藏，并通过页面右上角的小按钮访问：

f.lock_top_right = true

要设置脚注的字体大小：

f.font_size = '13px'

另一个选项是允许同时打开多个脚注：

f.multiple_notes = true

最后，您可以控制要显示哪些脚注。默认显示的脚注包括：

f.notes = [:session, :cookies, :params, :filters, :routes, :env, :queries, :log]

将 f.notes = [] 将不显示任何可用的脚注，但仍然会包含支持 CSS 和 JavaScript。要完全禁用页面上的所有 Rails-footnotes 内容，请在请求中包含 params[:footnotes] = 'false'。

3. 项目 API 使用文档

Rails 7 Footnotes 提供了灵活的 API 用于创建自定义脚注。以下是如何创建自定义脚注的步骤：

1. 创建一个 Footnotes::Notes::YourExampleNote 类。
2. 实现必要的方