わたしの部屋

網頁的組合關係#

1
src/pages/                         路由入口
2
  └─ MainGridLayout.astro          橫幅、網格、側欄、main
3
       └─ Layout.astro             HTML、head、主題、全域工具
4
            ├─ 頁面 slot          各路由傳入的內容
5
            ├─ FloatingTOC        常駐角落目錄
6
            ├─ MusicPlayer        常駐音樂播放器
7
            └─ Pio                看板娘

這是組合關係，不是檔案所在目錄。MainGridLayout.astro 使用 Layout.astro 包住它的內容；Layout.astro 內的 <slot /> 接收整個主版面。

如何操作#

• 右下角的「目錄」按鈕可展開或收合章節列表。
• 點章節會跳到標題上方，預留導覽列的空間，並更新網址的 hash。
• 閱讀位置會反映在目前章節的高亮，以及按鈕上的進度百分比。
• 清單很長時只捲動目錄面板，不需要回到文章頂端。
• 點面板外部或按 Escape 可收合；Escape 後焦點回到目錄按鈕。
• 拖曳點狀把手可移動。鍵盤使用者可聚焦把手，以方向鍵移動、Shift 加方向鍵細調、Home 重設。

設定層數與顯示模式#

在 src/config.ts 的 siteConfig.toc 修改：

1
toc: {
2
  enable: true,
3
  mode: "float",
4
  depth: 2,
5
  useJapaneseBadge: true,
6
},

enable 是總開關。mode: "float" 使用角落入口；保留的 sidebar 模式還可以顯示原本的大螢幕側邊目錄，而角落入口仍然可用。

浮動目錄的 depth 是相對於文章中最淺的標題層級。例如文章從 ## 開始，depth: 2 會列出 ## 與 ###。數字改大後，長文章的清單也會更長。

useJapaneseBadge 控制最上層標題使用片假名或數字標記。

為什麼不要放在會移動的內容容器內#

position: fixed 不代表在任何父容器中都會固定於視窗。父層的 transform、filter 或某些 containment 設定會改變定位基準。固定工具應放在全域外殼，避免跟著文章進場動畫、側欄網格或內容容器一起移動。

本專案使用 Swup 換頁，文章區域可能被替換但全域工具保留。目錄因此必須重新讀取新文章；事件和 observer 也必須在組件移除時清理，不能每次換頁都多綁一組捲動事件。

三種顯示狀態#

首次進入時預設收合在左下角。收合只隱藏介面，不卸載 <audio>，因此不會因收納而停止播放。播放器會記住收合狀態與位置；播放時間不保證跨重新整理保存。

開啟目錄時，播放器會自動收合；開啟播放器時，目錄會收合，避免兩塊面板互相遮住。音訊不受影響。

展開時使用獨立拖曳把手；收合時直接拖曳專輯封面，移動超過 6px 後會攔截該次點擊，避免放開時誤展開。播放列表跟著播放器移動，不再獨立固定在畫面另一角。

播放器收合為專輯封面#

播放器工具列的「收合」會將介面縮成只有 56px 的圓形專輯封面，播放不會中斷。直接拖曳封面可移動，點擊則展開；拖曳放開不會誤觸展開。封面亦支援方向鍵移動、Home 重設位置，以及 Enter／空白鍵展開。

修改音樂來源#

src/config.ts 的 musicPlayerConfig 管理 enable、mode、Meting API、id、server 與 type。現有的本地播放清單則位於 MusicPlayer.svelte 的 localPlaylist。

外部音源是否可播放仍取決於服務回應、CORS 與瀏覽器播放限制。調整版面不應改變這些來源設定，也不應為了收合介面而建立第二個播放器實例。

IMPORTANT

播放器已由全域 Layout.astro 掛載。不要再把相同播放器加入側欄，否則可能出現多個 audio 實例、重複下載與播放控制衝突。

第一步：建立組件#

新增 src/components/widget/ReadingTip.astro：

1
---
2
interface Props {
3
  class?: string;
4
  style?: string;
5
}
6
const { class: className, style } = Astro.props;
7
---
8
<section class:list={["card-base p-4", className]} style={style}>
9
  <h2 class="font-bold mb-2">閱讀小提示</h2>
10
  <p>使用角落目錄可以快速切換章節。</p>
11
</section>

class 與 style 要傳到外框，側欄管理器提供的動畫或響應式設定才會生效。可重複掛載的組件避免寫死相同 id。

第二步：登記型別與映射#

1. 在 src/types/config.ts 的 WidgetComponentType 加入 "reading-tip"。
2. 在 src/utils/widget-manager.ts 的 WIDGET_COMPONENT_MAP 加入對應檔案路徑。
3. 在 SideBar.astro 和 RightSideBar.astro 匯入 ReadingTip，並在兩份 componentMap 加入 "reading-tip": ReadingTip。

目前渲染器使用明確的 import 映射。只在 WIDGET_COMPONENT_MAP 加路徑，或只填一個 custom 設定，不會自動載入新組件。

第三步：加入側欄設定#

在 src/config.ts 的 sidebarLayoutConfig.properties 新增：

1
{
2
  type: "reading-tip",
3
  position: "sticky",
4
  animationDelay: 100,
5
},

再將 "reading-tip" 放到需要的位置，例如 components.left 或 components.drawer。陣列順序就是組件順序；properties 描述的是該組件的設定。

position: "top" 指側欄上方的一般內容區，不是固定在視窗頂部。sticky 會受父容器高度及 overflow 限制，也不能取代真正的全域浮動工具。

如果新組件需要互動#

Astro 組件的 <script> 可以處理簡單 DOM 行為。狀態較多時可寫 Svelte，並在掛載位置明確使用 client:load、client:idle 或 client:visible。

目前側欄動態映射渲染的是 <Component {...props} />。把 Svelte 組件加入映射不會自動取得 hydration 指令；需要為互動組件增加明確的渲染分支。全域常駐工具可參考 Layout.astro 中的播放器掛載方式。

主欄、側欄與斷點#

先看 sidebarLayoutConfig.components 與 responsive.breakpoints，再看 MainGridLayout.astro 的網格及 sidebar class。

Tailwind 的 md／lg 在 tailwind.config.cjs 定義，目前分別是 768px 與 1280px。部分組件還有獨立的 CSS media query；改斷點時需要一起搜尋，不能只改一份設定。

文章內文與列表卡片#

文章段落、表格、程式碼區塊等視覺設定集中在 src/styles/markdown.css、markdown-extend.styl、expressive-code.css，以及 Markdown.astro。

列表卡片看 PostCard.astro，整體列表／網格看 PostPage.astro。修改單篇文章的標題、作者、分享與授權位置，則看兩個文章路由。

全域 CSS 與層級#

Tailwind 由 postcss.config.mjs 處理，Layout.astro 明確匯入 src/styles/tailwind.css。新增一份樣式檔並不等於瀏覽器一定會載入，要檢查實際 import。

浮動閱讀工具目前使用 z-index 70。新增對話框、抽屜或遮罩時，應一起檢查 Navbar、看板娘、回到頂部及閱讀工具，避免只能看到卻點不到的介面。

最後一個章節：長文章跳轉測試#

如果你已經捲到這裡，現在打開角落目錄，跳回「先分清楚：內容、組件與版面」。目錄入口應持續留在你設定的位置，不需要回到文章最上方才能找到。