过滤器

过滤器用于修改某些指定的数据。Hexo 按顺序将数据传递给过滤器，然后过滤器依次修改数据。这个概念是从 WordPress 借用的。

¥A filter is used to modify some specified data. Hexo passes data to filters in sequence and the filters then modify the data one after the other. This concept was borrowed from WordPress.

概要

¥Synopsis

hexo.extend.filter.register(type, function() {
  // User configuration
  const { config } = this;
  if (config.external_link.enable) // do something...

  // Theme configuration
  const { config: themeCfg } = this.theme;
  if (themeCfg.fancybox) // do something...

}, priority);

你可以定义 priority。较低的 priority 表示将首先执行。默认的 priority 是 10。我们建议使用用户可配置的优先级值，用户可以在配置中指定该值，例如 hexo.config.your_plugin.priority。

¥You can define the priority. Lower priority means that it will be executed first. The default priority is 10. We recommend using user-configurable priority value that user can specify in the config, e.g. hexo.config.your_plugin.priority.

执行过滤器

¥Execute Filters

hexo.extend.filter.exec(type, data, options);
hexo.extend.filter.execSync(type, data, options);

选项	描述
context	上下文
args	参数。这必须是一个数组。

传递给每个过滤器的第一个参数是 data。传递到下一个过滤器的 data 可以通过返回新值来修改。如果没有返回任何内容，则数据保持不变。你甚至可以使用 args 在过滤器中指定其他参数。例如：

¥The first argument passed into each filter is data. The data passed into the next filter can be modified by returning a new value. If nothing is returned, the data remains unmodified. You can even use args to specify other arguments in filters. For example:

hexo.extend.filter.register("test", function (data, arg1, arg2) {
  // data === 'some data'
  // arg1 === 'foo'
  // arg2 === 'bar'

  return "something";
});

hexo.extend.filter.register("test", function (data, arg1, arg2) {
  // data === 'something'
});

hexo.extend.filter.exec("test", "some data", {
  args: ["foo", "bar"],
});

你还可以使用以下方法执行过滤器：

¥You can also use the following methods to execute filters:

hexo.execFilter(type, data, options);
hexo.execFilterSync(type, data, options);

取消注册过滤器

¥Unregister Filters

hexo.extend.filter.unregister(type, filter);

示例

¥Example

// Unregister a filter which is registered with named function

const filterFn = (data) => {
  data = "something";
  return data;
};
hexo.extend.filter.register("example", filterFn);

hexo.extend.filter.unregister("example", filterFn);

// Unregister a filter which is registered with commonjs module

hexo.extend.filter.register("example", require("path/to/filter"));

hexo.extend.filter.unregister("example", require("path/to/filter"));

过滤器列表

¥Filter List

以下是 Hexo 使用的过滤器列表。

¥Here is a list of filters used by Hexo.

before_post_render

在渲染帖子之前执行。执行步骤请参考 渲染后。

¥Executed before a post is rendered. Refer to post rendering to learn the execution steps.

例如，将标题转换为小写：

¥For example, to transform the title to lower case:

hexo.extend.filter.register("before_post_render", function (data) {
  data.title = data.title.toLowerCase();
  return data;
});

after_post_render

在帖子渲染后执行。执行步骤请参考 渲染后。

¥Executed after a post is rendered. Refer to post rendering to learn the execution steps.

例如，将 @username 替换为 Twitter 个人资料的链接：

¥For example, to replace @username with a link to a Twitter profile:

hexo.extend.filter.register("after_post_render", function (data) {
  data.content = data.content.replace(
    /@(\d+)/,
    '<a href="http://twitter.com/$1">#$1</a>',
  );
  return data;
});

before_exit

在 Hexo 即将退出之前执行 - 这将在调用 hexo.exit 后立即运行。

¥Executed before Hexo is about to exit – this will run right after hexo.exit is called.

hexo.extend.filter.register("before_exit", function () {
  // ...
});

before_generate

生成开始前执行。

¥Executed before generation begins.

hexo.extend.filter.register("before_generate", function () {
  // ...
});

after_generate

生成完成后执行。

¥Executed after generation finishes.

hexo.extend.filter.register("after_generate", function () {
  // ...
});

template_locals

修改模板中的 局部变量。

¥Modify local variables in templates.

例如，将当前时间添加到模板的局部变量：

¥For example, to add the current time to the local variables of templates:

hexo.extend.filter.register("template_locals", function (locals) {
  locals.now = Date.now();
  return locals;
});

after_init

在 Hexo 初始化后执行 - 这将在 hexo.init 完成后立即运行。

¥Executed after Hexo is initialized – this will run right after hexo.init completes.

hexo.extend.filter.register("after_init", function () {
  // ...
});

new_post_path

在创建帖子时执行以确定新帖子的路径。

¥Executed when creating a post to determine the path of new posts.

hexo.extend.filter.register("new_post_path", function (data, replace) {
  // ...
});

post_permalink

用于确定帖子的永久链接。

¥Used to determine the permalink of posts.

hexo.extend.filter.register("post_permalink", function (data) {
  // ...
});

after_render

渲染完成后执行。你可以查看 rendering 了解更多信息。

¥Executed after rendering finishes. You can see rendering for more info.

after_clean

在使用 hexo clean 命令删除生成的文件和缓存后执行。

¥Executed after generated files and cache are removed with hexo clean command.

hexo.extend.filter.register("after_clean", function () {
  // remove some other temporary files
});

server_middleware

将中间件添加到服务器。app 是 Connect 实例。

¥Add middleware to the server. app is a Connect instance.

例如，将 X-Powered-By: Hexo 添加到响应标头：

¥For example, to add X-Powered-By: Hexo to the response header:

hexo.extend.filter.register("server_middleware", function (app) {
  app.use(function (req, res, next) {
    res.setHeader("X-Powered-By", "Hexo");
    next();
  });
});