History.sys.mjs

用于管理历史记录的异步 API。

结构

该 API 使用 PageInfo 和 VisitInfo 对象，定义如下。

一个 PageInfo 对象是任何包含以下属性的 子集 的对象

  • guid (string) - 页面的全局唯一 ID

  • url (URL, href 或 nsIURI) - 页面的完整 URI。请注意，作为参数传递的 PageInfo 值可能包含 nsIURI 或 string 值作为属性 url，但此模块返回的 PageInfo 对象始终包含 URL 值

  • title (string) - 与页面关联的标题（如果有）

  • description (string) - 页面的描述（如果有）

  • previewImageURL (URL, nsIURI 或 string) - 页面的预览图像 URL（如果有）

  • frecency (number) - 页面的频次（如果有）。请注意，此属性不能用于更改页面的实际频次分数，只能用于检索它。换句话说，作为参数传递给此 API 函数的任何“frecency”字段都将被忽略

  • visits (Array<VisitInfo>) - 此页面的所有访问记录（如果有）

  • annotations (Map) - 包含此页面注释的键/值对的映射（如果有）

一个 VisitInfo 对象是任何包含以下属性的子集的对象

  • date (Date) - 访问发生的时间

  • transition (number) - 用户如何到达页面

  • referrer (URL, nsIURI 或 string) - 此访问的引用 URI。请注意，作为参数传递的 VisitInfo 可能包含 nsIURI 或 string 值作为属性 referrer，但此模块返回的 VisitInfo 对象始终包含 URL 值

主要功能

  • 获取。获取一个页面的可用信息。您需要指定一个唯一的标识符（Guid）或 url（url、nsIURI 或 href）作为字符串。获取步骤返回一个 promise，当获取完成且找到页面时，该 promise 将成功解析。当 Guid 或 url 类型不符合预期，或者如果它是一个字符串，url/Guid 无效时，则抛出错误。

  • 从数据库中删除页面/访问记录。您需要指定要删除的目标页面/访问记录对象。返回一个 promise，该 promise 解析为 true 布尔值。当“pages”类型不符合预期或提供的字符串/过滤器没有数据时，抛出错误。

  • 确定页面是否已被访问。连接到数据库并查询指定页面是否已被访问。返回一个 promise，如果页面已被访问，则解析为 true 布尔值，否则解析为假值。如果提供的 guid 或 uri 无效，则抛出错误。

  • 清除所有历史记录。返回一个 promise，当操作完成时解析。

  • 更新页面的信息。目前，它支持更新页面的描述、预览图像 URL 和注释，其他任何字段都将被忽略（如果目标页面尚未存储在数据库中，则此函数将忽略更新。History.fetch 可用于检查页面及其元信息是否存在）。如果提供了一个属性“description”，则更新页面的描述。空字符串或 null 将清除数据库中的现有值，并且描述长度不得超过 DB_DESCRIPTION_LENGTH_MAX。如果提供了一个属性“siteName”，则更新页面的站点名称，并且“previewImageURL”更新页面的预览图像 URL。对于描述，应用与空字符串清除现有数据和最大长度相同的规则，站点名称的最大长度为 DB_SITENAME_LENGTH_MAX，预览图像的最大长度为 DB_URL_LENGTH_MAX。属性“annotations”更新注释。它应该是一个映射，包含键/值对，如果值为假，则注释将被删除。键必须是字符串，值应该是布尔值、数字或字符串。更新信息返回一个 promise，如果操作不成功则拒绝，或者在更新完成后解析。当“pageInfo”类型不符合预期、url/guid 无效或既没有“description”也没有“previewImageURL”时，抛出错误。

每个成功操作都通过 PlacesObservers 观察者 接口进行通知。

包含每个方法的实际 javadoc 和描述的完整文件 - History.sys.mjs