obsidian-bases

Obsidian Bases Skill

工作流程

1. 建立檔案：在 vault 中建立內容為有效 YAML 的 .base 檔案
2. 定義範圍：新增 filters 來篩選要顯示的筆記（可依標籤、資料夾、屬性或日期）
3. 新增公式（選填）：在 formulas 區段中定義計算屬性
4. 設定檢視畫面：新增一個或多個檢視畫面（table、cards、list 或 map），並使用 order 指定要顯示的屬性順序
5. 驗證：確認檔案為有效的 YAML 且無語法錯誤。檢查所有被引用的屬性與公式皆已存在。常見問題包括：包含 YAML 特殊字元的字串未加引號、公式運算式中的引號不配對、引用了 formula.X 但未在 formulas 中定義 X
6. 在 Obsidian 中測試：在 Obsidian 中開啟 .base 檔案，確認檢視畫面能正確渲染。若顯示 YAML 錯誤，請檢查下方的引號規則

Schema 結構

Base 檔案使用 .base 副檔名，且包含有效的 YAML 內容。

# 全域篩選條件會套用至 Base 中的所有檢視畫面
filters:
  # 可以是單一篩選字串
  # 或剛好包含單一 key（and、or 或 not）的遞迴篩選物件
  and:
    - 'status == "active"'
    - not:
        - 'file.hasTag("archived")'

# 定義可在所有檢視畫面中使用的公式屬性
formulas:
  formula_name: 'expression'

# 設定屬性的顯示名稱與設定值
properties:
  property_name:
    displayName: "Display Name"
  formula.formula_name:
    displayName: "Formula Display Name"
  file.ext:
    displayName: "Extension"

# 定義自訂摘要公式
summaries:
  custom_summary_name: 'values.mean().round(3)'

# 定義一個或多個檢視畫面
views:
  - type: table | cards | list | map
    name: "View Name"
    limit: 10                    # 選填：限制結果數量
    groupBy:                     # 選填：分組結果
      property: property_name
      direction: ASC | DESC
    filters:                     # 檢視畫面專屬的篩選條件，遵守相同規則
      and:
        - 'status == "active"'
    order:                       # 依順序顯示屬性
      - file.name
      - property_name
      - formula.formula_name
    summaries:                   # 將屬性對映至摘要公式
      property_name: Average

篩選條件語法

篩選條件用來縮小結果範圍，可套用至全域或單一檢視畫面。

篩選結構

# 單一篩選條件
filters: 'status == "done"'

# AND - 必須滿足所有條件
filters:
  and:
    - 'status == "done"'
    - 'priority > 3'

# OR - 滿足任一條件即可
filters:
  or:
    - 'file.hasTag("book")'
    - 'file.hasTag("article")'

# NOT - 排除符合條件的項目
filters:
  not:
    - 'file.hasTag("archived")'

# 巢狀篩選條件
filters:
  or:
    - file.hasTag("tag")
    - and:
        - file.hasTag("book")
        - file.hasLink("Textbook")
    - not:
        - file.hasTag("book")
        - file.inFolder("Required Reading")

篩選運算子

運算子	說明
==	等於
!=	不等於
>	大於
<	小於
>=	大於或等於
<=	小於或等於
&&	邏輯與（AND）
||	邏輯或（OR）
<code>!</code>	邏輯非（NOT）

屬性

三種屬性類型

1. 筆記屬性 — 來自 frontmatter：note.author 或直接寫 author
2. 檔案屬性 — 檔案中繼資料：file.name、file.mtime 等
3. 公式屬性 — 計算產生的值：formula.my_formula

檔案屬性參考表

屬性	類型	說明
file.name	String	檔案名稱
file.basename	String	不含副檔名的檔案名稱
file.path	String	檔案完整路徑
file.folder	String	父資料夾路徑
file.ext	String	檔案副檔名
file.size	Number	檔案大小（位元組）
file.ctime	Date	建立時間
file.mtime	Date	修改時間
file.tags	List	檔案中的所有標籤
file.links	List	檔案中的內部連結
file.backlinks	List	連結至此檔案的背鏈
file.embeds	List	筆記中的嵌入內容
file.properties	Object	所有 frontmatter 屬性

this 關鍵字

• 在主要內容區：指稱 base 檔案本身
• 被嵌入時：指稱嵌入該 Base 的檔案
• 在側邊欄時：指稱主要內容區目前的活動筆記（active file）

公式語法

公式會根據屬性計算數值，定義於 formulas 區段中。

