rails_autolink 技术文档

1. 安装指南

rails_autolink 是一个从 Rails 中提取的 auto_link 方法的 gem，旨在为那些从 Rails 3.1 及以下版本迁移的用户提供支持。以下是安装步骤：

1.1 在 Gemfile 中添加依赖

首先，在你的 Rails 项目的 Gemfile 中添加以下行：

gem 'rails_autolink'

1.2 安装依赖

在终端中执行以下命令来安装 gem：

$ bundle install

安装完成后，rails_autolink 就可以在你的项目中使用了。

2. 项目的使用说明

rails_autolink 的主要功能是将文本中的 URL 和电子邮件地址自动转换为可点击的链接。以下是几种常见的使用场景：

2.1 基本用法

require 'rails_autolink'

auto_link("Go to http://www.rubyonrails.org and say hello to [e-mail]")
# => "Go to <a href=\"http://www.rubyonrails.org\">http://www.rubyonrails.org</a> and
#     say hello to <a href=\"mailto:[e-mail]\">[e-mail]</a>"

2.2 仅转换 URL 为链接

auto_link("Visit http://www.loudthinking.com/ or e-mail [e-mail]", :link => :urls)
# => "Visit <a href=\"http://www.loudthinking.com/\">http://www.loudthinking.com/</a>
#     or e-mail [e-mail]"

2.3 仅转换电子邮件地址为链接

auto_link("Visit http://www.loudthinking.com/ or e-mail [e-mail]", :link => :email_addresses)
# => "Visit http://www.loudthinking.com/ or e-mail <a href=\"mailto:[e-mail]\">[e-mail]</a>"

2.4 生成链接时不进行 HTML 标签的清理

默认情况下，auto_link 会清理 HTML 标签以防止恶意代码。你可以通过设置 :sanitize 选项为 false 来禁用此功能。

auto_link("Go to http://www.rubyonrails.org <script>alert('Script!')</script>", :sanitize => false)
# => "Go to <a href=\"http://www.rubyonrails.org\">http://www.rubyonrails.org</a> <script>alert('Script!')</script>"

2.5 自定义链接并缩短文本

你还可以通过传递一个块来自定义链接的生成方式，例如缩短链接文本：

post_body = "Welcome to my new blog at http://www.myblog.com/.  Please e-mail me at [e-mail]."
auto_link(post_body, :html => { :target => '_blank' }) do |text|
  truncate(text, :length => 15)
end
# => "Welcome to my new blog at <a href=\"http://www.myblog.com/\" target=\"_blank\">http://www.m...</a>."

3. 项目 API 使用文档

rails_autolink 提供了一个主要的 API 方法 auto_link，以下是该方法的详细说明：

3.1 auto_link 方法

auto_link(text, options = {}, &block)

参数说明

• text: 需要处理的文本字符串。
• options: 可选的配置项，支持以下选项：
  • :link: 指定要转换的内容类型，可选值为 :urls 或 :email_addresses。
  • :sanitize: 是否清理 HTML 标签，默认为 true。
  • :html: 自定义生成的 HTML 标签属性，例如 { :target => '_blank' }。
• &block: 可选的块，用于自定义链接文本的生成方式。

返回值

返回一个包含转换后链接的 HTML 安全字符串。

4. 项目安装方式

rails_autolink 的安装方式非常简单，只需在 Gemfile 中添加依赖并执行 bundle install 即可。具体步骤如下：

1. 在 Gemfile 中添加 gem 'rails_autolink'。
2. 在终端中执行 bundle install。

安装完成后，你就可以在项目中使用 rails_autolink 提供的功能了。

总结

rails_autolink 是一个简单但功能强大的 gem，能够帮助你将文本中的 URL 和电子邮件地址自动转换为可点击的链接。通过本文档，你应该能够轻松地安装、配置和使用 rails_autolink。如果你有任何问题或需要进一步的帮助，请参考项目的官方文档或社区支持。