变量和方法 | Baklib开发者中心

本教程介绍 Liquid 模板开发中的变量和方法使用。

Object（对象）

类型名称	解释
site	当前cms站点信息
page	页面的详细信息
tag	标签
author	作者
comment	评论
plugins.feedback	用户反馈插件

site（当前站点）

属性/方法	类型	解释	示例
name	string	站点名称	开心农场
favicon_url	string	站点图标	<url>
time_zone	string	站点时区	Beijiang
language	string	站点语言	zh-CN \| en <html lang="{{ site.language }}">
url	string	网站地址	https://help.baklib.com/
password_login_enabled	boolean	是否开启密码登录	true \| false
sso_login_enabled	boolean	是否开启 SSO 登录	true \| false
baklib_login_enabled	boolean	是否开启 Baklib 登录	true \| false
nav_tree_path		树状导航地址	/-/nav_tree
pages	page[]	通过 PATH 查找页面, 返回query关系 . 支持 created_at/edited_at/visit_count 排序	site.pages['/'] => 获取首页 site.pages['/blogs']
comments	comment[]	通过 id 查找页面, 返回query关系 . 支持 created_at/published_replies_count 排序	site.pages['7zkpc0'] 获取对应评论
pages_in_list	page[]	获取全站的页面列表	site.pages_in_list
tags	tag[]	站点所有标签列表，返回query关系 *-可选项，通过settings.tags自定义	tags['tag_name'] => 获取指定名称的标签 site.tags（见下面 Tags 介绍）
plugins	json	插件配置信息	见 plugins.feedback
settings	json	站点模板定义的变量信息
theme_colors_css	string	当前站点的主题颜色	--theme-color-primary: 3 169 244

page（页面）

属性/方法	类型	使用方法	返回值	说明
id	string	page.id	9g5hkd	页面的ID唯一标识
slug	string	page.slug	guide	页面path/url的唯一标识
link_text	string	page.link_text	操作教程	页面标题
path	string	page.path	/guide	页面相对路径
url	string	page.url	http://abc.example.com/guide	页面绝对路径
visits_count	integer	page.visits_count	0	页面访问量
edited_at	datetime	page.edited_at		<待开放>
published_at	datetime	page.published_at	2024-03-21 19:23:59 +0800	{ page.published_at \| time_ago }} {{ page.published_at \| date: "%Y-%m-%d" }}
seo_title	string	page.seo_title		SEO 标题
seo_keywords	string	page.seo_keywords		SEO 关键词
seo_description	string	page.seo_description		SEO 描述
settings	json{}	page.settings	{"title"=>"操作教程", "description"=>nil, "tags"=>[]}	page.settings.title page.settings.tags
author	author	page.author		本页面作者 page.author.name page.author.avatar_url
parent	page	page.parent		本页面的父页面
children	page[]	page.children		子页面集合
children_in_list	page[]	page.children_in_list		子页面集合，排除不在列表中显示的。
children_in_nav_menu	page[]	page.children_in_nav_menu		子页面集合，排除不在菜单中显示的。
pages	page[]	page.pages		子孙页面集合
pages_in_list	page[]	page.pages_in_list		子孙页面集合，排除不在列表中显示的。
prev_page	page	page.prev_page		上一个页面
next_page	page	page.next_page		下一个页面
comments	comment[]	page.comments		页面评论集合
breadcrumb	json	page.breadcrumb	{"link_text"=>"首页", "path"=>"/"}{"link_text"=>"操作教程", "path"=>"/guide"}	页面面包屑
visitor_posted_feedback	boolean	page.visitor_posted_feedback	false	是否已提交反馈
last_feedback_emoji	string	page.last_feedback_emoji		反馈的项
versions	page[]	page.versions		版本页面集合

Comment（页面）

