update at 2025-09-22 18:54:59

detaildesign.md

@@ -24,6 +24,11 @@
 | Gallery 支持 | 将 `{{<gallery .../>}}{{<load-photoswipe>}}` 转成图片 wikilinks 列表 |
 | 预处理 | 在 Markdown 渲染前执行自定义语法转 HTML |
 | 易扩展 | 提供独立函数/接口减少耦合，如 `selectGalleryImages`、`extractWeChatMeta` |
+| 默认封面配置 | 无任何图片候选时使用 `defaultCoverPic` (可配置) |
+| 前置回退解析 | 若 metadataCache 缺失 frontmatter，启用手动行级解析回退 |
+| Gallery 块扩展 | 支持 `{{<gallery>}}` 块 + 内部 `figure src|link=` 解析 |
+| 行级语法扩展 | `[fig .../]` 与 `||r`/`||g`/`||b`/`||y`/`||` 统一由 `applyCustomInlineBlocks` 处理 |
+| 调试日志节流 | 输出当前文件路径与默认封面选用日志，3 秒内同路径不重复 |
 
 ## 3. 术语与定义
 - **Wikilink 图片语法**：`![[xxx.png]]`
@@ -39,7 +44,9 @@ Raw Markdown
   ↓ extractWeChatMeta (保留 frontmatter 内容供分析)
   ↓ 去 frontmatter
   ↓ transformGalleryShortcodes (gallery → ![[...]] 列表)
+  ↓ transformGalleryBlock (gallery 块/figure → ![[...]] 列表)
   ↓ marked.parse() （图片扩展 -> LocalImage token）
+  ↓ applyCustomInlineBlocks (fig/彩色段落 轻语法 HTML 化)
   ↓ 生成 HTML + 样式注入
   ↓ setArticle()
   ↓ getArticleContent() -> preprocessContent(line regex 替换) -> 最终 HTML
@@ -76,6 +83,8 @@ Raw Markdown
 - 回退封面：同时匹配 wikilink + markdown 图片，比较 index 取出现最早的一种。
 - 返回：`{ title, author, coverLink, rawImage }`。
 - 与 `getMetadata()` 融合以补齐空缺字段。
+ - 若 Obsidian `metadataCache` 返回为空或缺失字段，触发手动 fallback：扫描首段 frontmatter 行（不依赖外部 YAML 包），支持 `key: value` 单行形式；空字符串的 cover/image 会被视为未提供。
+ - 追加默认封面逻辑：封面候选链（frontmatter cover > 正文首本地图/本地 wikilink/markdown > gallery 生成图 > defaultCoverPic）。
 
 ### 7.3 前置处理（`preprocessContent`）
 - `[fig .../]` → `<span>`（题注样式）。
@@ -106,6 +115,44 @@ Raw Markdown
 - 若块内未匹配到任何 figure，保留原文本。
 - 正则：`/{{<gallery>}}([\s\S]*?){{<\/gallery>}}/g` 与内部 `figureRegex = /{{<figure\s+src="([^"]+)"[^>]*>}}/g`。
 - 输出顺序按出现顺序。
