@18f/private-eye 中文文档教程

Question

Private Eye

一个 JavaScript 插件，用于警告用户有关私人页面的链接。 在具有您指定为私有的任何 URL 的任何链接旁边放置一个 :lock: 图标，并给出警告消息。

在 18F，这用于包含内部内容链接的公共站点，例如私人 GitHub 存储库或 Google 文档。 与其编写两个版本来编辑这些链接，不如让我们发布新内容并向员工和外部读者发出警告。

Installation

兼容现代浏览器（IE 9+）。 没有依赖性。

Script

Private Eye 可以作为普通脚本包含在您的页面上，公开一个 PrivateEye 全局。

<script src="private-eye.js" defer></script>

CommonJS

Private Eye 支持 CommonJS，因此兼容 Browserify、WebPack< /a> 等。

1. 安装模块。

   npm install --save @18f/private-eye
   

2. 包含在您的应用程序中：

   var PrivateEye = require('private-eye');
   

Basic Usage

要开始使用 Private Eye，请使用对象初始化 PrivateEye 包含一个带有要匹配的 URL 列表的 ignoreUrls 属性。

document.addEventListener('DOMContentLoaded', function() {
  new PrivateEye({
    // list of URLs to match as substrings – can be full URLs, hostnames, etc.
    ignoreUrls: [
      'http://so.me/private/url',
      'anoth.er',
      // ...
    ]
  });
}, false );

Advanced Usage

Private Eye 支持链接的自定义消息。 下面的示例提供了自定义 URL 消息的不同方法 一般到颗粒状。

Reconfiguring the default message

给链接的默认消息可以在所有私有 url 中配置 传递名为 defaultMessage 的选项。 该属性被添加到 对象传递到 PrivateEye( { /*...*/ } );。

document.addEventListener('DOMContentLoaded', function() {
  PrivateEye({
    // Update the default message to a custom `string`.
    defaultMessage: "This link is secured, please ensure you have the proper credentials to access it."
    ignoreUrls: [
      'http://so.me/private/url',
      'anoth.er',
      // ...
    ]
  });
}, false );

在上面的示例中，所有与 ignoreURLs 匹配的 URL 都将具有自定义的 defaultMessage 作为用户将鼠标悬停在链接上时看到的消息。

Configuring custom messages for individual URLs

也支持基于每个 URL 的自定义消息传递。 这是由 使用 url 和 message 属性传递 ignoreUrls 数组中的对象 分别匹配要匹配的 URL 和要显示的消息。

document.addEventListener('DOMContentLoaded', function() {
  PrivateEye({
    ignoreUrls: [
      'http://so.me/private/url',
      // Custom messages for individual URLs are passed in as an object.
      {
        url: 'anoth.er',
        message: 'This is another link that may not be accessible to you without the proper credentials',
      },
      // ...
    ]
  });
}, false );

在上面的示例中，http://so.me/private/url 的 URL 匹配将具有 基本默认消息。 anoth.er 的 URL 匹配项将具有特定的 仅那些个人比赛的自定义消息。

Using HTML to configure granular individual custom messages.

每个元素都支持自定义消息传递。 如果 title 属性是 在任何匹配的 anchor 上找到，默认或自定义消息永远不会设置 锚点。 原始的 title 属性保持不变。 这可以是 用于在更精细的级别上自定义单个 anchor 元素。

// Set up for the plugin is the same as "Basic Usage" above.
document.addEventListener('DOMContentLoaded', function() {
  PrivateEye({
    // list of URLs to match as substrings – can be full URLs, hostnames, etc.
    ignoreUrls: [
      'http://so.me/private/url',
      'anoth.er',
      // ...
    ]
  });
}, false );

<!-- Base, or configured, default messaging for this link. -->
<a href="http://so.me/private/url">A private URL</a>
<!-- Granluar custom message for only this specific element. -->
<a href="http://so.me/private/url" title="This link is still private and you may not have access to it.">Another private URL</a>

在上面的示例中，自定义消息设置为 title 属性 匹配的 anchor 元素之一。 第一个没有 title 的匹配项 属性将具有基本默认消息。 带有 title 的第二个匹配项 属性将具有在 title 中找到的自定义消息。 这个用例是 如果您的 HTML 页面已经包含有价值的信息，则特别有用 私有 URL，或者如果您想配置消息而不需要 使用 JavaScript。

Target specfic section of the page

要仅将私有图标锁添加到页面的特定部分，请通过 wrapper 选项传入 CSS 选择器。

document.addEventListener('DOMContentLoaded', function() {
  PrivateEye({
    // using the wrapper propety on the opts object - here, limiting to links under a tag with a "private" class"
    wrapper: '.private',
    // list of URLs to match as substrings – can be full URLs, hostnames, etc.
    ignoreUrls: [
      'http://so.me/private/url',
      'anoth.er',
      // ...
    ]
  });
}, false );

<div class="private">
    <a href="http://so.me/private/url">A private URL that will get a lock</a>
</div>
<a href="http://so.me/private/url">A private URL that will not get a lock</a>

Developing

要开始开发，只需克隆此存储库即可。 Private Eye 没有依赖关系，也没有构建过程。 Private Eye 的所有代码都位于 private-eye.js 中。

本项目使用jest 进行测试。 首先，运行 npm install 来安装 jest。 可以使用 npm test 或 npm test:watch 运行测试，以便在文件更改时重新运行测试。