TidSearch

TidSearch

为静态博客添加搜索功能的 JavaScript 库。A JavaScript library to add search functionality to static blogs.

TidSearch

为静态博客添加搜索功能的 JavaScript 库。

Click here for English version.

安装

下载源代码

克隆这个 git 仓库,并使用如下命令生成 dist 目录。

npm install
npm run build

然后将 dist 目录中的 TidSearch.js 复制到您的网站目录下,即可通过<script>标签将其引入。

使用 CDN

您可以使用 jsdelivr 提供的 CDN 在网页上引入本项目。

<script src="https://cdn.jsdelivr.net/npm/tidsearch@latest/dist/TidSearch.min.js"></script>

快速入门

创建 search.json

在您的网站中添加一个 search.json 文件,其内容是一个数组,数组中的每一个元素都是包含一个页面的信息的对象,需要含有字段 titleurlcategory(可选)、tags(可选)、date(可选)、content(可选),其值分别为该页面的标题、地址、类别、标签、发布日期、内容。

对于使用 Jekyll 构建的博客,可以使用下面的模板来快速生成search.json

---
layout: null
---
[
{% for post in site.posts %}
    {
        "title"    : "{{ post.title | escape }}",
        "url"      : "{{ site.baseurl }}{{ post.url }}",
        "category" : "{{ post.category }}",
        "tags"     : "{{ post.tags | join: ', ' }}",
        "date"     : "{{ post.date | date: '%Y年%m月%d日' }}",
        "content"  : {{ post.content | strip_html | normalize_whitespace | jsonify }}
    } {% unless forloop.last %},{% endunless %}
{% endfor %}
]

注意上述模板中的 content 项的内容并没有添加双引号,jsonify 会自动添加双引号。

如果您不需要模板中的某一项,删除对应行即可。

在页面上添加所需的 DOM 元素

使用 TidSearch 需要在页面中添加一个<div>或者<ul>等 DOM 元素来容纳搜索结果。

<input id="searchInput"/>
<div id="searchResultContainer"></div>

另外,您还可以添加一个<input>,以支持即时搜索。

初始化 TidSearch 组件

使用如下的 JavaScript 代码来初始化 TidSearch

const sch = new TidSearch({
    input: document.getElementById('searchInput'),
    output: document.getElementById('searchResultContainer'),
    // 或者这样写
    // input: '#searchInput',
    // output: '#searchResultContainer',
    json: '/search.json',
});

output 参数是搜索结果的盛放容器,可以是一个 DOM 元素或者 CSS 选择器(字符串)。注意,如果传入 CSS 选择器,需要保证在运行上述代码时,页面中对应的元素已经加载完成

json 参数是您的 search.json 的地址,或者您可以提前加载该 JSON 文件,并将解析后的结果传入。

开始使用

TidSearch 对象初始化完成之后,您可以通过其 search 方法发起一次搜索。搜索的结果会呈现在预先准备的容器元素中。

如果您在初始化时指定了 input 项,那么当其值变化时,会自动触发 search 方法。

关于浏览器兼容性

TidSearch 依赖于 Promise。默认的配置文件使用了babel来兼容旧版浏览器(Chrome59 和 IE11),但是没有包含对于 Promise 的 polyfill,如果您需要兼容不支持 Promise 的浏览器,请自行引入 polyfill。具体方法请参阅相关文章。

配置项

关于 TidSearch 对象在初始化时的其他参数,以及具体用法,请参阅 Wiki 页面

开源许可证

本项目使用 MPLv2 开源许可证,您需要注意以下几点:

  • 您需要公布您对本项目源码修改部分的代码。
  • 您需要对修改之处提供说明文档。