From 4b2e1bd7faef001450fbea3baf8c41ddfa2048df Mon Sep 17 00:00:00 2001 From: Nya Candy Date: Mon, 5 Aug 2024 19:09:52 +0800 Subject: [PATCH] feat: add some more --- source/_posts/ecosystem-develop-workflow.md | 18 ++++- source/_posts/linklist.md | 76 +++++++++++++++++++++ source/_posts/pjax-events.md | 38 +++++++++++ source/_posts/tag-widgets.md | 24 +++++++ source/index.md | 2 + 5 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 source/_posts/linklist.md create mode 100644 source/_posts/pjax-events.md diff --git a/source/_posts/ecosystem-develop-workflow.md b/source/_posts/ecosystem-develop-workflow.md index a02ba83..7914122 100644 --- a/source/_posts/ecosystem-develop-workflow.md +++ b/source/_posts/ecosystem-develop-workflow.md @@ -10,4 +10,20 @@ comments: true toc: true excerpt: "对主题周边生态组件的开发流程" --- -TODO +针对主题的周边开发，核心在于灵活使用注入代码功能提供的接口。 + +以评论系统为例，首先是在 `comments` 配置段里添加注入模板，之后就是通过 `additional_injections` 配置段引入需要额外引入的文件。例如： + +- 在 `head` 引入样式表文件 +- 在 `footer` 配置段中往 DOM 中加入组件 +- 在 `after_footer` 引入执行脚本 + +{% alertbar info " + +从表现形式来讲， additional_injections 配置段的 footer 和 after_footer 的功能一致，并没有什么区别，拆开这两个主要是出于语义上的区分需要，即 footer 用于安置组件，而 after_footer 用于引入代码。您也可以使用您自己喜欢的配置方式来管理。 + +" %} + +由于此处注入的脚本并不会在 PJAX 时自动重载，请添加针对 [PJAX 事件](/posts/pjax-events/) 的监听以确保重载后函数能在页面更新时被再次执行。 + +我们提供了一个 [周边站点](https://eco.krt.moe) 用于陈列一些周边的配置方案，如果您有相关开发参照或使用的需求，欢迎随时前往参考。 diff --git a/source/_posts/linklist.md b/source/_posts/linklist.md new file mode 100644 index 0000000..e980b3d --- /dev/null +++ b/source/_posts/linklist.md @@ -0,0 +1,76 @@ +--- +title: 链接列表 +date: "2024-08-04 21:00:08" +categories: 使用 +tags: +- 教程 +#sticky: +#cover: +comments: true +toc: true +--- +因链接列表可能包含较为复杂且频繁变动的信息，为了避免给主题的配置选项造成干扰， V3 版本开始的主题使用放置于 `_data` 目录下的 `linklist.yml` 来管理具体对应的内容。 + + +## 语法 + +这个文件使用的是 YAML 语法，也就是主题配置和站点配置文件使用的同一种语法。如果您有遇到语法提示报错，您可以参考相关的语法说明。 + +## 文件结构 + +一个链接列表文件中包含若干个平级的列表，每个列表的结构如下所示： + +``yaml +<列表ID>: +- <链接成员1> +- <链接成员2> +- <链接成员3> +- <链接成员...> +``` + +即，每个列表： + +1. 由一个 `列表 ID` 引领的若干个列表成员构成。 +2. 包含若干个链接成员。 + +其中， `列表ID` 的命名要求符合一般的字符串规范。为避免可能出现的异常问题，我们推荐您使用小写字母、数字与下划线的组合，且使用小写字母作为开头。 + +为避免出现冲突，每个 `列表 ID` 均应为局部唯一的：即在这个站点实例的 linklist.yml 文件中，不能包含多个相同的 `列表 ID` ；但对于不同的站点实例来说并没有这个限制。 + +每个链接成员的结构如下所示： + +``yaml +title: <链接标题> +description: <链接描述文本> +image: <链接代表图片地址> +link: <链接地址> +``` + +这四个字段都是文本型格式，其中 image 和 link 要求为有效的超链接（分别指向图片文件和目标位置），可以是相对路径也可以是绝对路径。 + +## 样例 + +一个简单的样例如下所示。 + +这个样例包含了两个链接列表：第一个的列表 ID 为 `linklistindata` ，包含 3 个链接；第二个的列表 ID 为 `awesome` ，包含 1 个链接。 + +```yaml +linklistindata: +- title: "猫猫①号" + description: "喵~" + image: "/images/user.svg" + link: "https://candinya.com" +- title: "猫猫②号" + description: "喵喵" + image: "/images/user.svg" + link: "https://candinya.com" +- title: "猫猫⑨号" + description: "咪啪~" + image: "/images/user.svg" + link: "https://candinya.com" +awesome: +- title: "糖菓·部落" + description: "Never drown the flame of hope" + image: "https://candinya.com/images/candinya.webp" + link: "https://candinya.com" +``` diff --git a/source/_posts/pjax-events.md b/source/_posts/pjax-events.md new file mode 100644 index 0000000..1ff6811 --- /dev/null +++ b/source/_posts/pjax-events.md @@ -0,0 +1,38 @@ +--- +title: PJAX 事件 +date: "2024-08-04 21:00:08" +categories: 开发 +tags: +- 教程 +#sticky: +#cover: +comments: true +toc: true +--- +Kratos : Rebirth 使用了一种名为 PJAX (PushState + AJAX) 的技术来实现页面组件的部分更新，以避免对页面间的共享项（如站点播放器）产生干扰。因为这项技术并不会在页面更新时自动重新执行所有的脚本项，所以我们增加了一些事件，用于指引自定义的脚本在页面重载时被正确执行。 + + +## 事件列表 + +事件列表及对应的详细解释如下： + +| 事件 | 触发条件 | 说明 | +| ------------- | ------------- | ------------------------------------------------------ | +| pjax:before | PJAX 执行前 | 即将执行 | +| pjax:success | PJAX 请求成功 | 已经成功拉取到数据，但还未确认是否为可以执行的有效内容 | +| pjax:complete | PJAX 执行完成 | 确认为有效的数据，并且完成了内容替换 | +| pjax:error | PJAX 遇到问题 | 请求失败或为无效内容等 | + +一般关注的比较多的是 `pjax:success` 事件，例如针对评论系统，可以在监听到这个事件被执行时重新设置 `window.loadComments` 以便在 PJAX 完成后被自动执行。 + +## 监听事件 + +这些事件会在 window 载体对象上传播，因而可以直接在 window 上挂载事件监听器，例如： + +```js +window.addEventListener( + 'pjax:success', // 事件名称 + () => { // 事件回调函数 + window.loadComments = loadComments; +}); +``` diff --git a/source/_posts/tag-widgets.md b/source/_posts/tag-widgets.md index 73417a8..6f07ba0 100644 --- a/source/_posts/tag-widgets.md +++ b/source/_posts/tag-widgets.md @@ -248,3 +248,27 @@ danger 的内容 ```md 这里有一些{% blur 被模糊的字符 %} ``` + +## 链接列表 (LinkList) + +链接列表是一块用于呈现包含图片、标题和描述的链接使用的组件。 + +与其他组件不同的是，它的数据并不直接配置在组件内部，而是通过 [链接列表](/posts/linklist/) 来管理。 + +### 格式 + +```md +{% linklist <列表ID> <列表顺序?> %} +``` + +### 参数 + +#### 列表ID + +列表 ID 是指在链接列表里用于标记整个列表的唯一标识符，具体请参考链接列表页面的说明，此处不再赘述。 + +#### 列表顺序 *(可选)* + +这个参数用于指引列表中各个链接具体使用的排序方式。它有两个可选值，分别为 `order` 和 `random` ，代表有序（遵从链接列表文件中的配置）或是无序的列表。 + +为了优化性能，有序列表会在站点渲染时直接固化，而无序列表则会在储存列表信息后由运行时的浏览器随机生成。 diff --git a/source/index.md b/source/index.md index 7e9851e..d5af604 100644 --- a/source/index.md +++ b/source/index.md @@ -11,6 +11,7 @@ toc: false - [配置结构](/posts/configurations/) - [模板参数](/posts/template-variables/) - [标签组件](/posts/tag-widgets/) +- [链接列表](/posts/linklist/) {% collapse "旧版本(V2)用户的迁移说明" %} @@ -24,5 +25,6 @@ toc: false ## 开发者的实验室 - [项目结构](/posts/project-structure/) +- [PJAX 事件](/posts/pjax-events/) - [二次开发流程](/posts/theme-develop-workflow/) - [周边开发流程](/posts/ecosystem-develop-workflow/)