Obsidian Bases

Obsidian Bases 技能

使用场景

• 在 Obsidian 中创建或编辑 .base 文件时使用。
• 用于带有过滤器、公式、汇总或卡片/表格的数据库式笔记视图。
• 当用户明确询问 Obsidian Bases 时使用。

工作流程

1. 创建文件：在保险库中创建一个包含有效 YAML 内容的 .base 文件
2. 定义范围：添加 filters 以选择显示哪些笔记（按标签、文件夹、属性或日期）
3. 添加公式（可选）：在 formulas 部分定义计算属性
4. 配置视图：添加一个或多个视图（table、cards、list 或 map），使用 order 指定要显示的属性
5. 验证：确认文件是有效的 YAML，没有语法错误。检查所有引用的属性和公式是否存在。常见问题：包含特殊 YAML 字符的未加引号字符串、公式表达式中的引号不匹配、引用了 formula.X 但未在 formulas 中定义 X
6. 在 Obsidian 中测试：打开 .base 文件确认视图渲染正确。如果显示 YAML 错误，请检查下面的引号规则

Schema

Base 文件使用 .base 扩展名，包含有效的 YAML。

# Global filters apply to ALL views in the base
filters:
  # Can be a single filter string
  # OR a recursive filter object with and/or/not
  and: []
  or: []
  not: []

# Define formula properties that can be used across all views
formulas:
  formula_name: 'expression'

# Configure display names and settings for properties
properties:
  property_name:
    displayName: "Display Name"
  formula.formula_name:
    displayName: "Formula Display Name"
  file.ext:
    displayName: "Extension"

# Define custom summary formulas
summaries:
  custom_summary_name: 'values.mean().round(3)'

# Define one or more views
views:
  - type: table | cards | list | map
    name: "View Name"
    limit: 10                    # Optional: limit results
    groupBy:                     # Optional: group results
      property: property_name
      direction: ASC | DESC
    filters:                     # View-specific filters
      and: []
    order:                       # Properties to display in order
      - file.name
      - property_name
      - formula.formula_name
    summaries:                   # Map properties to summary formulas
      property_name: Average

过滤器语法

过滤器用于缩小结果范围。可以全局应用，也可以按视图应用。

过滤器结构

# Single filter
filters: 'status == "done"'

# AND - all conditions must be true
filters:
  and:
    - 'status == "done"'
    - 'priority > 3'

# OR - any condition can be true
filters:
  or:
    - 'file.hasTag("book")'
    - 'file.hasTag("article")'

# NOT - exclude matching items
filters:
  not:
    - 'file.hasTag("archived")'

# Nested filters
filters:
  or:
    - file.hasTag("tag")
    - and:
        - file.hasTag("book")
        - file.hasLink("Textbook")
    - not:
        - file.hasTag("book")
        - file.inFolder("Required Reading")

过滤器运算符

属性

三种属性类型

1. 笔记属性 - 来自 frontmatter：note.author 或直接用 author
2. 文件属性 - 文件元数据：file.name、file.mtime 等
3. 公式属性 - 计算值：formula.my_formula

文件属性参考

this 关键字

• 在主内容区域：指 base 文件本身
• 嵌入时：指嵌入该内容的文件
• 在侧边栏：指主内容中的活动文件

公式语法

公式用于从属性计算值。在 formulas 部分定义。

formulas:
  # Simple arithmetic
  total: "price * quantity"

  # Conditional logic
  status_icon: 'if(done, "✅", "⏳")'

  # String formatting
  formatted_price: 'if(price, price.toFixed(2) + " dollars")'

  # Date formatting
  created: 'file.ctime.format("YYYY-MM-DD")'

  # Calculate days since created (use .days for Duration)
  days_old: '(now() - file.ctime).days'

  # Calculate days until due date
  days_until_due: 'if(due_date, (date(due_date) - today()).days, "")'

核心函数

最常用的函数。完整的类型参考（Date、String、Number、List、File、Link、Object、RegExp），请参阅 FUNCTIONS_REFERENCE.md。

Duration 类型

两个日期相减的结果是 Duration 类型（不是数字）。

Duration 字段： duration.days、duration.hours、duration.minutes、duration.seconds、duration.milliseconds

重要提示： Duration 不直接支持 .round()、.floor()、.ceil()。先访问数值字段（如 .days），然后应用数字函数。

# CORRECT: Calculate days between dates
"(date(due_date) - today()).days"                    # Returns number of days
"(now() - file.ctime).days"                          # Days since created
"(date(due_date) - today()).days.round(0)"           # Rounded days

# WRONG - will cause error:
# "((date(due) - today()) / 86400000).round(0)"      # Duration doesn't support division then round

日期算术

# Duration units: y/year/years, M/month/months, d/day/days,
#                 w/week/weeks, h/hour/hours, m/minute/minutes, s/second/seconds
"now() + \"1 day\""       # Tomorrow
"today() + \"7d\""        # A week from today
"now() - file.ctime"      # Returns Duration
"(now() - file.ctime).days"  # Get days as number

