/notes/plugin/custom-search-readme_full
---
date: 2026-05-13 19:02
updated: 2026-06-01 18:20
---
ᅟ<span class="date">Updated: 2026-06-01 18:20</span>
# 📋 Custom Search Plugin for Obsidian
**custom-search** 是一款 Obsidian 搜索增強插件，無需建立索引(原生索引會引起延遲)，即時搜索，適合需要在大規模筆記庫（數千至數萬文件）中進行精準、高效搜索的用戶。它支持**正則表達式**、**文件範圍自定義**、**文件組/組合管理**、**結果排序**以及**多種結果展示模式**等功能，並將搜索結果顯示在**右側邊欄**，方便快速瀏覽和跳轉。
- 原生搜索 = 每次都在整座圖書館裡檢索，館越大越慢。
- Custom Search = 先把幾本書拿到桌上，只在這幾本裡翻。保持渲染。
此外，插件還提供了**手寫搜索查詢**功能，支持完整的 Obsidian 原生搜索語法，通過**輔助編輯器**進行可視化構建查詢。
https://github.com/arpcn/obsidian-custom-search
## 📑 目錄
- [快速開始](#🚀.快速開始)
- [搜索方式](#🔍.搜索方式)
- [特殊搜索模式](#🔧.特殊搜索模式)
- [管理文件組/組合](#📁.管理文件組/組合)
- [結果面板](#🖱️.結果面板)
- [命令列表](#📖.命令列表)
- [設置說明](#⚙️.設置說明)
- [正則表達式提示](#💡.正則表達式提示)
- [常見問題](#❓.常見問題)
- [技術說明](#🔧.技術說明)
- [更新日誌](#📝.更新日誌)
- [Custom-Search vs Obsidian原生搜索 對比](#📊.Custom-Search.vs.Obsidian原生搜索.對比)
---
## ✨ 主要功能一覽
| 功能類別 | 具體功能 |
| :------- | :------------------------------- |
| 🔍 搜索方式 | 預定範圍搜索、自定義範圍搜索、原生搜索查詢 |
| 📁 範圍管理 | 文件組、組合、默認預定範圍、 |
| 📊 結果顯示 | 三種顯示模式（單行/3行滾動/展開）、條目獨立控制、文件批量控制、分頁加載、折疊/展開 |
| 📈 結果排序 | 文件優先級、組間優先級、組內模式優先級 |
| 🎨 界面自定義 | 顏色自定義（文件名、匹配行、關鍵詞、懸停、模式按鈕、序號文字等） |
| ✍️ 手寫查詢 | Obsidian 搜索語法支持、輔助編輯器、表單可視化 |
| ⌨️ 快捷操作 | 鍵盤導航、右鍵菜單集成、長按歷史菜單 |
![[custom-search.png|400]]
---
## 🚀 快速開始
### 安裝
1. 下載本項目的 `main.js` 和 `manifest.json` 文件。
2. 在 Obsidian 庫的 `.obsidian/plugins/` 目錄下，創建一個名為 `custom-search` 的文件夾。
3. 將下載的兩個文件放入 `custom-search` 文件夾中。
4. 在 Obsidian 中，進入 `設置` → `第三方插件`，**禁用安全模式**。
5. 在已安裝插件列表中，啟用 `Custom Search` 插件。
### 基本使用流程
1. **打開搜索面板** — 使用命令或右鍵菜單，選擇`搜索面板`
2. **輸入搜索內容** — 手動輸入，或從歷史下拉中選擇（有選中文本時會自動填入）
3. **選擇範圍** — 使用預定範圍，或自定義正則（可加載已有文件組）
4. **執行搜索** — 結果顯示在右側邊欄
5. **點擊跳轉** — 點擊結果跳轉（Ctrl+點擊在新標籤頁打開）
> 💡 **快速搜索**：選中文本後使用右鍵`預設範圍快搜`，一鍵執行。
---
## 🔍 搜索方式
### 方式一：預定範圍搜索
使用預設的文件模式進行快速搜索。
- 「初始默認預定範圍」可在設置中配置
- 可將文件組或組合設為「臨時默認預定範圍」，設置後「預定範圍」按鈕會顯示 ⭐ 標記
- 適用於經常在固定範圍內搜索的場景
- 點擊「預定(原生)」按鈕可轉為 Obsidian 原生搜索
### 方式二：自定義範圍搜索
手動指定文件名匹配模式，在匹配的文件中搜索內容。
- **文件名匹配**：單行輸入框支持多行模式（點擊後自動展開），每行一個正則表達式，支持包含/排除規則
- **內容搜索**：支持普通文本或正則表達式（自動檢測 `+*?|()[]{}` 字符）
- **排除規則**：以 `!` 開頭的行表示排除匹配該模式的文件（支持轉義 `\!` 匹配字面感嘆號）
- **修改版標記**：如果應用了文件組/組合後又修改了編輯區內容，按鈕會顯示「已修改」標記
- 點擊「自定義(原生)」按鈕可轉為 Obsidian 原生搜索
#### 包含/排除規則示例
```
# 包含規則（正常匹配）
^(集異門|法蘊|品類|識身)足論\.md
(婆沙|正理|本義抄)\d+-\d+\.md
# 排除規則（以 ! 開頭）
!.+疏22\.md
!^vibhasa\/others\/
!.*甘露味.*\.md
```
插件支持四種搜索模式：
- **包含模式** (`include-only`)：只匹配包含規則的文件
- **排除模式** (`exclude-only`)：從所有文件中排除匹配排除規則的文件
- **排除優先** (`exclude-first`)：先排除，再選取包含
- **包含優先** (`exclude-last`)：先選取包含，再從中排除
包含/排除模式自動檢測邏輯
| 模式 | 條件 | 行為 |
|:---|:---|:---|
| `include-only` | 只有包含規則 | 只匹配包含規則的文件 |
| `exclude-only` | 只有排除規則 | 從所有文件中排除匹配排除規則的文件 |
| `exclude-first` | 有包含規則，且第一個包含行之前有排除行 | 先排除，再選取包含 |
| `exclude-last` | 有包含規則，且第一個包含行之後有排除行 | 先選取包含，再從中排除 |
> 💡 **提示**：排除行（以 `!` 開頭）建議統一放在所有包含行的**最前面**（先排除後包含）或**最後面**（先包含後排除），以確保過濾順序符合預期。
### 方式三：原生搜索查詢
- 前兩種方式均可自動轉換成**原生搜索**，填入 Obsidian 搜索框並自動執行搜索。
- **手寫模式**：直接編寫 Obsidian 原生搜索語法，利用 Obsidian 內置的搜索功能。
- **輔助編輯器**：可視化構建查詢，無需記憶複雜語法。
原生搜索適用場景：
- 使用複雜的搜索條件組合（AND/OR/NOT）
- 搜索特定類型的內容（任務、區塊、章節等）
### 三種方式對比
| 方式 | 優點 | 適用場景 |
|:---|:---|:---|
| 預定範圍 | 快速、配置固定 | 日常頻繁使用的搜索範圍 |
| 自定義範圍 | 靈活、精準控制 | 臨時需要調整搜索範圍 |
| 原生搜索 | 功能最強大 | 複雜條件組合搜索 |
---
## 🔧 特殊搜索模式
在「搜索面板」對話框內容搜索中，提供了三個輔助搜索模式開關，可根據需要靈活組合使用。
💡 ①布爾模式：空格 & = AND;ᅠ | = OR;ᅠ ! = NOT;ᅠ ( ) = 分組\n\n
💡 ②無視標籤：忽略 HTML 標籤、MD語法及標點符號
💡 ③忽略變音：忽略九組變音符號（a/ā/â等）
📖 ④正則模式：標識 * + ? $ { } \ [ ]
🚫 注意：①②④ 三者互斥，①③互斥
### 布爾查詢
啟用後，搜索內容支持簡潔的邏輯運算符語法：
```
佛性 & 眾生 # 空格 或 & → AND 包含「佛性」且包含「如來藏」
佛性 | 如來藏 # | → OR 包含「佛性」或「如來藏」
佛性 !外道 # ! → NOT 包含「佛性」但不包含「外道」
(佛性|如來藏) 眾生 # ( ) → 分組 包含（佛性或如來藏）且包含「眾生」
```
**注意事項**：
> ⚠️ 與原生搜索不同：原生用空格表示 OR，本插件空格表示 AND
- 💡 此功能僅在「普通文本模式」下生效（未勾選無視標籤、忽略變音，且搜索內容不包含正則特殊字符）
### 無視標籤
啟用「無視標籤」後，插件會自動忽略 HTML 標籤、MD語法和標點符號，實現跨標籤的文本匹配。
| 功能維度 | Custom Search | 其他搜索插件 (Omnisearch, Clever 等) |
| ----------- | --------------------------------------------------- | ------------------------------------------------------------ |
| **處理機制** | **預處理**（先解析 Markdown/HTML，提取純文字，再比對） | **分詞/模糊匹配**（在帶有符號的原文上進行模糊比對） |
| **HTML 標籤** | ✅ **完整跳過**（如 `<font color="red">重要</font>` -> `重要`） | ❌ 視為普通字元或無法處理 [](https://forum-zh.obsidian.md/t/topic/52938) |
| **精確比對** | ✅ **精確**（刪除標籤後，必須字字匹配） | ❌ **模糊**（只能透過相似度「猜測」，可能誤判） |
**使用場景**：
- 筆記中包含 HTML 標籤（如 `<b>`、`<i>`、`<span>` 等）、MD語法（如 `~*_=[]!()^ 等），希望忽略這些標籤直接匹配文本內容
- 文本中包含標點符號（如逗號、句號、頓號等），希望忽略符號差異進行匹配
**工作原理**：
在搜索關鍵詞的每個字符之間，自動插入 `(?:<[^>]*>|\p{P}|\p{S}|\p{Zs}){0,3}` 模式，最多允許跳過 3 個標籤或標點符號。
**示例**：
```
原文：佛<b>即</b>知，子曹疑
搜索：佛即知子曹疑
結果：✅ 匹配成功（`<b>` 和 `，` 被忽略）
```
**注意事項**：
- 💡 此功能僅在「普通文本模式」下生效（未勾選布爾查詢，且搜索內容不包含正則特殊字符）
### 忽略變音
啟用「忽略變音」後，插件會自動處理帶變音符號的字符，實現忽略變音符號（diacritics）的匹配。
- 💡 原生搜索中並沒無有效的`diacritics`語法。
**支持的字符家族**：
| 家族 | 互換字符 |
| :--- | :--- |
| a 家族 | a, ā, â |
| i 家族 | i, ī, î |
| u 家族 | u, ū, û |
| s 家族 | s, ṣ, ś |
| t 家族 | t, ṭ |
| d 家族 | d, ḍ |
| n 家族 | n, ṇ, ñ, ṅ |
| m 家族 | m, ṃ |
| h 家族 | h, ḥ |
**示例**：
```
原文：śūnyatā（空性）
搜索：sunyata
結果：✅ 匹配成功（ś→s, ū→u, tā→ta）
```
**注意事項**：
- ✅ 同時支持正則模式和普通文本模式
- ✅ 與「無視標籤」可以同時啟用
- 💡 此功能與「布爾查詢」互斥
### 互斥關係說明
「無視標籤」「布爾查詢」「正則模式」三者互斥。
「忽略變音」可以與「正則模式」共用，也可以與「無視標籤」共用。
「忽略變音」與「布爾查詢」互斥。(如果「忽略變音」與「布爾查詢」同時使用，在「前瞻斷言」和「零寬斷言」這類語法中應用「忽略變音」轉換，搜索結果的高亮，沒法直接顯示。所以需要加互斥邏輯。)
互斥矩陣是：
| 模式1 | 模式2 | 是否兼容 |
| ---- | ---- | ---- |
| 布爾查詢 | 無視標籤 | ❌ 互斥 |
| 布爾查詢 | 忽略變音 | ❌ 互斥 |
| 布爾查詢 | 正則模式 | ❌ 互斥 |
| 無視標籤 | 正則模式 | ❌ 互斥 |
| 無視標籤 | 忽略變音 | ✅ 兼容 |
| 正則模式 | 忽略變音 | ✅ 兼容 |
根據上述規則，可以同時使用的功能組合是：
| 組合 | 布爾查詢 | 無視標籤 | 忽略變音 | 正則模式 |
| --- | ---- | ---- | ---- | ---- |
| 1 | ✅ | ❌ | ❌ | ❌ |
| 2 | ❌ | ✅ | ❌ | ❌ |
| 3 | ❌ | ❌ | ✅ | ❌ |
| 4 | ❌ | ❌ | ❌ | ✅ |
| 5 | ❌ | ✅ | ✅ | ❌ |
| 6 | ❌ | ❌ | ✅ | ✅ |
---
## 📁 管理文件組/組合
![[2026-04-30-1552.png|600]]
### 文件組 (Group)
由多個正則表達式模式組成的集合，支持包含/排除規則。
```
# 示例：俱舍論相關文件組
(俱舍論|AKBh)\d+\.md
^kosa\/ju\/
俱舍論記疏\d+\.md
!.+疏22\.md # 排除包含「疏22」的文件
```
操作：
- 創建/刪除文件組
- 編輯組內正則模式（每行一個，支持註釋 `#`，支持排除規則 `!`）
- 點擊組標題可折疊/展開
### 組合 (Combination)
將多個文件組組合成一個更大的範圍。
操作：
- 創建/刪除組合
- 從文件組列表中選擇添加到組合
- 已加入的組以標籤形式顯示，支持單獨移除
### 應用選項
| 選項 | 功能 |
|:---|:---|
| ⭐ 設為臨時默認預定範圍 | 將選中的文件組/組合作為臨時默認搜索範圍 |
| 🗑️ 清除臨時默認 | 清除已保存的臨時默認預定範圍，恢復初始設置 |
| 🔍 應用為自定義範圍（本次搜索） | 將模式填充到主窗口編輯區，並顯示「📌」標記（可繼續微調） |
| ✍️ 寫入手寫搜索查詢區 | 生成 Obsidian 原生搜索查詢語法，自動填入「手寫搜索查詢」對話框 |
⭐將任意文件組或組合設為臨時默認預定範圍後：
- 「快速預設範圍搜索」命令直接使用此範圍
- 「搜索面板」中的「預定範圍」選項使用此範圍，並顯示 ⭐ 標記
- 點擊「清除臨時默認」可恢復使用「初始默認預定範圍」
---
#### ✍️ 手寫搜索查詢對話框
提供兩種編輯模式：
##### 手動編輯模式
直接編寫 Obsidian 原生搜索語法。
支持的語法示例：
```
line:(佛即知子曹疑) file:/義足經/
line:/為顯自師[，\.]?其體尊高.*故先讚德/ path:^kosa/ju/
(tag:#哲學) (file:思考筆記.md)
```
##### 輔助編輯模式
通過表單可視化構建搜索查詢：
- **搜索類型**：all / file / path / tag / content / line / block / section / task / task-todo / task-done
- **搜索內容**：輸入關鍵詞或正則表達式
- **邏輯運算符**：AND / OR / NOT（第一行無運算符）
- **修飾符**：
- 🔤 大小寫敏感（match-case）
- ◌̈ 區分變音符號（diacritics）（實測無用）
- .* 正則表達式（regex）
- **快捷填充**：點擊類型旁的圖標 📁，可從 vault 中選擇文件/標籤/路徑快速填入
- **生成查詢**：點擊「✍️ 轉入編輯」將生成的查詢語法填入手動編輯區
- **重置表單**：清空所有條件，恢復初始狀態
### 預定範圍標籤頁
設置插件的「初始默認預定範圍」文件模式。這是「快速預設範圍搜索」和「預定範圍」按鈕的基礎範圍。
---
## 🖱️ 結果面板
### 基本操作
| 操作 | 效果 |
|:---|:---|
| 點擊結果行 | 跳轉到對應文件的行，並高亮選中關鍵詞 |
| `Ctrl` + 點擊 | 在新標籤頁打開 |
| 點擊左側序號 | 循環切換該條目顯示模式（A→B→C→A） |
| 全局 A/B/C 按鈕 | 切換所有結果的默認顯示模式 |
| Top 按鈕 | 滾動到面板頂部 |
| ⟳ 刷新按鈕 | 直接重新執行當前搜索，不打開對話框，不保存歷史 |
| 重新搜索按鈕 | 打開搜索對話框，載入當前搜索設置，可修改後重新搜索 |
### ⌨️ 鍵盤導航
在結果面板獲得焦點時，可以使用以下快捷鍵：
| 快捷鍵 | 功能 |
| :------------------ | :------------ |
| `↑` / `↓` | 選擇上一個/下一個搜索結果（支持循環） |
| `Enter` | 跳轉到當前選中的結果 |
| `Home` / `End` | 跳轉到第一個/最後一個結果 |
| `Escape` | 清除當前選中結果的焦點，將焦點轉移到面板容器 |
| `Ctrl+←` / `Ctrl+→` | 切換上一條/下一條搜索歷史 |
| `Ctrl+\` | 顯示搜索歷史列表（快捷鍵方式） |
> 💡 提示：點擊結果面板任意位置後即可使用鍵盤導航；按 Escape 可將焦點轉移到面板容器。
### 📊 搜索結果顯示（三種模式）
| 模式 | 顯示方式 | 適用場景 |
|:---|:---|:---|
| **A (單行)** | 只顯示匹配行，動態截取適應面板寬度 | 快速瀏覽，節省空間 |
| **B (3行+滾動)** | 顯示匹配行及其前後各一行，固定高度 | 需要上下文參考 |
| **C (展開)** | 顯示匹配行及其前後各一行，完全展開 | 需要完整上下文 |
| 切換操作 | 效果 |
| :------------------- | :--------------------------- |
| 點擊頂部 A/B/C 按鈕 | 全局切換，一次性設置所有結果的默認顯示模式 |
| 懸浮文件頭「«」按鈕 → 選 A/B/C | 批量設置當前文件下所有結果的模式 |
| 點擊每個結果左側的序號 | 獨立切換該條目的模式（循環：A → B → C → A） |
### 📄 文件折疊
當搜索結果較多時，可以折疊不需要查看的文件，專注於感興趣的內容。
| 操作 | 效果 |
|:---|:---|
| 點擊文件頭右側的 `▼` / `▶` 按鈕 | 折疊/展開該文件下的所有搜索結果 |
| 點擊頂部工具欄的 `▶` 按鈕（全部折疊） | 折疊所有已加載文件的結果 |
| 點擊頂部工具欄的 `▼` 按鈕（全部展開） | 展開所有已加載文件的結果 |
折疊狀態會自動保存，重新搜索或刷新面板後仍會保持。
> 💡 提示：折疊後的文件仍然會佔用已加載數量統計，但不會顯示在面板中，頂部統計欄會顯示折疊條數。
### 📦 分頁加載
為提升大量搜索結果（數千條）時的渲染性能，插件採用分批加載策略：
| 顯示模式 | 每批加載數量 |
|:---|:---|
| A 模式（單行） | 100 條 |
| B 模式（3行+滾動） | 40 條 |
| C 模式（展開） | 40 條 |
- **首次加載**：只加載第一批結果，快速響應
- **加載更多**：滾動到底部，點擊「➕ 加載更多」按鈕，按順序加載下一批結果
- **自動擴展**：新加載的文件如尚未在面板中，會自動創建對應的文件區域
- **動態調整**：切換全局模式時，批次大小會自動調整（如從 C 模式切換到 A 模式，批次從 40 增加到 100）
頂部統計欄會實時顯示當前加載狀態：`已加載數/總結果數`，如有折疊文件會額外顯示 `(折疊X條)`。
### 📜 搜索歷史
插件會自動保存每次主動搜索的記錄，方便回溯和重複使用。
#### 圖形化操作
| 操作 | 說明 |
| :----------- | :------------ |
| 點擊 `❮` / `❯` | 切換上一條/下一條搜索歷史 |
| 長按 `❮` / `❯` | 顯示歷史列表面板（長按 300ms） |
| 點擊歷史列表中的條目 | 加載該歷史並重新搜索 |
| 點擊歷史列表中的 `✕` | 刪除該條歷史記錄 |
| 點擊「清除所有歷史」 | 清空全部搜索歷史 |
| 鍵盤導航（歷史面板內） | `↑`/`↓` 選擇，`Enter` 加載，`Escape` 關閉 |
#### 快捷鍵操作
| 快捷鍵 | 功能 |
| :-------- | :---------- |
| `Ctrl+←` | 上一條搜索歷史（更舊） |
| `Ctrl+→` | 下一條搜索歷史（更新） |
| `Ctrl+\` | 顯示歷史列表面板 |
#### 歷史面板功能
- 半透明毛玻璃效果背景
- 顯示當前位置（如 `(2/10)`）
- 當前激活條目高亮顯示
- 支持鍵盤導航（`↑`/`↓` 移動，`Enter` 加載）
- 鼠標懸停時自動退出鍵盤導航模式
---
## 📖 命令列表
| 命令名稱 | 右鍵菜單 | 說明 |
|:---|:---|:---|
| 搜索面板 | ✅ | 打開完整的搜索模式選擇對話框 |
| 快速預設範圍搜索 | ✅ | 使用默認預定範圍直接執行搜索 |
| 打開結果面板 | ❌ | 打開或聚焦到右側的搜索結果面板 |
| 管理文件組/組合 | ❌ | 打開文件組和組合的管理界面 |
---
## ⚙️ 設置說明
打開設置 → custom-search 插件，共有 5 個選項卡：
![[2026-04-30-1411.png|600]]
---
### 1. 搜索設置
| 設置項 | 說明 |
|:---|:---|
| 默認顯示模式 | A（單行）或 B（3行+滾動）或 C（展開） |
| 布爾查詢（默認值） | 全局默認是否開啟布爾查詢模式 |
| 無視標籤（默認值） | 全局默認是否開啟無視標籤模式 |
| 忽略變音（默認值） | 全局默認是否開啟忽略變音模式 |
**默認搜索範圍（初始預定範圍）**
設置「快速預設範圍搜索」使用的初始預定文件名模式，每行一個正則表達式。支持註釋行（`#` 開頭）。
---
#### 字符寬度自定義設置
用於 A 模式（單行）的動態文本截取，讓用戶自定義哪些字符視為「窄字符」或「零寬度字符」。
| 設置項 | 說明 |
| :--- | :--- |
| 窄字符（每個字符折算 0.2 單位） | 每行一個 Unicode 碼位或範圍（如 `0x0F08` 或 `0x0F0B-0x0F0D`） |
| 零寬度字符（不計寬度） | 每行一個 Unicode 碼位或範圍，這些字符在計算寬度時完全跳過 |
**支持格式**：
- 單個碼位：`0x0F08`
- 碼位範圍：`0x0F0B-0x0F0D`
**使用場景**：
- 藏文等複雜文本的組合字符（如 `0x0F71-0x0F7E` 藏文元音符號、疊加字符等）
- 特殊標點符號（如 ༈ ་ ། 等）
- 梵文天城體中的休止符（्）等
**默認配置**：
- 窄字符：藏文分隔符、特殊標點等
- 零寬度字符：藏文元音符號、天城體休止符等
> 💡 如果 A 模式下的文本截取出現異常（如字符顯示不全或留有大量空白），可以通過此設置調整字符寬度計算規則。
---
### 2. 優先級設置
啟用排序後，搜索結果按以下優先級排列：
| 優先級 | 名稱 | 說明 |
|:---|:---|:---|
| 1 | 文件優先級 | 匹配正則的文件/路徑優先顯示（按行順序） |
| 2 | 文件組間優先級 | 拖拽調整組的顯示順序（越靠上越優先） |
| 3 | 文件組內模式優先級 | 調整組內正則行的匹配順序（越靠上越優先） |
| 4 | 默認順序 | 行號、文件名等 |
#### 文件優先級示例
```
# 優先顯示這些路徑/文件
^kosa\/ju\/
^重要/
核心概念\.md
# 次優先顯示
^nofa\/ji\/
參考資料\.md
```
#### 組間優先級
在設置頁面中，通過拖拽左側 `⋮⋮` 按鈕調整文件組的顯示順序（點擊 ↑/↓ 按鈕調整）。
#### 組內模式優先級
展開每個文件組，拖拽調整正則行的順序（點擊 ↑/↓ 按鈕調整），匹配順序會影響結果顯示。點擊「重置該組順序」可恢復為默認順序。
#### 保存與重置
- **💾 保存排序設置到文件組**：將當前的文件組間順序和組內模式順序寫入文件組的初始順序（會修改 `data.json` 中的模式排列）
- **🔄 重置所有排序設置**：清空所有排序配置，恢復默認狀態（文件組初始順序不變，需重新保存排序才能固化）
- **📁 管理文件組/組合**：快速跳轉到文件組管理界面
### 3. 歷史管理
| 設置項 | 說明 |
|:---|:---|
| 最大保存歷史數 | 設置歷史記錄上限（1-100），超出時自動截斷 |
| 歷史面板寬度 | 設置歷史列表彈窗寬度（200-600px） |
| 清除所有歷史 | 清空全部歷史記錄，重置當前索引為 -1 |
| 歷史列表 | 顯示所有歷史條目（搜索文本預覽 + 範圍顯示），支持單獨刪除 |
### 4. 顏色外觀
所有顏色均支持 RGBA 格式（紅、綠、藍、透明度），提供多種配置方式：
- **顏色選擇器**：直觀選取顏色（十六進制）
- **透明度滑塊**：調整透明程度（0-100%）
- **手動輸入框**：直接輸入 `rgba(r, g, b, a)` 或 `#RRGGBB` 格式，錯誤時恢復原值
- **實時預覽**：色塊實時顯示當前顏色
- **實時生效**：修改後立即刷新結果面板
#### 可自定義的顏色項
| 類別 | 顏色項 | 說明 |
|:---|:---|:---|
| 基礎顏色 | 文件名顏色 | 搜索結果中文件名的顏色 |
| | 匹配行背景色 | 匹配行的背景顏色（B/C 模式） |
| | 關鍵詞高亮背景色 | 搜索關鍵詞的高亮背景顏色 |
| | 懸停背景色 | 鼠標懸停時的行背景顏色 |
| 模式按鈕 | 模式 A/B/C 按鈕顏色 | 三種模式的按鈕背景色 |
| | 激活模式外框顏色 | 當前激活的全局模式按鈕的外框顏色 |
| 序號文字 | A/B/C 模式序號文字顏色 | 每種模式下序號數字的文字顏色 |
點擊「重置所有顏色為默認值」可恢復所有顏色設置。
### 5. 說明
顯示插件命令列表（含右鍵菜單標記）和正則表達式提示。
---
## 💡 正則表達式提示
正則模式，帶標識：`* + ? $ { } \ [ ]`
### 基本規則
| 規則 | 說明 |
|:---|:---|
| `\d` | 匹配數字 |
| `\d+` | 匹配一個或多個數字 |
| `\.` | 匹配點號（需要轉義） |
| `(A\|B)` | 匹配 A 或 B |
| `^` | 匹配開頭 |
| `$` | 匹配結尾 |
| `\/` | 匹配路徑分隔符（需要轉義） |
### 路徑匹配注意事項
在 Obsidian 中匹配路徑時，正則表達式中的 `/` 需要轉義為 `\/`：
```
✅ 正確：^kosa\/ju\/
❌ 錯誤：^kosa/ju/
```
### 排除規則
以 `!` 開頭的行表示排除匹配該模式的文件：
```
!.+疏22\.md # 排除文件名包含「疏22」的文件
!^vibhasa\/others\/ # 排除 vibhasa/others/ 路徑下的文件
```
如需匹配以感嘆號開頭的模式，使用轉義 `\!`：
```
\!important # 匹配以「!important」開頭的內容
```
---
### 註釋與空白
#### 文件名匹配
- 以 `#` 開頭的行會被忽略，可用於添加說明
- 行首的空格和製表符會被自動忽略（`trim()` 處理），如需匹配開頭空格和製表符請使用 `\s` `\t`
```
# 阿含部經典
(長阿含|中阿含|雜阿含|增一阿含)\.md
# 論藏文獻
(大毘婆沙|順正理論|俱舍論)\.md
```
#### 內容搜索
內容搜索中，開頭空格、`#`、`^` 等字符都可以直接正常使用，無需特殊處理。
**普通文本模式**（未勾選「布爾查詢」時）：
```
#普通文本
#定義區塊 ^block-id
#引用區塊 #^block-id
[[筆記#^block-id]]
[文字](網址#^block-id)
#標籤 #targ-id
```
**正則模式**（未勾選「布爾查詢」，且內容包含 `+*?${}()|[\]\\` 等符號時自動啟用）：
```
#定義區塊
\s\^block-id
#引用區塊
#\^block-id
\[\[.*?#\^block-id\]\]
\[[^\]]+\]\([^\)]+#\^block-id\)
#標籤
#targ-id
```
> ⚠️ 注意：布爾查詢模式下，`+*?${}()|[\]\\` 等符號視為普通字符，不會觸發正則模式。
---
### 文件名模式示例
```
# 純文件名匹配
^(集異門|法蘊|品類|識身)足論\.md
(婆沙|正理|本義抄)\d+-\d+\.md
(心論雜心|AKBh)\d+\.md
^(甘露味論|入阿毘達磨論)\.md
俱舍論記疏\d+\.md
^俱舍論頌疏\d+-\.md
頌疏注釋對照.*\.md
俱舍所依阿含\.md
成實論\.md
陰持入經註?.md
# 路徑匹配
^kosa\/ju\/
^kosa\/ju\/俱舍.+\.md
^agama\/[^\/]+\.md
# 藏經編號
T22n1428_四分律\d+\.md
T30n1579_瑜伽師地論\d+\.md
T25n1509_大智度論\d+\.md
T44n1851_大乘義章\d+\.md
# 排除規則
!.+疏22\.md # 排除包含「疏22」的文件
!^vibhasa\/others\/ # 排除該路徑下的所有文件
```
---
## ❓ 常見問題
**Q: 搜索結果不顯示？**
A: 確保文件名模式匹配到了文件，且文件中包含搜索關鍵詞。檢查正則語法是否正確。可查看控制台是否有錯誤信息。
**Q: 正則表達式報錯？**
A: 檢查正則語法，注意路徑中的 `/` 需要轉義為 `\/`，特殊字符需要轉義。錯誤時會有通知提示具體原因。
**Q: 排序不生效？**
A: 檢查「啟用結果排序」是否已開啟，且已配置相應的優先級規則。注意「文件優先級」規則優先級最高，會使匹配文件成為「優先文件」，無視後續排序規則（組間優先級、組內模式優先級只對普通文件生效）。
**Q: 如何恢復默認設置？**
A: 在設置頁面「顏色外觀」標籤頁點擊「重置所有顏色為默認值」；在「優先級設置」標籤頁點擊「重置所有排序設置」；在「管理文件組/組合」中點擊「清除臨時默認」；在「搜索設置」中可手動重置默認文件模式。
**Q: 文件組/組合數據保存在哪裡？**
A: 保存在 Obsidian 插件文件夾下的 `data.json` 中。插件版本更新時（版本不匹配）會自動備份舊配置（文件名：`data.json.backup.v{舊版本號}.{時間戳}.json`），並重置為默認配置，彈窗提示備份路徑。
**Q: 結果面板中的鍵盤導航不起作用？**
A: 請確保先點擊結果面板區域（或按 Tab 鍵聚焦），使其獲得焦點，然後再使用方向鍵。檢查是否有其他元素搶佔了焦點。
**Q: 包含/排除規則如何工作？**
A: 插件根據規則的出現順序自動判斷模式：僅包含規則 (`include-only`)、僅排除規則 (`exclude-only`)、先排除後包含 (`exclude-first`)、先包含後排除 (`exclude-last`)。如果同時存在包含和排除規則，會根據第一個包含行之後是否有排除行來決定順序。
> 💡 提示：排除行（以 `!` 開頭）建議統一放在所有包含行的**最前面**（先排除後包含）或**最後面**（先包含後排除），以確保過濾順序符合預期。混亂排列可能導致意外的過濾結果。
---
## 🔧 技術說明
- **視圖重建優化**：`refreshDisplay()` 方法增加 `forceRebuild` 參數，模式切換時傳入 `true` 強制重建，寬度變化時傳入 `false`（默認），避免側邊欄折疊/展開時已加載的結果被清空
- **累積單位寬度計算**：A 模式使用一次遍歷構建累積單位數組，結合二分查找快速定位截取邊界，避免多次遍歷和窄字符重調邏輯，提升性能和精度
- **位置映射截取**：基於可見字符串計算截取邊界後，通過 `displayToOriginal` 映射表轉換為原始字符串位置，確保截取結果保留所有原始 Markdown 語法字符，僅在寬度計算時跳過不可見標記
- **A 模式可見字符串構建**：通過 `buildVisibleStringWithMapping()` 函數使用狀態機遍歷原始行內容，識別並跳過以下不可見元素：
- 白名單 HTML 標籤（`<b>`、`<i>`、`<a>`、`<span>` 等，不佔寬度）、HTML 註釋（`<!-- -->`）、MD 語法鏈接 URL 部分（`[text](url)` 中的 `(url)`）
- 自定義高亮標記（`==[` 和 `==\[` 開頭，`]==` 結尾）
- 同時建立原始字符與可見字符的位置映射關係，確保截取後保留完整原始語法
- **鏈接 URL 關鍵詞檢測與轉義**：在 `getContextLines()` 中調用 `escapeLinkIfKeywordInUrl()`，使用正則匹配 `[文本](url)` 結構，檢測 URL 是否包含搜索關鍵詞（支持普通文本、正則、布爾查詢三種模式），若包含則在 `[` 前添加 `\` 轉義，使鏈接以純文本形式顯示
- **不成對元素清理**：在 A 模式截取完成後，調用 `removeUnpairedTagsAndMarkers()` 函數清理截取結果中不成對的元素：
- 白名單 HTML 標籤：移除只有開始標籤沒有結束標籤（或反之）的孤立標籤
- 自定義高亮標記：移除只有 `==[`/`==\[` 沒有 `]==` 的開頭標記，以及單獨出現的 `]==` 結尾標記
- **刷新按鈕**：在結果面板統計信息欄右側提供 `⟳` 圖標按鈕，點擊後直接復用當前視圖中保存的所有搜索參數，調用 `searchAndShowInSidebar()` 重新執行搜索，`skipHistorySave` 設為 `true` 不保存到歷史記錄，不顯示 Notice 提示，實現快速刷新
- **無視標籤**：在普通文本模式的每個字符之間插入 `(?:<[^>]*>|\p{P}|\p{S}|\p{Zs}){0,6}` 模式，最多跳過 6 個標籤、MD語法或標點符號，實現跨標籤匹配
- **忽略變音**：將九組字符互轉為字符組正則，實現雙向匹配
- **互斥機制**：布爾查詢 ↔ 無視標籤 / 正則模式 ↔ 無視標籤 兩組互斥關係，通過 UI 狀態聯動和自動關閉實現
- **布爾查詢**：生成兼容的正則表達式
- **排除規則解析**：支持三種排除（純包含、純排除、先排除後包含、先包含後排除），以 `!` 開頭的行為排除規則，`\!` 轉義為字面感嘆號
- **歷史字段自動修復**：載入時檢查 `isBooleanQuery`、`enableDiacriticIgnore`、`enableHtmlTagIgnore`、`rangeRef` 等字段，缺失則補充默認值，並修正布爾模式與正則模式的衝突，確保舊版歷史記錄兼容性
- **搜索結果緩存**：在右側邊欄視圖中（`SearchResultView`）
- **動態測量**：動態測量面板寬度，基於字符寬度(包括零寬度字符等)自動調整單行模式的文本截取
- **Markdown 渲染**：使用 Obsidian 的 `MarkdownRenderer.renderMarkdown()` 渲染結果，支持格式保留
- **數據存儲**：文件組/組合數據、搜索歷史保存在 `.obsidian/plugins/custom-search/data.json` 中
- **原生搜索**：使用 `executeCommandById("search:search")` 代替模擬 Enter 事件，避免 `isTrusted: false` 導致的問題
- **正則路徑檢測**：自動檢測路徑匹配（包含 `/` 或 `\/` 時轉為 `path:` 查詢），添加括號以確保原生語法解析正確
- **結果排序器**：`ResultSorter` 支持三層優先級規則，只對普通文件應用 B/C 規則，優先文件（文件優先級匹配）不受後續排序規則影響
- **搜索歷史**：支持完全去重、最大數量限制、面板寬度可調、鍵盤導航
- **單行模式（A模式）**：自動轉義腳注行（以 `[^...]:` 開頭的行），自動刪除所有反引號以避免 Markdown 解析問題
- **自動調整高度**：文件組/組合編輯時自動調整文本域高度（自適應最大 300px）
- **懸浮模式按鈕**：使用延遲顯示/隱藏（200ms/250ms），避免誤觸發，背景為毛玻璃效果
---
## 📝 更新日誌
https://github.com/arpcn/obsidian-custom-search/blob/main/CHANGELOG.md
### [2.4.8] - 2026-06-01
#### 🐛 修復問題
- **修復「無視標籤」與「忽略變音」同時啟用時搜索無結果**
- 調整普通文本模式的處理順序：先刪除標點符號，再轉義正則特殊字符，然後應用忽略變音，最後插入標籤跳過模式
- 避免刪除標點步驟誤刪忽略變音生成的字符組方括號 `[ ]`
- **修復「重搜」載入文件組/組合時組名丟失**
- 在歷史恢復時正確設置 `pendingRangeInfo`，確保提交時能識別組名和修改狀態
- 優化提交邏輯，兼容來自歷史恢復的 `originalPatterns: null` 情況
### [2.4.7] - 2026-05-30
#### 🔧 優化改進
- **無視標籤模式增強**：加入空格匹配（半角/全角），搜尋時自動跳過空白字符
#### 🐛 修復問題
- **修復 A 模式截取時行首/行尾空格導致的渲染異常**
- **修復預定範圍保存後污染編輯區**：保存「初始預定範圍」後不再錯誤地寫入主對話框編輯區
- **修復「已修改」狀態下編輯區被意外覆蓋**：「已修改」狀態下保護用戶手動編輯，僅同步名稱變化
- **修復組合引用同步問題**：修改組合所引用的文件組後，返回主界面時編輯區內容正確同步（未修改狀態下）
- **修復打開設置頁面時 A 模式結果重複渲染**：添加防抖和防併發機制
### [2.4.6] - 2026-05-26
#### ✨ 新增功能
- **分頁加載**：結果分批加載，A/B/C 模式分別對應 100/40/40 條/批，提升大量結果時的渲染性能
- **文件折疊**：點擊文件頭右側按鈕或文件名，可折疊/展開單個文件的所有結果
- **全局折疊/展開**：頂部工具欄新增 ▶/▼ 按鈕，可批量控制所有文件的折疊狀態
- **加載更多**：底部按鈕按順序加載下一批結果，新文件區域自動創建
- **懶加載**：折疊的文件展開時才動態渲染條目，減少初始渲染開銷
#### 🔧 優化改進
- **模式切換邏輯重構**：引入強制重建參數，模式切換時正確刷新，寬度變化時按需重建
- **A 模式寬度變化精細化更新**：寬度變化時僅重新計算並更新每行的截取內容，不必重建整個視圖
- **選擇性渲染**：模式切換時，目標條目之前的文件只渲染文件頭，大幅減少渲染量
- **智能加載範圍**：模式切換後自動計算加載範圍，確保目標條目可見，同時控制性能開銷
- **跨模式位置記憶**：基於文件路徑和文件內偏移記錄位置，模式切換後準確恢復滾動位置
#### 🐛 修復問題
- 修復側邊欄折疊後重新打開時，結果被清空的問題
- 修復 B/C 模式下因寬度變化觸發的不必要視圖重建
### [2.4.5] - 2026-05-25
#### ✨ 新增功能
- A 模式支持跳過白名單 HTML 標籤（`<b>`、`<i>`、`<a>`、`<span>` 等），不計入寬度計算
- 支持自定義高亮標記 `==[`、`==\[` 和 `]==`，標記本身不計入寬度
- 截取後自動清理不成對的 HTML 標籤和自定義高亮標記，避免渲染異常
#### 🐛 修復問題
- 添加新文件組及組合時，實時刷新
- 修改文件組或預定範圍後，刷新按鈕和重新搜索按鈕現在會自動載入最新的範圍內容(從 settings 獲取)
- 在管理彈窗中修改當前主窗口引用的文件組/組合/預定範圍後，關閉彈窗時主對話框編輯區會自動更新為最新內容
#### 🔧 優化改進
- `buildVisibleStringWithMapping()` 採用狀態機架構，統一處理 HTML 標籤、註釋、鏈接 URL 和自定義標記
- 新增 `removeUnpairedTagsAndMarkers()` 函數，使用棧匹配算法清理不成對元素
- 組合的添加/刪除組成員操作現在會自動保存，與文件組的行為保持一致
### [2.4.2] - 2026-05-19
#### ✨ 新增功能
- A 模式（單行）支持跳過 Markdown 不可見語法標記（鏈接中的 URL 部分）（可選：`==`、`**`、`*`、`_`、`~~`）
- 鏈接 URL 包含搜索關鍵詞時自動轉義，使 URL 可見並支持高亮
- 結果面板新增「⟳ 刷新」按鈕，直接重新執行當前搜索（不彈窗、不保存歷史）
#### 🔧 優化改進
- A 模式截取算法重構：採用累積單位 + 二分查找，提升精度和性能
- 新增 `buildVisibleStringWithMapping()` 函數統一處理可見字符串構建與位置映射
- 新增 `escapeLinkIfKeywordInUrl()` 函數處理鏈接轉義邏輯
- 所有顯示模式（A/B/C）均支持鏈接 URL 關鍵詞檢測與轉義
### [2.4.1] - 2026-05-14
#### ✨ 新增功能
- 設置面板中新增「無視標簽（默認值）」和「忽略變音（默認值）」開關，支持三個開關的互斥邏輯
#### 🔧 優化改進
- 無視標簽模式下，自動過濾輸入框中的 HTML 標簽、標點符號及 MD 語法符號，消除格式干擾
- 將正則生成邏輯從 searchInFiles 移至 searchAndShowInSidebar 統一處理，簡化參數傳遞鏈路，解決默認值傳遞問題
### [2.3.3] - 2026-05-13
#### ✨ 新增功能
- 文本內容的`html標簽`、`MD語法`及`標點符號`忽略功能
#### 🐛 修復問題
- 將依賴閉包變量 isExpanded 的地方改為從 DOM 實時讀取展開狀態
#### 🔧 優化改進
- 超過2秒，隨時可以停止，返回已搜得結果
---
### [2.2.0] - 2026-05-12
#### ✨ 新增功能
- 單行模式字符寬度自定義設置（可以添加零寬字符、窄字符）
- 在主面板文件名匹配中直接選擇需要的文件組/組合
#### 🔧 優化改進
- 增強自定義文件組面板的編輯功能
- 優化主面板的調用、輸入框歷史條目的載入
### [2.1.1] - 2026-05-10
#### 🐛 修復問題
- 修復搜索歷史文件組及組合加載數據傳輸問題
#### 🔧 優化改進
- 優化單行模式文本顯示（對零寬字符、疊加字符、分詞符，優化計算）
### [2.1.0] - 2026-05-09
#### ✨ 新增功能
- 新增文本內容布爾查詢語法（支持 `&`、`|`、`!`、括號，可選開關）
- 新增文本內容變音符號忽略功能（支持九組字符的雙向匹配）
- 新增文件名匹配排除規則（支持 `!` 開頭的排除行）
#### 🐛 修復問題
- 修復搜索結果中多個關鍵字的高亮及定位
- 修復排除規則解析錯誤（為排除模式添加括號）
- 修復原生搜索 Enter 事件模擬問題（改用 `executeCommandById("search:search")`）
#### 🔧 優化改進
- 歷史數據自動修復（加載時補充缺失字段、修正布爾/正則標誌位衝突）
---
### [2.0.0] - 2026-05-06
#### ✨ 新增功能
- 新增長按顯示歷史菜單（300ms 長按 `❮`/`❯` 顯示歷史面板）
- 新增「重新搜索」按鈕，保留當前範圍設置（預定範圍/自定義範圍/組/組合等）
- 新增修改版標記（組/組合應用後編輯會顯示「已修改」，提交時保存快照）
- 新增顏色自定義（序號文字顏色、模式按鈕顏色、激活外框顏色等）
- 新增文件批量模式切換（文件頭懸浮按鈕「«」）
- 新增歷史面板寬度可調（設置中 200-600px）
- 新增搜索歷史快捷鍵（`Ctrl+←/→` 切換，`Ctrl+\` 顯示面板）
- 修補輔助編輯器快捷填充（點擊圖標選擇文件/標籤/路徑）
#### 🐛 修復問題
- 修復多行文本輸入框自動調整高度
#### 🔧 優化改進
- 優化單行模式文本顯示（基於全/半角字符測量截取，優化腳注及代碼顯示）
- 優化鍵盤導航（支持循環導航，Escape 清除焦點）
---
### [1.0.0] - 2026-04-29
#### ✨ 新增功能
- 基礎搜索功能（預定範圍、自定義範圍）
- 三種結果顯示模式（A/B/C）
- 條目獨立顯示模式切換
- 文件組與組合管理
- 默認預定範圍設置
- 結果排序（三層優先級：文件優先級 → 組間優先級 → 組內模式優先級）
- 原生搜索查詢支持
- 輔助編輯器（可視化構建查詢，支持 AND/OR/NOT、修飾符）
- 顏色自定義（基礎顏色、模式按鈕顏色）
- 鍵盤導航（↑/↓/Enter/Home/End/Escape）
- 右鍵菜單集成（預設範圍快搜、搜索面板）
- 搜索歷史管理（自動保存、去重、快捷鍵導航）
---
## 📊 Custom-Search vs Obsidian原生搜索 對比
### 一、特色功能對比
| 功能 | Custom-Search | 原生搜索 |
| --------------------- | :----------------------------: | :-------------------: |
| **文件組預設** | ✅ 自定義文件組，可保存重用 | ❌ 無 |
| **文件組組合** | ✅ 多個文件組可組合成更大範圍 | ❌ 無 |
| **預定範圍（默認範圍）** | ✅ 可設為默認，快速搜索 | ❌ 無 |
| **排除語法（NOT）** | ✅ `!A` | ✅ `-file:A` |
| **執行順序控制** | ✅ exclude-first / exclude-last | ❌ 固定 |
| **無索引延遲** | ✅ 每次搜索都快 | ❌ 每次掃描索引 |
| **搜索歷史** | ✅ 完整歷史面板 + 快捷鍵 | ❌ 無 |
| **結果排序**（文件/組/模式三級） | ✅ 自定義 | ❌ 僅文件名/時間 |
| **三種顯示模式**（A/B/C） | ✅ 全局 + 單條切換 | ⚠️ 僅展開/摺疊 |
| **可視化語法編輯** | ✅ 輔助編輯器 | ❌ 無 |
| **右鍵菜單快速預定搜索** | ✅ | ❌ |
| **結果渲染**（Markdown 格式） | ✅ 完整渲染 | ❌ 純文本 |
| **布爾查詢語法**（`& \| !`） | ✅ 可選開關 | ❌ 無 |
| **變音符號忽略** | ✅ 支持內容 /可手動`s[uū]tr[āa]` | ❌ 無（需手動） |
| **忽略標籤語法及標點** | ✅ | ❌ 無 |
---
### 二、搜索語法對比
| 運算符 | Custom-Search（本插件） | Obsidian 原生搜索 |
| ------------------------------- | :--------------------------------: | :---------------------: |
| **文件名/路徑 OR**（多選一） | ✅ 多行自動 OR | ✅ `file:A OR file:B` |
| **文件名/路徑 NOT**（排除） | ✅ `!A` 語法 | ✅ `-file:A` |
| **文件名 AND**（同時包含） | ⚠️ 需手寫正則 `^(?=.*A)(?=.*B)` | ✅ `file:A file:B` |
| **路徑 AND** | ⚠️ 需手寫正則 | ✅ `path:A path:B` |
| **執行順序控制**（先排除還是先包含） | ✅ `exclude-first` / `exclude-last` | ❌ 固定順序 |
| **內容 OR** | ✅ `A \| B` `(A\|B\|C)` | ✅ `A OR B OR C` |
| **內容 NOT** | ✅ `!A`（布爾模式） | ✅ `-A` |
| **內容 AND**（同一行） | ✅`A B` `A & B` `^(?=.*A)(?=.*B)` | ✅ `A AND B` |
| **內容 AND**（跨行） | ❌ 不支持 | ✅ `A B`（同一文件內） |
| | | |
| 範圍類型 | Custom-Search | Obsidian 原生搜索 |
| **文件名正則** | ✅ 完整支持 | ⚠️ 僅 `file:/正則/` |
| **路徑正則** | ✅ 完整支持 | ⚠️ 僅 `path:/正則/` |
| **文件夾路徑** | ✅ `^kosa/ju/` | ✅ `path:kosa/ju/` |
| **文件組預設** | ✅ 多組 OR 組合 | ❌ 無 |
| **文件組組合** | ✅ 組間可再組合 | ❌ 無 |
| **標籤**`#tag` | ✅ 可搜索（字符串匹配） | ✅ `tag:#佛學` |
| **Frontmatter 元數據**`key: value` | ✅ 可搜索（字符串匹配） | ✅ `frontmatter:` |
| **區塊ID** `^id` | ✅ 可搜索（字符串匹配） | ✅ `block:` |
| **任務搜索** `- [ ]` 和 `- [x]` | ✅ 可搜索（字符串匹配） | ✅ `task:`, `task-todo:` |
| **大小寫敏感** | ✅ 正則 `i` 標誌 | ✅ `match-case:`或 `(?i)` |
| **忽略標籤語法及標點** | ✅ | ❌ 無 |
| **變音符號忽略** | ✅ 支持 | ❌ 無 |
| **正則表達式** | ✅ 完整支持 | ✅ `/正則/` 或 `regex:/正則/` |
> **總結**：Custom-Search 專注於文件名/路徑範圍的精準控制和大庫性能，適合日常快速搜索；布爾模式提供簡潔的 `& | !` 語法；原生搜索在跨行 AND、元數據語義搜索方面更強大。二者互補，可通過「原生」按鈕一鍵切換。
---
### 三、性能對比（2-3萬文件實測）
| 場景 | Custom-Search | Obsidian 原生搜索 |
| ---------------------- | :-----------: | :--------------: |
| **首次搜索**（剛打開 Obsidian） | 0.3-0.8秒 | 2-4秒（載入索引）+ 1-3秒 |
| **後續搜索**（同一會話） | 0.2-0.5秒 | 1-3秒（每次掃描索引） |
| **搜索範圍很窄（<200文件）** | 0.1-0.3秒 | 1-3秒 |
| **搜索範圍很寬（>5000文件）** | 2-5秒 | 1-3秒 |
| **文件變更後搜索** | 0.2-0.5秒 | 1-4秒（需更新索引） |
| **記憶體佔用** | 💚 低（<20MB） | 💛 中（50-100MB） |
| **啟動 Obsidian 開銷** | 無影響 | 載入索引 2-4秒 |
小範圍（<500文件）是 Custom Search 的優勢區(文件名正則匹配後的範圍)，快 5-10 倍。寬範圍（>5000文件）原生更快。
---
### 四、搜索類型與工具定位
#### 4.1 三種搜索類型的本質區別
| 類型 | 核心機制 | 示例 | 是否依賴索引 |
|:---|:---|:---|:---|
| **精確匹配** | 字符串完全相同（或正則匹配） | `search` → `search`、`Search`、`sūtra` → `sutra`* | ❌ 不需要 |
| **模糊匹配** | 字符串層面的近似（編輯距離、拼寫糾錯） | `recieve` → `receive` | ✅ 需要 |
| **語義匹配** | 含義層面的相似（向量、同義詞） | `汽車` → `轎車` | ✅ 需要 |
> \*註：大小寫不敏感、變音符號忽略是正則的擴展，本質仍是精確匹配——匹配「規範化後的相同字符串」。
#### 4.2 各搜索工具的定位
| 工具 | 精確匹配 | 忽略變音 | 無視標籤 | 模糊匹配 | 語義匹配 | 範圍控制 | 速度 |
| ----------------- | ---- | ---- | -------- | -------- | -------- | ---------------- | ----------- |
| **Obsidian 原生搜索** | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ 手寫路徑 | 中等（依賴索引） |
| **Custom Search** | ✅ | ✅ | ✅ **獨有** | ❌ | ❌ | ✅ **核心（可保存/組合）** | **極快**（無索引） |
| **Omnisearch** | ✅ | ✅ | ❌ | ✅ **核心** | ❌ | ❌ | 中等（有索引） |
| **Note Gallery** | ✅ | ❌ | ❌ | ✅ | ❌ | ⚠️ 手寫路徑 | 中等 |
| **Dataview** | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ `FROM` 語句 | 慢 |
| **QMD / Copilot** | ✅ | ❌ | ❌ | ⚠️ 有限 | ✅ **核心** | ❌ | 慢（向量計算） |
#### 4.3 性能與能力的權衡
| 類型 | 速度 | 資源佔用 | 適用場景 |
|:---|:---|:---|:---|
| **精確 + 範圍** | **極快（0.1-0.5秒）** | 極低（<20MB） | 知道要找什麼、知道大概在哪 |
| **模糊匹配** | 中等（1-2秒） | 中等（索引） | 不確定拼寫、想找近似 |
| **語義匹配** | 慢（2-5秒+） | 高（向量庫、模型） | 探索式搜索、找關聯概念 |
> **核心洞察：模糊和語義的「慢」不是實現問題，是數學問題。** 編輯距離和向量計算的本質決定了它們無法像字符串比較那樣快。
#### 4.4 Custom Search 的定位與設計理念
> **Custom Search = 對已知對象的精確快速定位**
| 維度 | 說明 |
|:---|:---|
| **做什麼** | 精確匹配 + 範圍控制 + 無視標籤 |
| **不做什麼** | 模糊匹配、語義匹配 |
| **為什麼不做** | 會犧牲速度，且與核心定位衝突 |
| **如何互補** | 可搭配 Omnisearch（模糊）或 QMD（語義）使用 |
**搜索類型對比：**
| 類型 | 機制 | Custom Search |
|:---|:---|:---|
| **精確匹配** | 字符串相同（含大小寫、變音符號） | ✅ 核心 |
| **無視標籤** | 跳過 HTML/標點，匹配渲染文本 | ✅ 特色 |
| **模糊匹配** | 編輯距離、拼寫糾錯 | ❌ 不做 |
| **語義匹配** | 向量相似度、AI | ❌ 不做 |
> 💡 **精確匹配求快，模糊匹配求全，語義匹配求懂。三者不可兼得，Custom Search 選擇了「快」。**
#### 4.5 使用建議
| 場景 | 推薦使用 |
| ----------------------- | :-----------: |
| **日常關鍵詞查找** | Custom-Search |
| **限定文件名/路徑、特定範圍** | Custom-Search |
| **排除特定文件（草稿、註解、備份）** | Custom-Search |
| **需要結果排序、渲染** | Custom-Search |
| **筆記庫很大（>5000文件）** | Custom-Search |
| **反覆搜索相關主題（善用歷史記錄）** | Custom-Search |
| **需要排除內容中的關鍵詞（內容 NOT）** | Custom-Search |
| **忽略標籤語法及標點** | Custom-Search |
| **變音符號忽略** | Custom-Search |
| **需要跨行 AND 邏輯** | 原生搜索 |
| **搜索範圍很寬（全庫）** | 原生搜索 |
| **需要多個搜索面板對比** | 原生搜索 |
---
### 五、一句話總結
| | 結論 |
| ----------------- | ------------------------------ |
| **Custom-Search** | 快、準、省記憶體，適合 80% 的日常文件名/路徑範圍搜索 |
| **原生搜索** | 功能全、語法豐富，適合 20% 的元數據/跨行布爾查詢 |
| **互補關係** | Custom-Search做主力，複雜需求轉原生（一鍵切換） |