Readability.js

Readability.js 是 Firefox 阅读器视图所使用的可读性库的独立版本。

安装

Readability 可在 npm 上获取：

npm install @mozilla/readability

然后你可以通过 require() 引入它，或者对于基于网页的项目，从你的网页加载 Readability.js 脚本。

基本用法

要解析文档，你必须从 DOM 文档对象创建一个新的 Readability 对象，然后调用 parse() 方法。这里有一个例子：

var article = new Readability(document).parse();

如果你在网页浏览器中使用 Readability，你可能能够使用来自其他地方的 document 引用（例如通过 XMLHttpRequest 获取的，或在你有权访问的同源 <iframe> 中等）。在 Node.js 中，你可以使用外部 DOM 库。

API 参考

`new Readability(document, options)`

options 对象接受多个属性，全部为可选：

debug（布尔值，默认 false）：是否启用日志记录。
maxElemsToParse（数字，默认 0 即无限制）：要解析的最大元素数量。
nbTopCandidates（数字，默认 5）：在分析候选者之间竞争程度时要考虑的顶级候选者数量。
charThreshold（数字，默认 500）：文章必须具有的最小字符数才能返回结果。
classesToPreserve（数组）：当 keepClasses 选项设置为 false 时，要在 HTML 元素上保留的类集合。
keepClasses（布尔值，默认 false）：是否保留 HTML 元素上的所有类。设置为 false 时，只保留 classesToPreserve 数组中指定的类。
disableJSONLD（布尔值，默认 false）：在提取页面元数据时，Readability 优先考虑 JSON-LD 格式指定的 Schema.org 字段。将此选项设置为 true 可跳过 JSON-LD 解析。
serializer（函数，默认 el => el.innerHTML）控制 parse() 方法返回的 content 属性如何从根 DOM 元素生成。如果你计划进一步处理 content，将 serializer 指定为恒等函数（el => el）以获取 DOM 元素而不是字符串可能会有用。
allowedVideoRegex（正则表达式，默认 undefined）：匹配应允许包含在文章内容中的视频 URL 的正则表达式。如果为 undefined，则应用默认正则表达式。
linkDensityModifier（数字，默认 0）：在阴暗度检查期间添加到基本链接密度阈值的数字。这可用于惩罚高链接密度的节点或反之亦然。

`parse()`

返回一个包含以下属性的对象：

title：文章标题；
content：处理后的文章内容的 HTML 字符串；
textContent：文章的文本内容，所有 HTML 标签已移除；
length：文章长度，以字符为单位；
excerpt：文章描述，或内容的简短摘录；
byline：作者元数据；
dir：内容方向；
siteName：网站名称；
lang：内容语言；
publishedTime：发布时间；

parse() 方法通过修改 DOM 工作。这会删除网页中的一些元素，可能会产生不希望的结果。你可以通过将 document 对象的克隆传递给 Readability 构造函数来避免这种情况：

var documentClone = document.cloneNode(true);
var article = new Readability(documentClone).parse();

`isProbablyReaderable(document, options)`

这是一种快速而简单的方法，用于判断给定文档的内容是否可能适合用 Readability 处理。它可能会产生误报和漏报。它存在的原因是为了避免在时间敏感的过程（如加载和向用户展示网页）中因 Readability 核心的复杂逻辑而拖慢速度。欢迎改进其逻辑（同时不降低其性能）。

options 对象接受多个属性，全部为可选：

minContentLength（数字，默认 140）：用于判断文档是否可读的最小节点内容长度；
minScore（数字，默认 20）：用于确定文档是否可读的最小累积"分数"；
visibilityChecker（函数，默认 isNodeVisible）：用于确定节点是否可见的函数；

该函数返回一个布尔值，表示我们是否怀疑 Readability.parse() 将成功返回文章对象。这里有一个例子：

/*
    只有在我们怀疑 `parse()` 方法会产生有意义的结果时
    才实例化 Readability。
*/
if (isProbablyReaderable(document)) {
    let article = new Readability(document).parse();
}

Node.js 用法

由于 Node.js 没有自带的 DOM 实现，我们依赖像 jsdom 这样的外部库。这里有一个使用 jsdom 获取 DOM 文档对象的例子：

var { Readability } = require('@mozilla/readability');
var { JSDOM } = require('jsdom');
var doc = new JSDOM("<body>看看这只猫：<img src='https://raw.githubusercontent.com/mozilla/readability/main/cat.jpg'></body>", {
  url: "https://www.example.com/the-page-i-got-the-source-from"
});
let reader = new Readability(doc.window.document);
let article = reader.parse();

记得在 JSDOM 构造函数中传递页面的 URI 作为 url 选项（如上例所示），这样 Readability 就可以将图片、超链接等的相对 URL 转换为它们的绝对对应项。

jsdom 能够运行 HTML 中包含的脚本并获取远程资源。出于安全原因，这些功能默认是禁用的，我们强烈建议你保持禁用状态。

安全性

如果你要将 Readability 用于不受信任的输入（无论是 HTML 还是 DOM 形式），我们强烈建议你使用像 DOMPurify 这样的净化库，以避免在使用 Readability 输出时发生脚本注入。我们还建议使用 CSP 来为结果内容的行为添加进一步的深度防御限制。Firefox 的阅读器模式集成本身就使用了这两种技术。从输入中净化不安全内容不是我们作为 Readability 本身的目标 - 有其他好的净化库可以使用，请使用它们！

贡献

请查看我们的 Contributing 文档。

许可证

Copyright (c) 2010 Arc90 Inc

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.