+ - `figure` 标签支持 `src="..."` 与可选 `link="..."`，当存在 link 时仍按 `src` 的 basename 作为图片候选；后续可利用 link 生成超链接包装。
+
+#### 7.4.2 link 属性与未来 caption 计划
+- 当前：`link` 仅被解析但未输出额外结构，保留在后续渲染扩展阶段使用（例如生成 `<a>` 包裹 `<img>`）。
+- 规划：`caption` 字段可映射为 wikilink alias 或 `<figcaption>`。
+
+### 7.5 行级轻语法扩展 (`applyCustomInlineBlocks`)
+- 输入：渲染后 HTML / 或预处理文本段落。
+- 规则：
+  - `[fig 内容 /]` → `<span class="n2m-fig">内容</span>`（当前实现可能用内联 style，后续计划换 class）。
+  - `||r 文本` / `||g` / `||b` / `||y` / `|| 文本` → 彩色背景段落 `<p style>...</p>`。
+- 节点安全：通过转义内部 HTML 以防注入（若未实现需列入风险）。
+- 后续：提取公共 class + 主题 CSS。
+
+### 7.6 调试日志与节流
+- 目的：调试封面选取与路径解析；避免刷屏。
+- 机制：记录最近一次输出路径时间戳，3 秒内同路径日志抑制。
+- 日志包括：当前 markdown 文件绝对路径；默认封面 fallback 触发说明；gallery 转换统计（可选）。
+
+### 7.7 配置项外化 (Settings 更新)
+- 新增：`galleryPrePath`, `galleryNumPic`, `defaultCoverPic`。
+- 位置：`NMPSettings` + `SettingTab` UI 输入框。
+- 迁移：移除硬编码常量 `GALLERY_PRE_PATH` / `GALLERY_NUM_PIC`。
+- 默认值：`defaultCoverPic = 'cover.png'`（可为相对/绝对/网络 URL 或 wikilink 形式）。
+- 风险：用户提供的默认封面不存在 → 目前不校验，可后续增加存在性检查与 Notice。
+
+### 7.8 封面候选决策链（更新版）
+1. 若已有 `thumb_media_id`（外部指定）→ 不再上传本地封面，保持 null。
+2. frontmatter cover/image（非空字符串）→ 使用其 basename 生成 wikilink。
+3. 正文扫描首个本地图片（markdown / wikilink；忽略 http/https）。
+4. 若正文无 → 使用 gallery 自动展开生成的第一张候选。
+5. 若仍无 → 使用 `defaultCoverPic`（若配置）。
+6. 若 `defaultCoverPic` 也无 → cover 为空。
+
+Edge Cases：
+- frontmatter cover: "" → 视为未提供。
+- defaultCoverPic 若为绝对 URL → 在上传阶段需区分远程/本地策略。
+- gallery 展开后若所有图片为远程 URL（未来支持）→ 不作为本地候选，跳到 defaultCoverPic。
 
 ## 8. 正则清单
 | 场景 | 正则 | 说明 |
@@ -114,6 +161,9 @@ Raw Markdown
 | Wikilink 图片 | `!\[\[(.+?)\]\]` | 非贪婪 |
 | Markdown 图片 | `!\[[^\]]*\]\(([^\n\r\)]+)\)` | 不跨行 |
 | Gallery | `{{<gallery\s+dir=\"([^\"]+)\"(?:\s+figcaption=\"([^\"]*)\")?\s*\/>}}{{<load-photoswipe>}}` | 捕获 dir/caption |
+| Gallery 块 | `{{<gallery>}}([\s\S]*?){{<\/gallery>}}` | 块包裹内容 |
+| Gallery figure | `{{<figure\s+src=\"([^\"]+)\"[^>]*>}}` | 提取图片 src |
+| Figure link 属性 | `link=\"([^\"]+)\"` | 可选外链（当前仅解析） |
 | fig | `\[fig([^>]*?)\/]` | 题注 |
 | 行块 | `\|\|r (.*)` 等 | 行级匹配 |
 
@@ -134,8 +184,11 @@ Raw Markdown
 ## 11. 配置 & 常量
 | 常量 | 说明 | 后续计划 |
 |------|------|----------|
-| `GALLERY_PRE_PATH` | 画廊根目录 | 移入设置面板 |
-| `GALLERY_NUM_PIC` | 默认选图数量 | 支持短代码参数覆盖 |
+| `galleryPrePath` | 画廊根目录（配置项） | 未来参数化 per-block 覆盖 |
+| `galleryNumPic` | 默认选图数量（配置项） | 支持块/短代码 count 覆盖 |
+| `defaultCoverPic` | 默认封面备用 | 校验存在 / 多备选随机 |
+| （移除）GALLERY_PRE_PATH | (已外化) | - |
+| （移除）GALLERY_NUM_PIC | (已外化) | - |
 | 行级样式内联 | 直接 embed style | 可改 class + CSS |
 
 ## 12. 对外接口
@@ -167,6 +220,11 @@ Raw Markdown
 | 封面策略 | 配置“frontmatter 优先 / 正文优先 / 首图随机” |
 | 图廊 HTML 模式 | 直接生成 `<figure>` 集合而非 wikilink 列表 |
 | 样式外置 | 行级块样式改为统一 CSS class |
+| 默认封面池 | 支持数组随机选择 default cover |
+| 默认封面校验 | 选择时校验存在性 + Notice 提示 |
+| caption alias | gallery figure caption -> wikilink alias/figcaption |
+| link wrap | figure link 生成 `<a>` 包裹图片 |
+| debug 开关 | 设置中关闭全部调试日志 |
 | 目录缓存 | 减少频繁 IO |
 
 ## 15. 风险与规避