属性/方法	类型	使用方法	返回值	说明
id	string	comment.id	9g5hkd	评论的ID唯一标识
body	string	comment.body	guide	评论的内容
created_at	datetime	comment.created_at		评论创建时间 { page.created_at \| time_ago }} {{ page.created_at \| date: "%Y-%m-%d" }}
author	author	comment.author		评论作者
reply_to_user	author	comment.reply_to_user		回复内容作者
target	page	comment.target		评论主题
parent	comment	comment.parent		回复的评论
root	comment	comment.root		评论所属一级评论
replies	comment[]	comment.replies		评论回复集合

version（版本）

返回当前 page 页面的前 50 个版本信息。

属性/方法	类型	解释	示例
name	string	版本名称	v1.0
url	string	版本 URL	url

用法

{% assign version_count = page.versions | size %}
{% if version_count > 0 %}
  <ul class="flex space-x-1">
    <li class="px-2"><a href="{{ page.url }}">当前版本</a></li>
    {% for version_page in page.versions %}
      <li class="px-2"><a href="{{ version_page.url }}">{{ version_page.name }}</a></li>
    {% endfor %}
  </ul>
{% endif %}

tag（标签）

属性/方法	类型	解释	示例
path	string	标签页面的路径	/-/tags/AxdEf
name	string	名称	测试标签
color	string	字体颜色	#42445A
bg_color	string	背景颜色	#42445A
color_hls	string	颜色计算	background-color: hsl({{ tag.color_hls[0] }}, {{ tag.color_hls[1] }}%, 90%);
pages_count	integer	含有该标签的页面数量	<待开放>
pages	page[]	含有该标签的页面列表

页面的标签通过在 settings 中动态定义，通过 page.settings.tags 方法调用。

{% schema %}
{
  "settings": [
    {
      "id": "tags",
      "type": "tag_picker",
      "multiple": true,
      "label": "标签"
    }
  ]
}
{% schemaend %}

页面中的调用示例：

{% for tag in page.settings.tags %}
  <span style="background-color: {{ tag.color }}" class="px-2 py-1 text-white rounded-lg focus:outline-none focus:ring-2 focus:ring-offset-2">
    {{ tag.name }}
  </span>
{% endfor %}

site.tags 则返回当前站点的 Tag 标签集合

<ul role="list" class="flex flex-col space-y-1">
   {% for tag in site.tags %}
     <li>
       <a href="{{ tag.path }}" class="flex items-center px-2 py-2 space-x-2 transition-all duration-300 ease-in-out hover:bg-gray-500/5">
         <span class="w-2 h-2 rounded-full shrink-0" style="
           background-color: hsl({{ tag.color_hls[0] }}, {{ tag.color_hls[1] }}%, 90%);
           color: {{ tag.color }};"></span>
         <span class="flex-grow w-0 break-words" style="color: {{ tag.color }};">
           {{ tag.name }}
         </span>
       </a>
     </li>
   {% endfor %}
 </ul>

author（作者）

属性/方法	类型	解释	示例
name	string	作者名称	张三
avatar_url	string	作者头像

操作示例：

{% assign avatar_url = 'images/icons/icon.svg' | asset_url %}
<img src="{{ page.author.avatar_url | default: avatar_url }}" class="w-10 h-10 rounded-full" />
{{ page.author.name }}

plugins.feedback （用户反馈配置信息）

属性/方法	类型	解释	示例
helpful_types	Array(JSON)	用户可选择的表情列表	plugins.feedback.helpful_types
helpful_types[0].emoji	string	表情符	😊
helpful_types[0].label	string	表情符对应的意思	有用
helpful_label	string	提示用户选择表情	您的反馈是对我们的产品极其重要
message_enabled	boolean	是否启用反馈留言
message_required	boolean	当开启反馈留言，反馈留言是否必填
login_required	boolean	反馈是否必须登录

Filter（函数）

名称	解释
order_by	排序

order_by

对page列表进行排序，排序规则：