formulas:
  # 簡單算術運算
  total: "price * quantity"

  # 條件邏輯
  status_icon: 'if(done, "✅", "⏳")'

  # 字串格式化
  formatted_price: 'if(price, price.toFixed(2) + " dollars")'

  # 日期格式化
  created: 'file.ctime.format("YYYY-MM-DD")'

  # 計算自建立以來的天數（Duration 請使用 .days）
  days_old: '(now() - file.ctime).days'

  # 計算距離到期日剩餘天數
  days_until_due: 'if(due_date, (date(due_date) - today()).days, "")'

常用函數

最常使用的函數。若要檢視所有型態（Date、String、Number、List、File、Link、Object、RegExp）的完整參考文件，請參閱 FUNCTIONS_REFERENCE.md。

函數	簽章	說明
date()	date(string): date	解析字串為日期 (YYYY-MM-DD HH:mm:ss)
now()	now(): date	目前日期與時間
today()	today(): date	目前日期（時間為 00:00:00）
if()	if(condition, trueResult, falseResult?)	條件判斷
duration()	duration(string): duration	解析時間長度（duration）字串
file()	file(path): file	取得檔案物件
link()	link(path, display?): Link	建立連結

Duration（時間長度）型態

當兩個日期相減時，傳回的結果為 Duration 型態（而非數字）。

Duration 欄位： duration.days、duration.hours、duration.minutes、duration.seconds、duration.milliseconds

重要： Duration 不支援直接呼叫 .round()、.floor() 或 .ceil()。請先存取數值欄位（如 .days），再套用數字函數。

# 正確：計算日期之間的天數
"(date(due_date) - today()).days"                    # 傳回天數（數字）
"(now() - file.ctime).days"                          # 自建立以來的天數
"(date(due_date) - today()).days.round(0)"           # 四捨五入後的天數

# 錯誤 - 將導致錯誤：
# "((date(due) - today()) / 86400000).round(0)"      # Duration 不支援除法後進行 round

日期運算

# Duration 單位：y/year/years、M/month/months、d/day/days、
#                 w/week/weeks、h/hour/hours、m/minute/minutes、s/second/seconds
"now() + \"1 day\""       # 明天
"today() + \"7d\""        # 從今天起算一週後
"now() - file.ctime"      # 傳回 Duration
"(now() - file.ctime).days"  # 取得天數（數字）

檢視畫面類型

表格檢視（Table View）

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

卡片檢視（Cards View）

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

列表檢視（List View）

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

地圖檢視（Map View）

需要經緯度（latitude/longitude）屬性以及 Maps 社群外掛。

views:
  - type: map
    name: "Locations"
    # 地圖專屬的緯度/經度屬性設定

預設摘要公式

名稱	輸入型態	說明
Average	Number	算術平均值
Min	Number	最小值
Max	Number	最大值
Sum	Number	所有數值之和
Range	Number	最大值 - 最小值
Median	Number	中位數
Stddev	Number	標準差
Earliest	Date	最早日期
Latest	Date	最晚日期
Range	Date	最晚 - 最早日期
Checked	Boolean	true 值的數量
Unchecked	Boolean	false 值的數量
Empty	Any	空值的數量
Filled	Any	非空值的數量
Unique	Any	唯一值的數量

完整範例

任務追蹤 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

嵌入 Base

嵌入至 Markdown 檔案中：

![[MyBase.base]]

<!-- 指定特定的檢視畫面 -->
![[MyBase.base#View Name]]

YAML 引號規則

• 若公式中包含雙引號，請使用單引號包覆整條公式：'if(done, "Yes", "No")'
• 一般簡單字串請使用雙引號："My View Name"
• 在複雜運算式中請妥善跳脫（escape）巢狀引號

疑難排解

YAML 語法錯誤

未加引號的特殊字元：包含 :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, ` 等字元的字串必須加上引號。

# 錯誤 - 未加引號的字串中包含冒號
displayName: Status: Active

# 正確
displayName: "Status: Active"

公式中的引號不配對：當公式內部包含雙引號時，請用單引號包覆整個公式。

# 錯誤 - 雙引號內又有雙引號
formulas:
  label: "if(done, "Yes", "No")"

# 正確 - 使用單引號包覆內部包含雙引號的公式
formulas:
  label: 'if(done, "Yes", "No")'

常見公式錯誤

未存取欄位即進行 Duration 運算：日期相減會傳回 Duration，而非數字。在進行數字運算或四捨五入（rounding）前，務必先存取 .days、.hours 等欄位。