可视化类组件

可视化类组件负责把笔记中的数量、时间、进度和查询结果转换成更容易阅读的图表。它们适合放在主页上方或侧栏，用来快速回答“最近写了多少”“项目进行到哪里”“哪些资料刚刚更新”等问题。

当前可用组件

一、热力图

热力图把每天的创作量映射到颜色深浅。颜色越深，代表当天记录的数量越多，适合观察长期写作节奏，而不是比较某两天的精确数值。

基础设置

在组件内容设置中选择“可视化 → 热力图”，然后依次设置以下项目。

四种计数方式

数据不正确时怎么处理

热力图的长期统计依赖插件本地索引。如果刚切换统计口径、迁移了大量文档，或某段日期的数据明显缺失，请进入“主页设置 → 检索管理”，刷新或重建相关索引，然后重新打开主页。

二、SQL 查询

SQL 查询组件适合把思源数据库中的文档或内容块筛选成表格。它比“最近文档”和“条件文档”更灵活，但也更需要明确查询范围。

设置步骤

1. 在组件内容设置中选择“可视化 → SQL 查询”。
2. 填写组件标题，例如“最近更新的文档”。
3. 输入 SQL 查询语句，并尽量添加明确的筛选条件和数量限制。
4. 在“列排序”中填写希望优先展示的字段。
5. 在“隐藏字段”中填写不希望显示的原始字段名。
6. 确定后检查结果数量、字段顺序和文档跳转是否符合预期。

一个可以直接修改的示例

下面的查询会找出最近更新的 20 篇文档：

SELECT
  id,
  content,
  hpath,
  box,
  tag,
  created,
  updated
FROM blocks
WHERE type = 'd'
ORDER BY updated DESC
LIMIT 20;

可以把“列排序”设置为：

content,hpath,updated,created,box,tag

如果不想直接展示内部 ID，可以把“隐藏字段”设置为：

id

常用字段

组件会把思源数据库的英文列名转换成更易读的中文表头。

其他可用字段还包括 name、alias、memo、fcontent、length、subtype、ial 和 sort。只有在确实需要时才加入查询，表格列越少越容易阅读。

列排序与隐藏字段

• “列排序”支持中文逗号或英文逗号分隔，可以填写原始英文列名，也可以填写转换后的中文列名。
• “隐藏字段”同样用逗号分隔。为了避免字段名混淆，优先填写 id、path、ial 这类原始英文列名。
• 没有写进“列排序”的字段不会消失，而是排在已指定字段之后。
• 查询 created 或 updated 时，组件会自动格式化为年月日和时分秒。

SQL 学习资料

思源 SQL 实用参考

补充常见查询场景和使用思路。

siyuannote.com

↗

需要核对字段定义时，可以查看 思源数据库表结构参考↗。

三、可视化图表

可视化图表目前提供“进度条”和“标签云图”两种模式。它们共用同一个组件入口，但使用场景不同。

进度条

进度条可以同时放置多个目标，每一项会显示名称、当前值、目标值和完成百分比。

新增进度时，先填写标题，再选择进度类型。

任务进度使用任务的开始日期；没有设置开始日期时，使用任务创建时间。任务必须设置截止日期，否则不会生成进度条。已完成任务不会出现在可选列表中。

已经添加的进度条会保存在当前组件实例中，可以继续添加，也可以单独删除，不会影响其他可视化图表组件。

标签云图

标签云图会自动读取工作空间中的标签。标签使用次数越多，文字通常越大；颜色根据标签名稳定分配，同一个标签刷新后不会随意换色。

• 将鼠标悬停在标签上可以查看名称和数量。
• 点击标签会在思源中打开对应的标签搜索页。
• 图表右上角的下载按钮可以把当前标签云保存为图片。
• 标签较少时字号范围会自动收窄，避免少量标签过度占满画面。

四、统计卡片 👑

统计卡片用于突出一个数字。它不负责展示明细，而是让你进入主页时立刻看到某个关键指标，例如总字数、未完成任务或今日截止任务。

可调整的样式

• 标题文字、标题大小和标题颜色。
• 数字大小和数字颜色。
• 统计类型。
• 选择“SQL 查询结果数”时使用的自定义 SQL。

当前统计类型

“SQL 查询结果数”统计的是查询返回的行数，适合制作“本月新建文档”“带有某标签的资料”“等待处理的项目”等自定义指标。

数字为空或不更新

除自定义 SQL 外，多数统计类型依赖插件的统计索引。如果首次添加后没有数据，或批量迁移文档后数字明显不正确，请进入“主页设置 → 检索管理”刷新或重建索引，再重新载入主页。

组合示例