视图类型

表格视图

views:
  - type: table
    name: "My Table"
    order:
      - file.name
      - status
      - due_date
    summaries:
      price: Sum
      count: Average

卡片视图

views:
  - type: cards
    name: "Gallery"
    order:
      - file.name
      - cover_image
      - description

列表视图

views:
  - type: list
    name: "Simple List"
    order:
      - file.name
      - status

地图视图

需要经纬度属性和 Maps 社区插件。

views:
  - type: map
    name: "Locations"
    # Map-specific settings for lat/lng properties

默认汇总公式

完整示例

任务跟踪器 Base

filters:
  and:
    - file.hasTag("task")
    - 'file.ext == "md"'

formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'
  is_overdue: 'if(due, date(due) < today() && status != "done", false)'
  priority_label: 'if(priority == 1, "🔴 High", if(priority == 2, "🟡 Medium", "🟢 Low"))'

properties:
  status:
    displayName: Status
  formula.days_until_due:
    displayName: "Days Until Due"
  formula.priority_label:
    displayName: Priority

views:
  - type: table
    name: "Active Tasks"
    filters:
      and:
        - 'status != "done"'
    order:
      - file.name
      - status
      - formula.priority_label
      - due
      - formula.days_until_due
    groupBy:
      property: status
      direction: ASC
    summaries:
      formula.days_until_due: Average

  - type: table
    name: "Completed"
    filters:
      and:
        - 'status == "done"'
    order:
      - file.name
      - completed_date

阅读清单 Base

filters:
  or:
    - file.hasTag("book")
    - file.hasTag("article")

formulas:
  reading_time: 'if(pages, (pages * 2).toString() + " min", "")'
  status_icon: 'if(status == "reading", "📖", if(status == "done", "✅", "📚"))'
  year_read: 'if(finished_date, date(finished_date).year, "")'

properties:
  author:
    displayName: Author
  formula.status_icon:
    displayName: ""
  formula.reading_time:
    displayName: "Est. Time"

views:
  - type: cards
    name: "Library"
    order:
      - cover
      - file.name
      - author
      - formula.status_icon
    filters:
      not:
        - 'status == "dropped"'

  - type: table
    name: "Reading List"
    filters:
      and:
        - 'status == "to-read"'
    order:
      - file.name
      - author
      - pages
      - formula.reading_time

每日笔记索引

filters:
  and:
    - file.inFolder("Daily Notes")
    - '/^\d{4}-\d{2}-\d{2}$/.matches(file.basename)'

formulas:
  word_estimate: '(file.size / 5).round(0)'
  day_of_week: 'date(file.basename).format("dddd")'

properties:
  formula.day_of_week:
    displayName: "Day"
  formula.word_estimate:
    displayName: "~Words"

views:
  - type: table
    name: "Recent Notes"
    limit: 30
    order:
      - file.name
      - formula.day_of_week
      - formula.word_estimate
      - file.mtime

嵌入 Bases

在 Markdown 文件中嵌入：

![[MyBase.base]]

<!-- Specific view -->
![[MyBase.base#View Name]]

YAML 引号规则

• 包含双引号的公式使用单引号：'if(done, "Yes", "No")'
• 简单字符串使用双引号："My View Name"
• 复杂表达式中正确转义嵌套引号

故障排除

YAML 语法错误

未加引号的特殊字符：包含 :、{、}、[、]、,、&、*、#、?、|、-、<、>、=、!、%、@、` 的字符串必须加引号。

# WRONG - colon in unquoted string
displayName: Status: Active

# CORRECT
displayName: "Status: Active"

公式中的引号不匹配：当公式包含双引号时，用单引号包裹整个公式。

# WRONG - double quotes inside double quotes
formulas:
  label: "if(done, "Yes", "No")"

# CORRECT - single quotes wrapping double quotes
formulas:
  label: 'if(done, "Yes", "No")'

常见公式错误

Duration 计算未访问字段：日期相减返回 Duration，不是数字。始终访问 .days、.hours 等。

# WRONG - Duration is not a number
"(now() - file.ctime).round(0)"

# CORRECT - access .days first, then round
"(now() - file.ctime).days.round(0)"

缺少空值检查：属性可能不存在于所有笔记中。使用 if() 进行保护。

# WRONG - crashes if due_date is empty
"(date(due_date) - today()).days"

# CORRECT - guard with if()
'if(due_date, (date(due_date) - today()).days, "")'

引用未定义的公式：确保 order 或 properties 中的每个 formula.X 都在 formulas 中有对应条目。

# This will fail silently if 'total' is not defined in formulas
order:
  - formula.total

# Fix: define it
formulas:
  total: "price * quantity"

参考资料

• Bases 语法
• 函数
• 视图
• 公式
• 完整函数参考

限制

• 仅当任务明确匹配上述范围时使用此技能。
• 不要将输出视为特定环境验证、测试或专家评审的替代品。
• 如果缺少所需输入、权限、安全边界或成功标准，请停下来请求澄清。