尧图网站建设 
1. 项目概述为什么你的博客需要一个“自定义页面”如果你正在使用Halo搭建个人博客或内容网站那么“页面”这个概念你一定不陌生。它和“文章”是构成网站内容的两大基石。但很多时候我们需要的不仅仅是一个简单的“关于我”或“友情链接”页面。你可能想创建一个展示个人作品集的画廊一个聚合了所有技术栈标签的“技能树”甚至是一个带有复杂交互的“留言板”或“项目时间线”。这时Halo后台自带的那个功能相对基础的“页面”编辑器就显得有些力不从心了。这就是“Halo自定义页面”项目要解决的问题。它不是一个具体的插件而是一种构建思路和能力。核心在于通过Halo提供的主题开发能力结合模板引擎、自定义字段以及一点点前端技术突破后台编辑器的限制为你的网站创建出独一无二、功能各异的专属页面。这就像给你的博客装上了一套“乐高积木”你可以用标准的“文章”和“页面”模块作为基础砖块再通过自定义的模板和逻辑搭建出城堡、飞船或者任何你想象中的东西。我自己的博客就用了不少自定义页面。比如我有一个“开源项目”页面它不仅仅罗列项目名称和链接还通过调用GitHub API动态显示项目的Star数、最后更新时间并用卡片式布局展示视觉效果和实用性都远超普通列表。还有一个“阅读清单”页面它集成了豆瓣读书的API自动同步我读过的书并生成评分和短评。这些页面的存在让我的博客从一个单向的信息发布平台变成了一个更具个人特色和互动性的数字名片。所以无论你是想打造更专业的个人品牌还是希望网站能承载更复杂的业务逻辑深入理解并实践“Halo自定义页面”都将是你从Halo使用者进阶为Halo驾驭者的关键一步。接下来我将从设计思路、技术实现到避坑经验完整拆解这个过程。2. 核心设计思路从“展示什么”到“如何生成”在动手写代码之前理清设计思路至关重要。自定义页面的核心是数据与表现的分离以及动态逻辑的引入。我们不能再用“写一篇页面文章”的思维而要用“开发一个微型应用页面”的思维。2.1 定义页面类型与数据源首先你需要明确这个自定义页面最终要呈现什么。我通常将其分为三类聚合展示型这是最常见的一类。例如“全站标签云”、“年度文章归档”、“特定分类下的文章画廊”。它的核心逻辑是查询与筛选。数据源就是Halo系统内的文章、分类、标签等元数据。外部集成型例如“GitHub项目墙”、“豆瓣书影音记录”、“最新推特动态”。它的核心逻辑是API调用与数据格式化。数据来自第三方服务你需要处理网络请求、数据解析和缓存。混合交互型例如“带搜索和过滤的作品集”、“用户留言板需结合评论功能”。它的核心逻辑是前端交互与数据过滤。可能同时涉及本地数据查询和前端JavaScript逻辑。以创建一个“技术栈技能树”页面为例它属于聚合展示型但带有一定的组织性。它的数据源是Halo的“标签”Tags但并非所有标签而是我事先规划好的、代表某项技能如“Java”, “Docker”, “React”的特定标签。页面需要展示这些标签并可能附带每个标签下的文章数量甚至文章列表。2.2 选择技术实现路径在Halo主题开发中实现自定义页面主要有三种路径选择哪种取决于你的需求复杂度路径一纯模板页面。这是最简单的方式。在主题的templates目录下创建一个新的模板文件例如skills.ftl假设使用FreeMarker。然后在Halo后台创建一个新页面在“高级设置”或“自定义模板”中选择这个skills模板。这种方式适用于数据逻辑简单主要通过模板语法如#list循环展示已有数据的场景。对于“技能树”页面如果只是列出特定标签此方法足够。路径二模板页面 自定义字段。当页面需要一些可配置的、不属于Halo默认模型的数据时就需要自定义字段。例如在“技能树”页面里我想为每个技能标签添加一个熟练度百分比如“Java: 85%”和一句简短描述。Halo的文章/页面模型本身没有这些字段。我可以在主题的theme.yaml中为“页面”模型声明一组自定义字段比如skill_proficiency数字类型和skill_description文本类型。这样在后台编辑该页面时就会出现这些额外的输入框。模板中通过${page.spec.fields.skill_proficiency!}即可读取。这种方式实现了后台可配置增强了灵活性。路径三模板页面 自定义数据模型与控制器。这是最强大也是最复杂的方式。当你的页面需要处理复杂的业务逻辑、调用外部API、或者操作全新的数据结构时就需要扩展Halo的后端。你需要开发一个Halo插件在插件中定义新的数据模型Extension并编写控制器Controller来提供数据查询接口。然后在主题模板中通过AJAX或直接调用插件提供的模板方法如果插件暴露了来获取这些自定义数据。例如要实现一个“GitHub项目墙”你需要在插件中编写调用GitHub API的Service并处理OAuth授权和缓存然后提供一个接口给前端模板使用。注意对于大多数个人博客场景路径一和路径二已经完全够用。路径三涉及到Java插件开发门槛较高通常只在有复杂企业级定制需求时使用。我们今天的讨论将聚焦于前两种路径这也是最能体现“自定义”精髓且性价比最高的方式。2.3 规划前端表现与交互确定了数据和逻辑就要思考前端如何呈现。是简单的列表还是卡片网格是否需要排序、过滤或搜索功能是否需要动画效果对于“技能树”我可能会选择一种视觉化较强的形式比如用水平或垂直进度条表示熟练度。将标签按领域分组如“后端”、“前端”、“运维”。点击每个技能标签可以展开/折叠显示该标签下的相关文章列表。这要求我们的模板不仅仅是输出HTML还要合理地引入CSS和JavaScript资源。在Halo主题中通常有统一的macro宏或module模块来管理头部head和尾部footer的静态资源。你需要确保自定义页面所需的特定样式表CSS或脚本JS能被正确加载。3. 实战构建一个“技能图谱”自定义页面下面我们以“路径二模板页面自定义字段”为例一步步构建一个功能相对丰富的“技能图谱”页面。这个页面将展示分组的技术技能每个技能包含名称、熟练度、描述以及相关文章链接。3.1 第一步在主题中定义自定义字段首先我们需要编辑主题的配置文件theme.yaml。在spec部分下找到或添加customTemplates和settings相关配置。这里的关键是为“页面”模型添加字段定义。apiVersion: theme.halo.run/v1alpha1 kind: Theme metadata: name: my-halo-theme spec: displayName: 我的主题 # ... 其他配置 ... customTemplates: - name: skills-map # 自定义模板的名称将在后台页面模板下拉框中显示 description: 技能图谱展示页面 screenshot: # 可选模板截图 file: templates/skills-map.ftl # 对应的模板文件路径 settings: # ... 主题设置 ... # 为“页面”模型定义字段组 formSchema: - $form: true group: basic label: 基础信息 # ... 其他基础字段 ... - $form: true group: skillFields # 我们自定义的字段组 label: 技能配置 formItem: - $form: true name: skill_groups label: 技能分组配置 description: 请按照JSON格式配置技能分组和技能项。 type: textarea required: true defaultValue: | [ { groupName: 后端开发, skills: [ {name: Java, proficiency: 85, description: 精通Spring Boot生态, tag: java}, {name: Golang, proficiency: 70, description: 用于微服务与工具开发, tag: golang} ] }, { groupName: 前端开发, skills: [ {name: Vue.js, proficiency: 80, description: 主力前端框架, tag: vue}, {name: React, proficiency: 60, description: 有所了解, tag: react} ] } ]关键点解析customTemplates这里注册了一个名为skills-map的自定义模板。当你在后台创建或编辑页面时在“模板”选择下拉框中就能看到“技能图谱展示页面”这个选项。formSchema我们在设置表单中为“页面”模型添加了一个新的字段组skillFields。字段设计我选择使用一个textarea类型的字段skill_groups用JSON格式来存储所有分组和技能数据。为什么用JSON而不是为每个技能单独定义字段因为技能项的数量和结构是动态的、可变的。为每个技能单独定义“技能1名称”、“技能1熟练度”…这样的字段会非常僵化且难以管理。一个JSON字段提供了最大的灵活性你可以在后台直接编辑这个JSON数组来增删改技能。当然这要求使用者在编辑时懂得基本的JSON语法。实操心得对于非技术人员博主JSON编辑可能有些门槛。一个更友好的替代方案是开发一个简单的主题设置UI通过可动态添加的表单行来输入技能数据然后在后台逻辑中将其组装成JSON。但这需要更复杂的前端脚本和主题开发能力。对于技术博客直接使用JSON字段是最高效、最清晰的方式。3.2 第二步创建自定义模板文件在主题的templates目录下创建文件skills-map.ftl。这个文件将定义页面的HTML结构和数据渲染逻辑。#-- skills-map.ftl -- #import ../macros/layout.ftl as layout #import ../macros/post.ftl as postMacros layout.layout title${post.title!} - ${blog_title!} canonical${post.status.publicUrl!} div classcontainer mx-auto px-4 py-12 h1 classtext-4xl font-bold text-center mb-2${post.title!}/h1 #if post.spec.excerpt?has_content p classtext-xl text-gray-600 text-center mb-12${post.spec.excerpt!}/p /#if #-- 1. 解析并展示技能分组数据 -- #assign skillGroupsJson post.spec.fields.skill_groups! / #if skillGroupsJson?has_content #assign skillGroups skillGroupsJson?eval / #list skillGroups as group div classmb-16 h2 classtext-3xl font-semibold border-l-4 border-blue-500 pl-4 mb-8${group.groupName}/h2 div classgrid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8 #list group.skills as skill #-- 2. 为每个技能查询关联文章 -- #assign relatedPosts [] / #if skill.tag?has_content postTag.list postsposts pageablepageable tagNameskill.tag #assign relatedPosts posts.content[0..*2] /#-- 只取前3篇 -- /postTag.list /#if div classbg-white rounded-xl shadow-lg p-6 hover:shadow-xl transition-shadow duration-300 div classflex justify-between items-start mb-4 h3 classtext-2xl font-bold${skill.name}/h3 span classtext-lg font-semibold text-blue-600${skill.proficiency}%/span /div p classtext-gray-700 mb-6${skill.description!}/p #-- 3. 熟练度进度条 -- div classmb-6 div classh-2 bg-gray-200 rounded-full overflow-hidden div classh-full bg-gradient-to-r from-blue-400 to-blue-600 rounded-full stylewidth: ${skill.proficiency}%;/div /div /div #-- 4. 展示关联文章 -- #if relatedPosts?size gt 0 div classpt-4 border-t border-gray-100 h4 classfont-medium text-gray-900 mb-2相关文章/h4 ul classspace-y-2 #list relatedPosts as relatedPost li a href${relatedPost.status.publicUrl!} classtext-blue-500 hover:text-blue-700 hover:underline flex items-center text-sm svg classw-4 h-4 mr-1 fillnone strokecurrentColor viewBox0 0 24 24path stroke-linecapround stroke-linecapround stroke-width2 dM9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z/path/svg ${relatedPost.spec.title!} /a /li /#list /ul /div /#if /div /#list /div /div /#list #else div classtext-center py-12 p classtext-gray-500请在页面编辑器中配置技能数据。/p /div /#if /div #-- 引入特定于本页面的CSS/JS -- style /* 可以在这里添加一些微调样式 */ /style /layout.layout代码逻辑拆解数据获取与解析#assign skillGroupsJson post.spec.fields.skill_groups! /这行代码从当前页面对象post的自定义字段中取出我们之前定义的JSON字符串。?eval函数是FreeMarker的内置函数用于将JSON字符串解析为真正的数据结构列表、字典等。这是一个关键技巧。动态数据查询对于每个技能项我们通过postTag.list这个Halo内置的模板标签Tag根据技能配置的tag字段如“java”去查询被打上该标签的最新文章。posts.content[0..*2]是FreeMarker的切片语法表示取列表的前3个元素索引0到2。这实现了数据关联。前端渲染我们使用了Tailwind CSS的类名进行样式布局如grid,shadow-lg,p-6。进度条通过一个外层灰色背景div和一个内层蓝色背景div实现内层div的宽度由skill.proficiency动态控制。错误处理通过#if skillGroupsJson?has_content判断字段是否有内容如果没有则显示提示信息避免页面因空数据而报错或显示异常。3.3 第三步在Halo后台创建并配置页面登录Halo后台进入“页面”管理。点击“新建页面”。填写页面标题例如“我的技能图谱”。在编辑器的“高级”或“设置”区域不同主题位置可能不同找到“模板”选择框。你应该能看到下拉选项中出现了我们定义的“技能图谱展示页面”对应skills-map。关键步骤选择“技能图谱展示页面”后页面的编辑表单可能会刷新下方会出现我们在theme.yaml中定义的“技能配置”字段组。你会看到一个文本区域Textarea里面已经预填了我们在defaultValue中设置的示例JSON。根据你的实际情况修改这个JSON数据。例如增加新的分组“DevOps”并在其下添加“Docker”、“Kubernetes”等技能项。确保JSON格式正确可以使用在线JSON格式化工具校验。发布页面。至此一个高度定制化的“技能图谱”页面就创建完成了。它完全独立于普通的文章列表或页面拥有自己独特的数据结构和视觉表现。4. 进阶技巧与深度优化上面的例子展示了基本流程。但在实际项目中你可能会遇到更复杂的需求。下面分享几个进阶技巧。4.1 性能优化缓存与异步加载我们的技能页面在渲染时对每个技能标签都执行了一次文章查询postTag.list。如果技能项很多比如20个这意味着页面一次渲染要执行20次数据库查询在访问量稍大时会对服务器造成压力。优化方案一数据预聚合与缓存我们可以在主题的某个地方例如一个自定义的宏或工具类中预先进行一次性的复杂查询。比如一次性获取全站所有标签及其对应的最新N篇文章存储在一个Map数据结构中。在模板里直接从这个Map里取数据而不是每次都查询数据库。这需要将逻辑写在主题的Java代码中如果主题包含自定义组件或者利用Halo的缓存机制。一个更简单、在纯模板层面可实现的方案是减少查询量。例如只对“熟练度”高于某个阈值的关键技能进行文章关联查询或者将所有技能对应的标签合并成一个列表只做一次查询后再在内存中分组。优化方案二前端异步加载对于“外部集成型”页面如GitHub项目墙API调用可能很慢。不应该让用户等待所有数据加载完才看到页面。我们可以这样设计模板只渲染页面的基本骨架标题、介绍、空的容器。在页面底部引入一段JavaScript使用fetch或axios异步调用一个后端接口这个接口可以是Halo插件提供的也可以是一个简单的云函数。这个接口负责调用GitHub API获取数据后返回给前端。前端JavaScript收到数据后动态生成DOM元素并插入到容器中。这样做页面首屏加载很快动态内容在后台加载即使第三方API偶尔超时或失败也不会导致整个页面白屏。4.2 增强交互前端过滤与搜索假设我们的技能页面项目非常多用户想快速找到某个特定技能。我们可以添加一个搜索框。#-- 在技能分组列表上方添加搜索框 -- div classmb-8 input typetext idskillSearch placeholder搜索技能名称或描述... classw-full md:w-1/3 px-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent outline-none transition /div script document.getElementById(skillSearch).addEventListener(input, function(e) { const searchTerm e.target.value.toLowerCase(); const skillCards document.querySelectorAll([data-skill-card]); // 给每个技能卡片添加>div class...> Halo自定义页面开发指南：从模板到实战打造个性化博客
1. 项目概述为什么你的博客需要一个“自定义页面”如果你正在使用Halo搭建个人博客或内容网站那么“页面”这个概念你一定不陌生。它和“文章”是构成网站内容的两大基石。但很多时候我们需要的不仅仅是一个简单的“关于我”或“友情链接”页面。你可能想创建一个展示个人作品集的画廊一个聚合了所有技术栈标签的“技能树”甚至是一个带有复杂交互的“留言板”或“项目时间线”。这时Halo后台自带的那个功能相对基础的“页面”编辑器就显得有些力不从心了。这就是“Halo自定义页面”项目要解决的问题。它不是一个具体的插件而是一种构建思路和能力。核心在于通过Halo提供的主题开发能力结合模板引擎、自定义字段以及一点点前端技术突破后台编辑器的限制为你的网站创建出独一无二、功能各异的专属页面。这就像给你的博客装上了一套“乐高积木”你可以用标准的“文章”和“页面”模块作为基础砖块再通过自定义的模板和逻辑搭建出城堡、飞船或者任何你想象中的东西。我自己的博客就用了不少自定义页面。比如我有一个“开源项目”页面它不仅仅罗列项目名称和链接还通过调用GitHub API动态显示项目的Star数、最后更新时间并用卡片式布局展示视觉效果和实用性都远超普通列表。还有一个“阅读清单”页面它集成了豆瓣读书的API自动同步我读过的书并生成评分和短评。这些页面的存在让我的博客从一个单向的信息发布平台变成了一个更具个人特色和互动性的数字名片。所以无论你是想打造更专业的个人品牌还是希望网站能承载更复杂的业务逻辑深入理解并实践“Halo自定义页面”都将是你从Halo使用者进阶为Halo驾驭者的关键一步。接下来我将从设计思路、技术实现到避坑经验完整拆解这个过程。2. 核心设计思路从“展示什么”到“如何生成”在动手写代码之前理清设计思路至关重要。自定义页面的核心是数据与表现的分离以及动态逻辑的引入。我们不能再用“写一篇页面文章”的思维而要用“开发一个微型应用页面”的思维。2.1 定义页面类型与数据源首先你需要明确这个自定义页面最终要呈现什么。我通常将其分为三类聚合展示型这是最常见的一类。例如“全站标签云”、“年度文章归档”、“特定分类下的文章画廊”。它的核心逻辑是查询与筛选。数据源就是Halo系统内的文章、分类、标签等元数据。外部集成型例如“GitHub项目墙”、“豆瓣书影音记录”、“最新推特动态”。它的核心逻辑是API调用与数据格式化。数据来自第三方服务你需要处理网络请求、数据解析和缓存。混合交互型例如“带搜索和过滤的作品集”、“用户留言板需结合评论功能”。它的核心逻辑是前端交互与数据过滤。可能同时涉及本地数据查询和前端JavaScript逻辑。以创建一个“技术栈技能树”页面为例它属于聚合展示型但带有一定的组织性。它的数据源是Halo的“标签”Tags但并非所有标签而是我事先规划好的、代表某项技能如“Java”, “Docker”, “React”的特定标签。页面需要展示这些标签并可能附带每个标签下的文章数量甚至文章列表。2.2 选择技术实现路径在Halo主题开发中实现自定义页面主要有三种路径选择哪种取决于你的需求复杂度路径一纯模板页面。这是最简单的方式。在主题的templates目录下创建一个新的模板文件例如skills.ftl假设使用FreeMarker。然后在Halo后台创建一个新页面在“高级设置”或“自定义模板”中选择这个skills模板。这种方式适用于数据逻辑简单主要通过模板语法如#list循环展示已有数据的场景。对于“技能树”页面如果只是列出特定标签此方法足够。路径二模板页面 自定义字段。当页面需要一些可配置的、不属于Halo默认模型的数据时就需要自定义字段。例如在“技能树”页面里我想为每个技能标签添加一个熟练度百分比如“Java: 85%”和一句简短描述。Halo的文章/页面模型本身没有这些字段。我可以在主题的theme.yaml中为“页面”模型声明一组自定义字段比如skill_proficiency数字类型和skill_description文本类型。这样在后台编辑该页面时就会出现这些额外的输入框。模板中通过${page.spec.fields.skill_proficiency!}即可读取。这种方式实现了后台可配置增强了灵活性。路径三模板页面 自定义数据模型与控制器。这是最强大也是最复杂的方式。当你的页面需要处理复杂的业务逻辑、调用外部API、或者操作全新的数据结构时就需要扩展Halo的后端。你需要开发一个Halo插件在插件中定义新的数据模型Extension并编写控制器Controller来提供数据查询接口。然后在主题模板中通过AJAX或直接调用插件提供的模板方法如果插件暴露了来获取这些自定义数据。例如要实现一个“GitHub项目墙”你需要在插件中编写调用GitHub API的Service并处理OAuth授权和缓存然后提供一个接口给前端模板使用。注意对于大多数个人博客场景路径一和路径二已经完全够用。路径三涉及到Java插件开发门槛较高通常只在有复杂企业级定制需求时使用。我们今天的讨论将聚焦于前两种路径这也是最能体现“自定义”精髓且性价比最高的方式。2.3 规划前端表现与交互确定了数据和逻辑就要思考前端如何呈现。是简单的列表还是卡片网格是否需要排序、过滤或搜索功能是否需要动画效果对于“技能树”我可能会选择一种视觉化较强的形式比如用水平或垂直进度条表示熟练度。将标签按领域分组如“后端”、“前端”、“运维”。点击每个技能标签可以展开/折叠显示该标签下的相关文章列表。这要求我们的模板不仅仅是输出HTML还要合理地引入CSS和JavaScript资源。在Halo主题中通常有统一的macro宏或module模块来管理头部head和尾部footer的静态资源。你需要确保自定义页面所需的特定样式表CSS或脚本JS能被正确加载。3. 实战构建一个“技能图谱”自定义页面下面我们以“路径二模板页面自定义字段”为例一步步构建一个功能相对丰富的“技能图谱”页面。这个页面将展示分组的技术技能每个技能包含名称、熟练度、描述以及相关文章链接。3.1 第一步在主题中定义自定义字段首先我们需要编辑主题的配置文件theme.yaml。在spec部分下找到或添加customTemplates和settings相关配置。这里的关键是为“页面”模型添加字段定义。apiVersion: theme.halo.run/v1alpha1 kind: Theme metadata: name: my-halo-theme spec: displayName: 我的主题 # ... 其他配置 ... customTemplates: - name: skills-map # 自定义模板的名称将在后台页面模板下拉框中显示 description: 技能图谱展示页面 screenshot: # 可选模板截图 file: templates/skills-map.ftl # 对应的模板文件路径 settings: # ... 主题设置 ... # 为“页面”模型定义字段组 formSchema: - $form: true group: basic label: 基础信息 # ... 其他基础字段 ... - $form: true group: skillFields # 我们自定义的字段组 label: 技能配置 formItem: - $form: true name: skill_groups label: 技能分组配置 description: 请按照JSON格式配置技能分组和技能项。 type: textarea required: true defaultValue: | [ { groupName: 后端开发, skills: [ {name: Java, proficiency: 85, description: 精通Spring Boot生态, tag: java}, {name: Golang, proficiency: 70, description: 用于微服务与工具开发, tag: golang} ] }, { groupName: 前端开发, skills: [ {name: Vue.js, proficiency: 80, description: 主力前端框架, tag: vue}, {name: React, proficiency: 60, description: 有所了解, tag: react} ] } ]关键点解析customTemplates这里注册了一个名为skills-map的自定义模板。当你在后台创建或编辑页面时在“模板”选择下拉框中就能看到“技能图谱展示页面”这个选项。formSchema我们在设置表单中为“页面”模型添加了一个新的字段组skillFields。字段设计我选择使用一个textarea类型的字段skill_groups用JSON格式来存储所有分组和技能数据。为什么用JSON而不是为每个技能单独定义字段因为技能项的数量和结构是动态的、可变的。为每个技能单独定义“技能1名称”、“技能1熟练度”…这样的字段会非常僵化且难以管理。一个JSON字段提供了最大的灵活性你可以在后台直接编辑这个JSON数组来增删改技能。当然这要求使用者在编辑时懂得基本的JSON语法。实操心得对于非技术人员博主JSON编辑可能有些门槛。一个更友好的替代方案是开发一个简单的主题设置UI通过可动态添加的表单行来输入技能数据然后在后台逻辑中将其组装成JSON。但这需要更复杂的前端脚本和主题开发能力。对于技术博客直接使用JSON字段是最高效、最清晰的方式。3.2 第二步创建自定义模板文件在主题的templates目录下创建文件skills-map.ftl。这个文件将定义页面的HTML结构和数据渲染逻辑。#-- skills-map.ftl -- #import ../macros/layout.ftl as layout #import ../macros/post.ftl as postMacros layout.layout title${post.title!} - ${blog_title!} canonical${post.status.publicUrl!} div classcontainer mx-auto px-4 py-12 h1 classtext-4xl font-bold text-center mb-2${post.title!}/h1 #if post.spec.excerpt?has_content p classtext-xl text-gray-600 text-center mb-12${post.spec.excerpt!}/p /#if #-- 1. 解析并展示技能分组数据 -- #assign skillGroupsJson post.spec.fields.skill_groups! / #if skillGroupsJson?has_content #assign skillGroups skillGroupsJson?eval / #list skillGroups as group div classmb-16 h2 classtext-3xl font-semibold border-l-4 border-blue-500 pl-4 mb-8${group.groupName}/h2 div classgrid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8 #list group.skills as skill #-- 2. 为每个技能查询关联文章 -- #assign relatedPosts [] / #if skill.tag?has_content postTag.list postsposts pageablepageable tagNameskill.tag #assign relatedPosts posts.content[0..*2] /#-- 只取前3篇 -- /postTag.list /#if div classbg-white rounded-xl shadow-lg p-6 hover:shadow-xl transition-shadow duration-300 div classflex justify-between items-start mb-4 h3 classtext-2xl font-bold${skill.name}/h3 span classtext-lg font-semibold text-blue-600${skill.proficiency}%/span /div p classtext-gray-700 mb-6${skill.description!}/p #-- 3. 熟练度进度条 -- div classmb-6 div classh-2 bg-gray-200 rounded-full overflow-hidden div classh-full bg-gradient-to-r from-blue-400 to-blue-600 rounded-full stylewidth: ${skill.proficiency}%;/div /div /div #-- 4. 展示关联文章 -- #if relatedPosts?size gt 0 div classpt-4 border-t border-gray-100 h4 classfont-medium text-gray-900 mb-2相关文章/h4 ul classspace-y-2 #list relatedPosts as relatedPost li a href${relatedPost.status.publicUrl!} classtext-blue-500 hover:text-blue-700 hover:underline flex items-center text-sm svg classw-4 h-4 mr-1 fillnone strokecurrentColor viewBox0 0 24 24path stroke-linecapround stroke-linecapround stroke-width2 dM9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z/path/svg ${relatedPost.spec.title!} /a /li /#list /ul /div /#if /div /#list /div /div /#list #else div classtext-center py-12 p classtext-gray-500请在页面编辑器中配置技能数据。/p /div /#if /div #-- 引入特定于本页面的CSS/JS -- style /* 可以在这里添加一些微调样式 */ /style /layout.layout代码逻辑拆解数据获取与解析#assign skillGroupsJson post.spec.fields.skill_groups! /这行代码从当前页面对象post的自定义字段中取出我们之前定义的JSON字符串。?eval函数是FreeMarker的内置函数用于将JSON字符串解析为真正的数据结构列表、字典等。这是一个关键技巧。动态数据查询对于每个技能项我们通过postTag.list这个Halo内置的模板标签Tag根据技能配置的tag字段如“java”去查询被打上该标签的最新文章。posts.content[0..*2]是FreeMarker的切片语法表示取列表的前3个元素索引0到2。这实现了数据关联。前端渲染我们使用了Tailwind CSS的类名进行样式布局如grid,shadow-lg,p-6。进度条通过一个外层灰色背景div和一个内层蓝色背景div实现内层div的宽度由skill.proficiency动态控制。错误处理通过#if skillGroupsJson?has_content判断字段是否有内容如果没有则显示提示信息避免页面因空数据而报错或显示异常。3.3 第三步在Halo后台创建并配置页面登录Halo后台进入“页面”管理。点击“新建页面”。填写页面标题例如“我的技能图谱”。在编辑器的“高级”或“设置”区域不同主题位置可能不同找到“模板”选择框。你应该能看到下拉选项中出现了我们定义的“技能图谱展示页面”对应skills-map。关键步骤选择“技能图谱展示页面”后页面的编辑表单可能会刷新下方会出现我们在theme.yaml中定义的“技能配置”字段组。你会看到一个文本区域Textarea里面已经预填了我们在defaultValue中设置的示例JSON。根据你的实际情况修改这个JSON数据。例如增加新的分组“DevOps”并在其下添加“Docker”、“Kubernetes”等技能项。确保JSON格式正确可以使用在线JSON格式化工具校验。发布页面。至此一个高度定制化的“技能图谱”页面就创建完成了。它完全独立于普通的文章列表或页面拥有自己独特的数据结构和视觉表现。4. 进阶技巧与深度优化上面的例子展示了基本流程。但在实际项目中你可能会遇到更复杂的需求。下面分享几个进阶技巧。4.1 性能优化缓存与异步加载我们的技能页面在渲染时对每个技能标签都执行了一次文章查询postTag.list。如果技能项很多比如20个这意味着页面一次渲染要执行20次数据库查询在访问量稍大时会对服务器造成压力。优化方案一数据预聚合与缓存我们可以在主题的某个地方例如一个自定义的宏或工具类中预先进行一次性的复杂查询。比如一次性获取全站所有标签及其对应的最新N篇文章存储在一个Map数据结构中。在模板里直接从这个Map里取数据而不是每次都查询数据库。这需要将逻辑写在主题的Java代码中如果主题包含自定义组件或者利用Halo的缓存机制。一个更简单、在纯模板层面可实现的方案是减少查询量。例如只对“熟练度”高于某个阈值的关键技能进行文章关联查询或者将所有技能对应的标签合并成一个列表只做一次查询后再在内存中分组。优化方案二前端异步加载对于“外部集成型”页面如GitHub项目墙API调用可能很慢。不应该让用户等待所有数据加载完才看到页面。我们可以这样设计模板只渲染页面的基本骨架标题、介绍、空的容器。在页面底部引入一段JavaScript使用fetch或axios异步调用一个后端接口这个接口可以是Halo插件提供的也可以是一个简单的云函数。这个接口负责调用GitHub API获取数据后返回给前端。前端JavaScript收到数据后动态生成DOM元素并插入到容器中。这样做页面首屏加载很快动态内容在后台加载即使第三方API偶尔超时或失败也不会导致整个页面白屏。4.2 增强交互前端过滤与搜索假设我们的技能页面项目非常多用户想快速找到某个特定技能。我们可以添加一个搜索框。#-- 在技能分组列表上方添加搜索框 -- div classmb-8 input typetext idskillSearch placeholder搜索技能名称或描述... classw-full md:w-1/3 px-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent outline-none transition /div script document.getElementById(skillSearch).addEventListener(input, function(e) { const searchTerm e.target.value.toLowerCase(); const skillCards document.querySelectorAll([data-skill-card]); // 给每个技能卡片添加>div class...>