Atomeocean Logbook

简体中文

English

简体中文

English

主题

The avatar of contributor named as JunmingJunming
The avatar of contributor named as JackJack
The avatar of contributor named as BojianBojian

引用来源组件的使用指南 ​

发表于 2025-07-07
最后修改 2026-06-14
阅读量 —

在Atomeocean文档中，标注引用来源时可以使用<ReferenceSource>组件。该组件可以帮助您规范地展示参考文献、数据来源或外部引用，提升文档的专业性和可信度。

无需 import

ReferenceSource 已在主题中全局注册，任意 Markdown 页面均可直接使用，无需在页面中 import。

基本使用方法 ​

组件只有一个 prop——sources（引用来源数组）。最简单的方式是在标签内直接写入数组：

markdown
<ReferenceSource
:sources="[
{
title: '显示为标题',
link: 'https://',
site: '原站名称',
author: '作者名字',
date: '2021-08-21',
category: '问答'
},
]"
/>

参数说明 ​

sources 数组中的每一项均为一个对象，字段如下（所有字段在技术上均为可选，缺省时按"说明"列中的规则降级显示，但建议至少填写 title 与 link）：

参数名类型是否必填说明
titleString建议引用内容的标题；缺省时显示"未提供标题"
linkString建议引用来源的 URL 链接；存在时渲染"查看原文"按钮，缺省则不显示按钮
siteString否来源网站或出版物名称；缺省时显示"未知来源"
authorString否作者姓名或机构名称
dateString否发布日期，格式为 YYYY-MM-DD
categoryString否内容分类，如"论文"、"新闻"、"问答"等，显示为右上角标签
descriptionString否对该引用的补充说明，显示在标题下方

高级用法 ​

多来源引用 ​

可以同时引用多个来源：

markdown
<ReferenceSource
:sources="[
{
title: '量子计算基础',
link: 'https://example.com/quantum',
site: '科技前沿',
author: '张三',
date: '2022-03-15',
category: '论文'
},
{
title: 'AI发展趋势报告',
link: 'https://example.com/ai-trend',
site: 'AI研究院',
date: '2023-01-10',
category: '报告'
}
]"
/>

部分参数省略 ​

非必填参数可以省略：

markdown
<ReferenceSource
:sources="[
{
title: '简明Python教程',
link: 'https://example.com/python-guide'
}
]"
/>

在 script 中声明数据（推荐用于较多来源） ​

当来源较多时，可以在页面顶部的 <script setup> 中先声明一个数组变量，再通过 :sources="变量名" 绑定，使正文更整洁。显示效果与直接在标签内写数组完全一致，且 ReferenceSource 已全局注册，无需在页面中额外 import。

markdown
<script setup>
const sources = [
  {
    title: '显示为标题',
    link: 'https://example.com',
    site: '原站名称',
    author: '作者名字',
    date: '2021-08-21',
    category: '问答'
  }
]
</script>

<ReferenceSource :sources="sources" />

注意

  • <script setup> 每个页面只需写一处，建议放在文件顶部。
  • 同一页面若有多组引用，请使用各自唯一的变量名（如 const codexSources、const aiTipsSources），避免重复声明 const sources 造成冲突。

通过 frontmatter 传入数据 ​

VitePress 会把页面 frontmatter 暴露为模板全局变量 $frontmatter，因此也可以把来源数据写进 YAML，再直接绑定，无需 <script setup>：

markdown
---
title: 我的文章
references:
  - title: 显示为标题
    link: https://example.com
    site: 原站名称
    author: 作者名字
    date: '2021-08-21'
    category: 问答
---

<ReferenceSource :sources="$frontmatter.references" />

选用建议

该写法可行，但本仓库的约定是优先使用前两种方式（标签内联或 <script setup>）。仅当你确实需要把数据放在 frontmatter 中（例如便于其他工具读取/检索）时，再考虑此方式。

最佳实践建议 ​

  1. 完整性：尽可能提供完整的引用信息，包括作者、发布日期等
  2. 链接有效性：确保提供的链接是可访问的
  3. 格式统一：保持日期等字段的格式一致性
  4. 分类明确：合理使用category字段进行分类

显示效果 ​

该组件会生成格式化的引用卡片，包括

  • 标题与分类标签（位于卡片头部）
  • 补充说明 description（如有）
  • 来源、作者、发布时间等元信息
  • "查看原文"按钮（仅当填写 link 时显示，点击在新标签页打开）

注意事项 ​

  1. 请确保引用来源的合法性
  2. 尊重原作者的版权声明
  3. 对于付费内容，建议注明访问权限要求
  4. 定期检查链接有效性，避免出现死链

如需进一步定制引用样式，请联系系统管理员获取组件样式修改指南。