登录 注册

Solo 皮肤开发指南

本贴最后更新于 1752 天前，其中的信息可能已经渤澥桑田

皮肤开发

框架简介

solo/src/main/webapp 页面结构

|- admin                        // 后台管理
|- common-template              // 通用模版
|  |- kill-browser.ftl          // 对非现代浏览器展现的提示
|  |- label.ftl                 // js 中需要使用到的 Java 变量
|  |- macro-comment_script.ftl  // 评论宏
|  |- macro-common_head.ftl     // html 中的 head 宏
|  |- macro-common_page.ftl     // 皮肤以外的其他页面宏
|  |- macro-user_site.ftl       // 用户自定义的站点宏
|  |- search.ftl                // 搜索页面
|  |- start.ftl                 // 开始使用页面，即登录/注册
|  |- share.ftl                 // 分享，需配合 page.share() 使用
|  |- toc.ftl                   // 文章目录
|  |- top-bar.ftl               // 皮肤顶部导航栏，可选
|- error                        // 错误页面
|- images                       // 通用图片
|- js                           // js 目录
|  |- admin                     // 后台 js 
|  |- lib                       // js 第三方库
|  |- common.js                 // 通用方法
|  |- page.js                   // 文章页面通用方法
|  |- pjax.js                   // 页面跳转无刷新的
| - markdowns                   // 存放导入的 markdowns
| - plugins                     // 插件
| - scss                        // 样式文件
|- skins                        // 参见下面的皮肤结构
|- WEB-INF                      // 页面资源配置
|- CHANGE_LOGS.html             // 版本修改历史
|- manifest.json.tpl            // 移动站点描述模版
|- robots.txt                   // 爬虫设置
|- sw.js                        // service work 文件

solo/src/main/webapp/skins/skin-name 皮肤结构

|- css                       // 样式目录
|  |- fonts                  // 字体文件
|  |- base.scss              // 使用 sass，尽量避免使用行内样式及页内样式
|  |- base.css               // npm run build 后根据 base.scss 生成
|- images                    // 图片目录
|- js                        // JavaScript 目录
|  |- common.js              // 脚本，尽量避免在 ftl 中写脚本
|  |- common.min.js          // npm run build 后根据 common.js 生成
|- lang                      // 语言配置文件，当 solo/src/main/resources/lang_zh_CN.properties 中无配置时可添加至此
|  |- lang_en_US.properties  // 英文
|  |- lang_zh_CN.properties  // 中文
|- archive-articles.ftl      // 某年某月所写文章的列表页面
|- archives.ftl              // 存档列表页面
|- article.ftl               // 文章页面
|- article-list.ftl          // 文章列表，可复用于有文章列表的页面
|- categories.ftl            // 分类页面
|- category-articles.ftl     // 某分类下的文章列表页面
|- common-comment.ftl        // 评论模版
|- dynamic.ftl               // 动态页面
|- footer.ftl                // 页尾
|- header.ftl                // 页头
|- index.ftl                 // 首页页面
|- links.ftl                 // 链接列表页面
|- author-articles.ftl       // 某用户所写的文章列表页面
|- macro-comments.ftl        // 评论列表及回复的宏
|- preview.png               // 皮肤首页截图，大小为 280px * 160px
|- side.ftl                  // 侧边栏
|- skin.properties           // 皮肤信息
|- tag-articles.ftl          // 某标签的文章列表页面
|- tags.ftl                  // 标签列表页面

开发步骤

  1. 安装 node 环境，根目录下运行 npm install
  2. 在 solo/src/main/webapp/skins 目录下按照皮肤结构创建对应的文件夹及文件。可参照 nijigen 皮肤
  3. 根目录下运行 npm run dev ，保持对 CSS、JavaScript 文件的热编译，以便实时生成浏览器可运行的的 CSS 、JavaScript 文件
  4. 从 index.ftl 开始入手依次编写页面
  5. 编写完成后运行 npm run build 对 CSS、JavaScript 文件进行编译和压缩

Pjax 使用

  1. scss 文件中添加 @import "../../../scss/nprogress";
  2. 页面中需要 pjax 的部分请参照以下代码进行修改
<div id="pjax">  
<#if pjax><!---- pjax {#pjax} start ----></#if>
我是需要 pjax 的内容
<#if pjax><!---- pjax {#pjax} end ----></#if>  
</div>
...
<#if pjax><!---- pjax {#pjax} start ----></#if>
我是需要 pjax 的脚本
<#if pjax><!---- pjax {#pjax} end ----></#if>
  1. 调用 Util.initPjax
  2. 在文章页面、首页、其他页面来回切换进行 pjax 测试，检查功能和脚本是否正常。

vcomment 使用

vcomment 简介：🧵 B3log 分布式社区的评论组件，欢迎加入下一代社区网络。

使用静态皮肤和 文章同步，需添加 vcomment 组件。使用时请注意保持元素属性及属性值。

<!-- vcomment 组件 -->
<div id="vcomment" data-name="${article.authorName}" data-postId="${article.oId}"></div>
<!-- solo 原生评论组件 -->
<div id="soloComments" style="display:none">
    <@comments commentList=articleComments article=article></@comments>
