本篇博客参考Akilar糖果屋的文章!详情参考原文

DIY外挂标签的简单写法与应用

https://akilar.top/posts/e2bf861f/

标签外挂

  • 标签外挂实质其实就是简化HTML的写法,把大片重复的内容交给Hexo编译,我们只需要在外挂标签内提供必要的参数即可
  • 外挂标签的编译函数属于Hexo内部函数,所以应该放在scripts文件夹下。千万不要放在source/js/目录下,用外部函数引用方法
  • 本帖将标签函数脚本放在[Blogroot]\themes\butterfly\scripts\tag\目录下。以下如无另外声明,一律都是放在这个目录了

API详解

1
2
hexo.extend.tag.register('name', function(args, content){
}, options);
  • name:表示外挂标签的名字,为字符串,为了避免和之后会提到的参数处理函数名混淆,建议用''包裹。

  • args:外挂标签传入的参数,可以是一个包含多个参数的字符串,之后再用分割函数处理成数组。

  • content: 外挂标签涵盖的内容。

  • options: 标签函数的参数,有endsasync

    • ends:决定是否使用结束标签,此选项默认为false。如果为true,则需要添加形似endname的结束标签。注意,只有ends设为true时,content参数才有效。适用于需要在外挂标签内嵌套外挂标签或者markdown语法的情况。
    • async:决定是否开启非同步渲染模式,此选项默认为false。它用于决定是否开启在hexo s预览时对外挂标签进行同步渲染。如设为false则开启同步渲染。所以建议尽量不要去改它。
  • endsfalse的情况,此时不存在content参数,所以没必要写了

1
2
3
//标签函数结构
hexo.extend.tag.register('name', function(args){
});
1
2
//对应的外挂标签写法
{% name args %}
  • endstrue的情况,此时content参数有效
1
2
3
//标签函数结构
hexo.extend.tag.register('name', function(args, content){
},{ends:true});
1
2
//对应的外挂标签写法
{% name args %}content{% endname %}

简单示例

查看代码测试

  • endsfalse的情况
1
2
3
hexo.extend.tag.register('kbd', function(args) {
return `<kbd>${args.join(' ')}</kbd>`;
});
  • 则标签函数写法为
1
{% kbd args %}
  • 会被编译成
1
<kbd>args</kbd>

查看代码测试

  • endstrue的情况:
1
2
3
hexo.extend.tag.register('tip',function tip (args, content) {
return `<div class="tip ${args.join(' ')}">${hexo.render.renderSync({ text: content, engine: 'markdown' })}</div>`
}, { ends: true })
  • 这个函数也可以写成如下形式,这样更符合开发体验:
1
2
3
4
5
6
//参数处理函数
function tip (args, content) {
return `<div class="tip ${args.join(' ')}">${hexo.render.renderSync({ text: content, engine: 'markdown' })}</div>`
}
//标签注册函数
hexo.extend.tag.register('tip',tip, { ends: true })
  • 则标签函数写法为
1
{% tip args %}content{% endtip %}
  • 会被编译成
1
<div class="tip args">content</div>
  • 此处的args可以是一个字符串,例如args='warning fa fa-icon'
  • ${hexo.render.renderSync({ text: content, engine: 'markdown' })}表示使用markdown语法来编译处理content的内容。
  • 所以content可以是任何markdown语法兼容的内容,乃至其他外挂标签
  • 更多辅助函数内容请参阅 Hexo 开发文档 - 辅助函数:https://hexo.io/zh-cn/docs/helpers

初级应用

  • 可以看出整个标签函数分为参数处理函数标签注册函数
1
2
3
4
5
6
7
8
9
//参数处理函数
function poem (args, content) {
args = args.join(' ').split(',')
let p0 = args[0]
let p1 = args[1]?args[1]:''
return `<div class='poem'><div class='poem-title'>${p0}</div><div class='poem-author'>${p1}</div>${hexo.render.renderSync({ text: content, engine: 'markdown' })}</div>`
}
//标签注册函数
hexo.extend.tag.register('poem',poem,{ ends: true });
  • args = args.join(' ').split(',') 表示对字符串 args 做分割处理,使用, 作为分割标记,然后强制转换成数组
1
2
3
4
5
6
7
//原本
args='a,ab,abc,abcd'
//运行args = args.join(' ').split(',')后
args=[a,ab,abc,abcd]
//此时
args[0]='a' args[1]='ab' ......
//以此类推,要注意数组是从0开始计数的
  • let p1 = args[1]?args[1]:'' 是 javascript 的三元运算符
  • 语法为:条件表达式?表达式 1: 表达式 2。
    • 说明:问号前面的位置是判断的条件,判断结果为布尔型,为 true 时调用表达式 1,为 false 时调用表达式 2。
    • 使用这个方式,我们可以配置对应参数的默认值。因为分割好的数组 args 的实质是个动态数组,所以未取到的值应该为空 null,如果转化成布尔型的话,就是 false

具体案例

  • 比如我们要把上标式标签写成外挂标签样式。首先确保引入了CSS,可以查看我的博文:http://xiaoliblog.cn/page/butterfly04.html
  • 首先确定最终的 HTML 结构,我们需要参考它来编写参数处理函数
1
2
3
<div class="tip [参数] [动画]">
<p>文本内容</p>
</div>
1
2
3
<div class="tip faa-horizontal animated">
<p>为简单的一句话提供的简便写法。</p>
</div>
  • 其次需要确定我们需要的外挂标签样式。因为有内容需要content,因此采用 ends: true 的编写方式且适用markdwon语法。然后传入样式参数动画参数
1
2
3
{% textTips style animate %}

{% endtextTips %}
1
2
3
4
5
6
7
8
9
10
11
[参数]
不填默认为 info
warning 黄色叹号
success 绿色打钩
error 红色禁止
[动画]
参考动画特效
faa-horizontal animated
faa-flash animated
faa-horizontal animated-hover
faa-flash animated-hover
  • 然后就可以根据这些信息编写参数处理函数。在script/tags下新建Mytags.js即可,因为是内部函数。hexo编译时会自动读取的
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// 参数处理函数
function textTips (args,content){
// 适用逗号分隔参数字符串,得到多个参数
args = args.join(' ').split(',')
// 使用三元运算设置动画默认值
let p0 = args[0]?args[0]:'info'
// 使用三元运算设置动画默认值
let p1 = args[1]?args[1]:''
//用style="..."的内联样式写法添加特定参数
return `<div class="tip ${p0} ${p1}">
<p>${hexo.render.renderSync({ text: content, engine: 'markdown' })}</p>
</div>`
}

// 标签注册函数
hexo.extend.tag.register('textTips', textTips, { ends: true })
  • 写完后,测试一下传入样式和动画
1
2
3
{% textTips warning faa-horizontal animated%}
测试文本
{% endtextTips %}
  • 效果如下

测试文本