技术/教程向

我网站的那些常用组件

温馨提示 本文的大部分组件教程只适用hexo的特定主题（cupertino）。

前言

最近在写一些文章的时候老是要用到一些主题的特有组件，而这主题的官方文档还是英文的不方便查阅，所以我写一篇文章记录一下这些组件的写法。

1. 剧透文字

效果如下：

这是一些文字

实现方式：

这个效果原主题是没有的，本站的剧透文字效果复刻自MrWillCom/MrWillCom.github.io，想要复刻，请在_config.cupertino.yml配置文件中的

1
2
3
insertions:
  head:
    ending: |

中添加如下代码：

1
2
3
4
5
6
7
8
9
10
.spoiler {
        filter: blur(5px);
        opacity: 0.6;
        transition-property: filter, opacity;
        transition-duration: 0.15s;
      }
      .spoiler:hover {
        filter: none;
        opacity: 1;
      }

然后在文章中使用以下写法即可。

1
<span class="spoiler">这里填文字</span>

2. 容器

默认情况下，这个主题的几乎所有组件都没有视口边缘的边距或填充。这让你能够创建超宽的内容，而不受固定宽度限制。所以你必须用 .container 来恢复边距和填充：

实现方法

把你的组件包裹在如下结构内。

1
2
3
<div class="container">
  <!-- 在这里写组件 -->
</div>

3. 按钮

效果如下：

按下导航至锚点或链接

实现方式

1
2
3
<a class="action-button-primary" href="在这里填链接">在这里填显示文字</a>

<button class="action-button-primary">普通按钮</button>

值得注意的是，按钮无需包裹容器。

4. 徽章

效果如下：

Stable

Warning

Secondary

Success

实现方式

1
2
3
4
5
6
7
<span class="badge">Stable</span>

<span class="badge warning">Warning</span>

<span class="badge secondary">Secondary</span>

<span class="badge success">Success</span>

值得注意的是，徽章无需包裹容器。

5. 提示框

效果如下：

Default Your content goes here. Warning Your content goes here. Accent Your content goes here. Success Your content goes here.

实现方式

这里直接给出包裹后的写法。

默认无色

1
2
3
4
5
6
<div class="container">
<htc-callout>
  <span slot="title">Default</span>
  Your content goes here.
</htc-callout>
</div>

黄色

1
2
3
4
5
6
7
<div class="container">
<htc-callout type="warning">
  <span slot="icon"><i class="bi bi-exclamation-triangle-fill"></i></span>
  <span slot="title">Warning</span>
  Your content goes here.
</htc-callout>
</div>

蓝色

1
2
3
4
5
6
7
<div class="container">
<htc-callout type="accent">
  <span slot="icon"><i class="bi bi-palette-fill"></i></span>
  <span slot="title">Accent</span>
  Your content goes here.
</htc-callout>
</div>

绿色

1
2
3
4
5
6
7
<div class="container">
<htc-callout type="success">
  <span slot="icon"><i class="bi bi-check-circle-fill"></i></span>
  <span slot="title">Success</span>
  Your content goes here.
</htc-callout>
</div>

6. 卡片与卡片网格

适合用来展示「一个条目一块卡」的内容，比如开源项目、作品、常用工具等。卡片网格是响应式的：宽屏一行三列、中等宽度两列、手机上单列，无需包裹容器（和按钮、徽章一样自带宽度约束，居中显示）。

效果如下：

RSA CLI

A command line tool for RSA encryption and decryption.

Stable
Learn more
封面图演示，换成你自己的图片链接

带封面图的卡片

这张卡演示了封面图（cardCoverImg）的写法。封面图高度固定 266px，宽图会被等比裁剪居中，鼠标悬停时还有轻微放大效果。

Success

只有内容的卡片

这张卡没有封面图也没有底部操作区，只有标题和描述。同排卡片高度会自动对齐，没有操作区的卡会由内容撑满。

实现方式

卡片由一组配套的标签构成，cardGrid 包整体、card 是一张卡，其余部分按需自由组合、全部可以删减：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{% cardGrid %}
{% card %}
{% cardCoverImg 图片链接 "图片描述" %}          <!-- 封面图，可选 -->
{% cardContent %}
{% cardContentTitle "标题" %}
{% cardContentDescription "描述文字" %}
{% endcardContent %}
{% cardActions %}                            <!-- 底部操作区，可选 -->
{% cardActionsLeft %}
<span class="badge">Stable</span>            <!-- 左半区：通常放徽章 -->
{% endcardActionsLeft %}
{% cardActionsRight %}
<a class="action-button-primary" href="链接">Learn more</a>
{% endcardActionsRight %}                    <!-- 右半区：通常放按钮 -->
{% endcardActions %}
{% endcard %}
{% endcardGrid %}

几个要点：

  • 想放多张卡，就在 cardGrid 里面并列多个 {% card %} ... {% endcard %} 即可。
  • 标题、描述、图片链接这些参数里如果带空格，需要像 "图片描述" 这样用引号包起来。
  • 卡片内容经 nunjucks 渲染，所以里面可以随意混用徽章、按钮、<a> 等前面提到的组件。
  • 卡片里的封面图 cardCoverImg 也可以直接换成 <img> 之类任意 HTML。

7. 轮播

轮播用来横排放一组照片，超出宽度的部分可以横向滚动查看（鼠标按住拖动或触摸滑动，移动端体验更自然）。下面为了演示效果我复用了同一张占位图，实际使用时把每张 src 换成你自己的图片链接即可：

图片描述
这是一张带说明文字的图片

实现方式

1
2
3
4
5
6
7
8
9
10
<div class="container">
<div class="carousel">
  <img src="图片链接1" class="carousel-item" />
  <figure>
    <img src="图片链接2" alt="图片描述" class="carousel-item" />
    <figcaption>这张图的说明文字</figcaption>
  </figure>
  <img src="图片链接3" class="carousel-item" />
</div>
</div>

几个要点：

  • 图片统一高 320px（小屏幕上最多占视口高度的 80%），宽度自适应，figure 和 figcaption 用来给单张图加说明、可选。
  • 纯 CSS 实现，没有任何 JavaScript，代价就是没有自动播放、没有滑动吸附，只能手动横向滚。

8. 工具类

除了组件，主题还提供一些现成的工具类，直接在标签的 class 里加上就能生效：

.block-large 让块级元素突破正文列宽、更宽一些（最大 1000px 居中，视口足够宽时才看得出差别）：

1
2
3
<div class="block-large">
  这里放你想加宽的内容
</div>

.no-select 禁止选中文字（不过按 F12 依然能在开发者工具里看到内容）：

1
<p class="no-select">这段文字无法被选中</p>

.text-left / .text-center / .text-right 控制文本对齐，.text-uppercase / .text-lowercase / .text-capitalize 变换字母大小写（对中文无效，只作用于英文）

效果如下：

这段文字居中（text-center）
这段文字右对齐（text-right）
hello world 大写效果
HELLO WORLD 小写效果
hello world，this is a card 首字母大写效果

参考文献

[1] mrwill. Use Built-in Components[EB/OL]. [2026-09-07]. https://cupertino.mrwillcom.com/guides/use-builtin-components.

本文最后更新于 2026-09-08

About this Post

This post is written by xjhjtzac, licensed under CC BY-NC-SA 4.0.

#website #html #css #js

评论