</div>

uvstat 使用

uvstat 简介：📈 B3log 分布式社区的浏览、评论计数组件，欢迎加入下一代社区网络。

  • 浏览
    使用 span 标签将访问数进行包裹，并加上 data-uvstaturl 属性，其值为该访问数对应的链接地址 
     <span data-uvstaturl="${servePath}${article.articlePermalink}"> ${article.articleViewCount} </span>
  • 评论
    使用 span 标签将评论数进行包裹，并加上 data-uvstatcmt 属性，其值为该评论数对应的文章 id 
     <span data-uvstatcmt="${article.oId}"> ${article.articleCommentCount} </span>

注意事项

  • 皮肤下的样式文件 css/base.scss 和脚本文件 js/common.js 请保持名称的统一，否则无法进行编译

  • 不可修改 .css 文件或 .min.js 文件，否则运行 npm run dev 或 npm run build 命令时会被覆盖

  • macro-comments.ftl 中标签 id 不可进行更改

  • 可引入公共的 scss [遵循 BEM 规范] src/main/webapp/scss 、公共的 js src/main/webapp/js 和公共的模版 src/main/webapp/common-template 以保持功能的一致性和减轻开发量

  • 发布到生产环境需在根目录下运行 npm run build 以进行代码合并及压缩

模板变量

  • 如果模板变量的类型是 JSONObject ，其字段属性参考 org.b3log.solo.model 包下的类
  • 每个页面都包含一些公共模板变量，这些模板变量单独列出（不在 *.ftl 表中给出）
  • 每个页面的模板变量如以 Label 结尾，则为多语言配置文件，参看 lang_zh_CN.properties

公共模板变量

⚠️ 某些变量只能在 side.ftl 中使用，其他 ftl 需使用可通过 <#include "side.ftl"> 进行引入

变量 类型 说明
hljsTheme String 代码高亮主题
usite Map 用户站点配置信息
footerContent String 页脚自定义内容
adminUser JSONObject 管理员
userName String 当前登录用户名
isIndex Boolean 判断是否是首页
faviconAPI String 获取 favicon API 地址
isLoggedIn Boolean 用户登录判断
gravatar String 当前登录人的 gravatar 地址
runtimeMode String 运行模式，例如 DEVELOPMENT
runtimeEnv String 运行环境，例如 GAE
pageType String 当前页面类型，例如 Index，Article，DateArticles
servePath String 应用路径，可在 latke.properties 中配置
staticServePath String 静态资源路径，可在 latke.properties 中配置
staticResourceVersion String js, CSS 版本号，防止缓存
topBarReplacement String 公用 top-bar.ftl 内容
path String Action 路径
archiveDates List 存档日期列表
articles List 存档文章列表
blogTitle String 博客标题
blogHost String 博客地址
blogSubtitle String 博客子标题
htmlHead String 用户自定义的 HTML Head
links List 链接列表
localeString String 区域设定字符串
metaKeywords String 用户自定义的关键字
metaDescription String 用户自定义的描述
mostUsedTags List 引用最多的标签列表
noticeBoard String 用户自定义的公告栏
oId String 存档日期对象 Id
pageNavigations List 自定义页面列表
paginationFirstPageNum Integer 文章列表分页第一页页码
paginationLastPageNum Integer 文章列表分页最末页页码
paginationPageNums List 文章列表分页页号
paginationPageCount Integer 文章列表页数
skinDirName String 当前使用的皮肤目录名
statistic JSONObject 统计信息对象
onlineVisitorCnt Integer 在线访客统计数
users List 用户列表
version String 当前使用的 Solo 版本
year String 当前年份
loginURL String 登录 URL
logoutURL String 登出 URL
staticSite Boolean 是否为静态站点

archive-articles.ftl

变量 类型 说明
archiveDate JSONObject 存档日期对象
articles List 文章列表

archives.ftl

变量 类型 说明
archiveDates List 存档列表

article.ftl

变量 类型 说明
article JSONObject 文章对象
articleComments List 文章评论列表
externalRelevantArticlesDisplayCount Integer 站外相关文章显示数
nextArticlePermalink String 下一篇文章链接
nextArticleTitle String 下一篇文章标题
previousArticlePermalink String 上一篇文章链接
previousArticleTitle String 上一篇文章标题

author-articles.ftl

变量 类型 说明
authorName String 用户名

categories.ftl

变量 类型 说明
categories List 分类列表

category-articles.ftl

变量 类型 说明
category JSONObject 分类对象
articles List 文章列表
变量 类型 说明
links List 链接列表

tag-articles.ftl

变量 类型 说明
tag JSONObject 标签对象
articles List 文章列表

tags.ftl

变量 类型 说明
tags List 标签列表

预览下载

官方皮肤

其余 16 个皮肤

社区皮肤

在此感谢 B3log 社区 Solo 爱好者的贡献

全局预览

可直接访问 https://b3log.org/solo ，点击皮肤预览进行查看。

新皮肤推荐

大家可以在 issue #6 下跟帖来推荐皮肤，我们会按点赞数进行参考并融入自己的风格后进行制作。当然，也欢迎大家参考本帖后自行开发。

