HTML Truncator 技术文档

HTML Truncator 是一个用于正确截断 HTML 字符串的 Ruby gem，它基于 Nokogiri 库构建。本文将详细介绍如何安装、使用该 gem，并解释其 API 的使用方法。

1. 安装指南

使用 RubyGems 安装

你可以通过 RubyGems 直接安装 HTML Truncator：

gem install html_truncator

使用 Bundler 安装

如果你使用 Bundler 管理项目依赖，可以在 Gemfile 中添加以下内容：

gem "html_truncator", "~>0.2"

然后运行 bundle install 安装 gem。

2. 项目的使用说明

安装完成后，你可以在代码中使用 HTML Truncator 来截断 HTML 字符串。以下是一个简单的示例：

require "html_truncator"
HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3)
# => "<p>Lorem ipsum dolor…</p>"

主要方法

HTML_Truncator 类只有一个主要方法 truncate，它接受三个参数：

1. HTML 字符串：需要截断的 HTML 格式字符串。
2. 保留的单词数：实际保留的单词数，标签和属性不计入。
3. 选项：可选参数，用于自定义截断行为，例如省略号。

属性

HTML_Truncator 类还提供了以下属性，用于自定义截断行为：

• ellipsable_tags：可以包含省略号的标签列表（默认包括 p, ol, ul, li, div, header, article, nav, section, footer, aside, dd, dt, dl）。
• self_closing_tags：空标签列表（默认包括 br, hr, img, param, embed）。
• punctuation_chars：在省略号前移除的标点符号列表（默认包括 ,, ., :, ;, !, ?）。

3. 项目 API 使用文档

truncate 方法

truncate 方法用于截断 HTML 字符串，并返回截断后的结果。以下是其参数和选项的详细说明：

• HTML 字符串：需要截断的 HTML 格式字符串。
• 保留的单词数：实际保留的单词数，标签和属性不计入。
• 选项：可选参数，支持以下选项：
  • :length_in_chars：如果设置为 true，则按字符数而不是单词数进行截断。
  • :ellipsis：自定义省略号，默认为 …。
  • 其他选项可以通过 HTML_Truncator::DEFAULT_OPTIONS 查看。

示例

以下是一些使用 truncate 方法的示例：

# 按单词数截断
HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3)
# => "<p>Lorem ipsum dolor…</p>"

# 按字符数截断
HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 12, :length_in_chars => true)
# => "<p>Lorem ipsum…</p>"

# 自定义省略号
HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3, :ellipsis => " (truncated)")
# => "<p>Lorem ipsum dolor (truncated)</p>"

html_truncated? 方法

html_truncated? 方法用于检查字符串是否被截断：

HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3).html_truncated?
# => true

4. 项目安装方式

通过 RubyGems 安装

gem install html_truncator

通过 Bundler 安装

在 Gemfile 中添加：

gem "html_truncator", "~>0.2"

然后运行：

bundle install

总结

HTML Truncator 是一个简单易用的工具，能够帮助你正确地截断 HTML 字符串，同时保持 HTML 结构的完整性。通过本文的指南，你可以轻松安装并使用该 gem，并根据需要自定义截断行为。