参数	解释
created_at	按照创建时间排列
edited_at	按照修改时间排列
visits_count	按照访问量排列

在参数前添加-，代表倒序排列

示例：

{% assign tag_pages = tag.pages | order_by: '-created_at' %}

名称	解释
where	筛选

where

对page列表进行筛选，筛选参数

参数	解释
template_name	模板名称

示例：

{% assign  pages = search.pages | where: 'template_name', 'post' %}

名称	解释
feedback_count	反馈数量
feedback_type_count(page, useful_type)	某个反馈类型的反馈数量

feedback_count、feedback_type_count

获取page的反馈数量

示例：

{{ page | feedback_type_count: '😊' }} //😊表情的反馈数量
{{ page | feedback_count }}            //页面总反馈数

roots

一级评论

roots

comment列表一级评论

示例：

{{ post.comments | roots | size }}

meta_tags

<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  {% meta_tags %}
</head>

这个标签会在 head 中自动添加如下内容

参考： meta-tags gem
charset=utf-8
title SEO 标题
theme-name 模板代号
theme-version 模板版本
theme-scope 模板类型
模板配色变量
favicon/image-src/share 都在mate_tag实现了
<link rel="icon" href="{{ site.settings.favicon_url}}"> 删掉，集成到了 meta_tags

paginate_tag

这个可以对数组或数据库查询分页，在这个标记内，会自动生成一个 paginate 变量，可获取如下属性：

engines/theme_engine/lib/theme_engine/liquid/drops/pagy_drop.rb:26

{
  'total_count' => @pagy.count,   # 总数量
  'total_pages' => @pagy.pages,   # 总页数
  'per_page' => @pagy.items,      # 每页数量
  'current_page' => @pagy.page,   # 当前页码
  'prev_page' => @pagy.prev,      # 上一页页码
  'next_page' => @pagy.next,      # 下一页页码
  'last_page' => @pagy.last,      # 最后一页页码
  'from' => @pagy.from,           # 当前页码的第一条记录的序号
  'to' => @pagy.to,               # 当前页码的最后一条记录的序号
  'series' => @pagy.series,       # 页码序列
  'page_param' => @pagy.vars[:page_param], # 页码参数名称
  'url_for' => UrlFor.new(@pagy)
}
分页不需要传 page 参数{% paginate_tag products, per: 5, page: params.page %} =>
{% paginate_tag products, per: 5 %}

其中 url_for 是一个自定义函数，可以通过 paginate.url_for[2] 生成第二页的链接，生成分页链接的例子。

前端用法：themes/cms/test/snippets/_paginate.liquid

{% assign pages = site.pages['/'].pages_in_list %}
{% paginate_tag pages, per: 4 %}
{% for page in pages %}
{% render "card", page: page %}
{% else %}
{% assign empty_i18n = "empty.name" | t %}
{% render 'empty', message: empty_i18n %}
{% endfor %}
{% render 'paginate', paginate: paginate %}
{% endpaginate_tag %}

search - 搜索表单

可以通过关键字或者标签搜索，搜索页面的可使用的变量包含：

site - 全站通用变量
search - 搜索页变量，其属性如下：
- pages - 搜索结果
- keywords - 搜索的关键字
- tag - 搜索的标签

app/drops/search_result_drop.rb

{% form_tag 'search' %}
<input type="hidden" name="q" value="{{ params.q | escape }}">
<button>搜一搜</button>
{% endform_tag %}
2024.1.27 提交新代码，以上代码已废弃

搜索表单，可通过 form.keywords_field_name 获取搜索输入框的 name 值

{% form_tag 'search' %}
<div class="relative flex items-center">
<input type="text" name="{{form.keywords_field_name}}" value="{{ search.keywords | escape }}" class="block w-full outline-none border-0 bg-white rounded pl-2 pr-8 text-[#424242] py-3 placeholder:text-gray-400 text-sm" placeholder="{{ "search.placeholder" | t }}">
</div>
{% endform_tag %}