加入开发

  1. 回贴提供皮肤下载及演示地址
  2. 官方进行测试及反馈
  3. 将皮肤链接加入 https://b3log.org/solo/#themes 官网及本帖中
30 引用
Solo 用户指南 • 88250
Solo 怎么在本地编译启动项目 • PeterChu
修改 solo - Bubble 皮肤 • lonuslan
如何修改博客端 vditor 的配置？ Hexo 主题 Nexmoe 自己画了一个极简的个人博客模板，支持响应式布局。 solo3.3 文章评论问题 开源博客系統 Solo v2.9.9 发布，同步 GitHub 仓库 添加网页播放器 + 全站 pjax 开源博客系統 Solo v2.9.8 发布，支持阿里云 OSS 新人询问帖 Solo 皮肤开发指南 请教一下，nijigen 主题如何做到点击网站内连接不刷新浏览器窗口页面。 Java 开源博客 Solo 2.9.4 发布，新皮肤加数据库重构 Java 开源博客 Solo 2.1.0 发布 Java 开源博客 Solo 2.2.0 发布 Java 开源博客 Solo 2.3.0 发布 Java 开源博客 Solo 2.4.0 发布 Java 开源博客 Solo 2.5.0 发布 Java 开源博客 Solo 2.6.0 发布 Java 开源博客 Solo 2.7.0 发布 Java 开源博客 Solo 2.8.0 发布 Java 开源博客 Solo 2.9.0 发布，支持后台文章搜索 Java 开源博客 Solo 2.9.1 发布，支持 PJAX Java 开源博客 Solo 2.9.2 发布，看板娘来了 Java 开源博客 Solo 2.9.3 发布，可指定移动端皮肤 Java 开源博客 Solo 2.9.4 发布，新皮肤加数据库重构 Java 开源博客 Solo 2.9.5 发布，大量细节优化 开源博客系統 Solo 2.9.6 发布，大量细节优化 开源博客系統 Solo 2.9.7 发布，新皮肤 Jane
7 操作
Vanessa 在 2020-01-19 11:30:02 更新了该帖
Vanessa 在 2020-01-16 16:40:26 更新了该帖
Vanessa 在 2020-01-16 15:10:35 更新了该帖
Vanessa 在 2020-01-14 18:40:38 更新了该帖 Vanessa 在 2019-11-29 23:40:40 更新了该帖 Vanessa 在 2019-08-05 22:30:36 更新了该帖 Vanessa 在 2019-08-05 22:20:39 更新了该帖
昆明 位置
1 感谢
10 关注
5 收藏
3 赞同
30 引用
7 操作
54 回帖
3
2
2
2
41.7k 2.8k 2.8k 3.5k 3 2.5k 1.5k 120 915 27.2k

相关帖子

优质回帖
54 回帖
Solo 皮肤开发指南

欢迎来到这里！

我们正在构建一个小众社区，大家在这里相互信任，以平等 • 自由 • 奔放的价值观进行分享交流。最终，希望大家能够找到与自己志同道合的伙伴，共同成长。

注册 关于
请输入回帖内容 ...
  • kkk •

    imagepng
    这个是写在哪里的啊？

    1 回复
  • 其他回帖
  • lucky • • 1

    好像还有点问题,前三项不会取消菜单,后四项才会

    imagepng

    阅读完第一篇文章,继续阅读第二篇文章的时候,右侧菜单不会更新.

    imagepng

    2 回复
  • zjhch123 • • 2 评论

    发现一个问题可能需要各位皮肤开发者注意一下。

    当皮肤使用 pjax 来加载部分内容时，如果用户在管理后台的 HTML head 中使用了第三方的数据统计服务（比如百度统计、谷歌分析）的话，可能需要在刷新内容之后重新调用数据统计接口来确保当前页面的访问被统计到。数据统计可能会影响搜索引擎的抓取与搜索结果的权重。

    换句话说，如果用户配置了希望在每个页面都被执行的脚本的话，在使用 pjax 的时候需要对页面 url 注册监听，并在其发生改变时触发用户配置的回调。

    @Vanessa 是不是可以针对 pjax 制定一些规范，来保证一些脚本在每次局部刷新的时候都会被加载？

    每个皮肤需要 pjax 的部分不一样，比较难制定规范。
    Vanessa •
    其实问题就在于 pjax 部分差异较大和用户自定义的脚本不可控，的确没有什么好办法…
    zjhch123 •
  • Vanessa •
    订阅者 付费者 作者 MOD

    我去你站点试了下，菜单可以取消的；阅读完第一篇文章, 继续阅读第二篇文章的时候, 右侧菜单也会更新。可以分别给我一下重现步骤么？
    现在发现在自定义页面和文章页面切换目录不会消失。修改详见：https://github.com/b3log/solo-skins/commit/ab99a1c1397a30d5ddae07d5736141815c158f50
    PS：你的播放器好赞。

  • 查看全部回帖
Vanessa MOD
我们终此一生，就是要摆脱他人的期待，找到真正的自己。 昆明
回帖
8926
 帖子
756
 积分
140823