结果返回：

{% paginate_tag search.pages, as: 'items' %}
{% for page in items %}
<li class="group hover:bg-primary/10 rounded px-2 space-x-2 py-2 flex items-center">
<div class="w-0 flex-grow">

搜索判断（新增）{% if search.tag or search.keywords %}
<p class="mt-3 text-xs">
{{ "search.result.t1" | t }}
{% if search.tag %}
<i class="px-2 py-1 rounded" style="background-color: {{ search.tag.bg_color }}">{{ search.tag.name }}</i>
{% endif %}
{% if search.keywords %}
<i>{{ search.keywords }}</i>
{% endif %}
{{ "search.result.t2" | t }}
</p>
{% endif %}

Breadcrumb

用户可以通过 page.breadcrumb 输出的 JSON 数组，自己循环生成，如：

themes/cms/test/snippets/_breadcrumb.liquid

{% comment %}
@params breadcrumb
array of objects with keys:
link_text: string
path: string
{% endcomment %}#引用: page.liquid
{% render 'breadcrumb', breadcrumb: page.breadcrumb %}#实现： snippets/_breadcrumb.liquid
<ul class="list-none text-gray-400 text-xs hidden sm:flex items-center space-x-1">
{% for crumb in breadcrumb %}
<li>
<div class="flex items-center">
{% if forloop.index0 > 0 %}
<svg class="h-5 w-5 flex-shrink-0 text-gray-300" fill="currentColor" viewBox="0 0 20 20" aria-hidden="true">
<path d="M5.555 17.776l8-16 .894.448-8 16-.894-.448z" />
</svg>
{% endif %}
<a href="{{ crumb.path }}">{{ crumb.link_text }}</a>
</div>
</li>
{% endfor %}
</ul>

# 前端最佳实践一个优秀的面包屑导航需要满足：1）移动端不会因为面包屑太长而被挤压；超出的部分可自动水平滚动；2）文本不会因为被挤压而截断。前端生成的代码：
<div class="overflow-x-auto">
<ol class="p-0 ml-4 bg-transparent breadcrumb">
<li class="breadcrumb-item flex break-keep"><a href="/">首页</a></li>
<li class="breadcrumb-item flex break-keep"><a href="/70891d/b53f30">工作区</a></li>
<li class="breadcrumb-item flex break-keep"><a href="/70891d/b53f30/da5e2e">工作区基础操作</a></li>
</ol>
</div>解析：overflow-x-auto 实现了溢出部分水平滚动breadcrumb 必须；为面包屑自定义cssbreadcrumb-item 必须；为面包屑自定义cssflex 使“/”和文本在一行（不被挤压）break-keep 使文本在一行（不被挤压）

feedback - 用户反馈表单

{% form_tag 'feedback' %}<input type="hidden" name="helpful_type" value="😊">
<button>😊</button>
{% endform_tag %}

password - 密码登录

{% form_tag 'sign_in_with_password' %}
<input name="sign_in[username]">
<input name="sign_in[password]">
<button>登录</button>
{% endform_tag %}

ssb - Baklib 账号一键登录

{% form_tag 'sign_in_with_ssb' %}
<button>Baklib 账号登录</button>
{% endform_tag %}

sso - 企业 SSO 账号一键登录

{% form_tag 'sign_in_with_sso' %}
<button>SSO 一键登录</button>
{% endform_tag %}

I18n翻译

模板设置翻译：

"t:setings_schema.beian.title"

页面翻译：

_("备案号")

模板翻译：

{{ 'setings_schema.beian.title' | t : '默认值' }}

颜色选项卡

站点主题设置默认添加的颜色选项卡，共6种色卡可定制，如图所示：

在站点设置页面定制好色卡颜色后，可在代码中使用，具体方法：

text-primary
text-primary-lighten
text-primary-darken
text-primary-50
text-primary-600/50