主題協議

主題協議

小樹壁紙 Next 支援透過自訂主題檔案調整應用的配色方案與背景樣式，提升視覺體驗。主題檔案採用 JSON 格式，允許開發者定義顏色、背景圖片、元件樣式以及用於主題商店展示的元資訊。

存放位置

預設主題目錄：%APPDATA%/Little-Tree-Wallpaper/Next/themes/（Windows，實際路徑由 app.paths.CONFIG_DIR 決定）。
透過設定項 ui.theme_profile 指定主題：
- "default"：使用內建預設主題。
- 自訂主題：填寫相對路徑（如 "aurora.json"）或絕對路徑。

若目錄不存在，應用啟動時會自動建立。

主題檔案結構

主題檔案為 JSON 物件，推薦包含以下兩類內容：

元資訊（用於主題商店展示）
樣式定義（用於執行階段渲染）

{
  "name": "極光綠",
  "logo": "logo.png",
  "description": "清新柔和的綠色主題，靈感來自極光與森林。",
  "details": "本主題採用 Material You 動態調色技術，適配深色與淺色模式。背景圖使用 Unsplash 高畫質素材，支援透明遮罩疊加，確保文字可讀性。",
  "author": "小樹團隊",
  "website": "https://little-tree.dev/themes/aurora-green",

  "palette": {
    "mode": "seed",
    "seed_color": "#34d399",
    "preferred_mode": "dark",
    "use_material3": true
  },
  "background": {
    "image": "https://images.unsplash.com/photo-1469474968028-56623f02e42e",
    "opacity": 0.35,
    "fit": "cover",
    "alignment": "center",
    "repeat": "no_repeat"
  },
  "components": {
    "page": {
      "bgcolor": "#0f172a"
    },
    "app_bar": {
      "bgcolor": "#0f172a",
      "color": "#f8fafc"
    },
    "navigation_rail": {
      "bgcolor": "#111827",
      "indicator_color": "#34d399"
    },
    "navigation_container": {
      "bgcolor": "#111827"
    }
  }
}

元資訊欄位（可選但推薦）

這些欄位不參與執行階段渲染，僅用於主題商店展示、搜尋和詳細資訊頁：

欄位	類型	說明
`name`	字串	主題名稱（必填，用於顯示）
`logo`	字串	主題圖示檔案名（相對主題檔案路徑，如 `"logo.png"`；若存在，主題商店將優先展示）
`description`	字串	簡短介紹（建議 ≤100 字，用於列表摘要）
`details`	字串	詳細介紹（支援markdown，用於詳細資訊頁）
`author`	字串	作者或團隊名稱
`website`	字串	主題首頁或專案連結（可選）

所有元資訊欄位均可省略，但建議完整填寫以提升主題可發現性與使用者體驗。

樣式定義欄位

與原協議一致，包括 palette、background、components 三部分，詳見下文。

配色（`palette`）

支援兩種模式：

seed 模式：透過單一主色產生完整色板。
- seed_color：十六進位顏色（如 #34d399），必填。
- preferred_mode：light / dark / system（可選）。
- use_material3：布林值，啟用 Material 3 風格（可選）。
custom 模式：直接提供完整 color_scheme。
- color_scheme：包含 primary、surface、on_primary 等欄位的物件。
- brightness：light 或 dark。

顏色值支援：

#RRGGBB 或 #AARRGGBB
rgb(255, 0, 0) / rgba(255, 0, 0, 0.5)
Flet 顏色常數（如 "surface_container_highest"，自動轉換底線）

背景（`background`）

欄位	說明
`image`	圖片路徑或 URL。相對路徑按主題檔案所在目錄 → `themes/` → 設定目錄順序查找。留空則無背景圖。
`opacity`	0.0 ~ 1.0，預設 1.0
`fit`	`cover`（預設）、`contain`、`fill`、`fit_width`、`fit_height`、`scale_down`、`none`
`alignment`	`center`（預設）、`top_left`、`bottom_right` 等
`repeat`	`no_repeat`（預設）、`repeat`、`repeat_x`、`repeat_y`

背景圖位於最底層，與內容疊加顯示。

元件樣式（`components`）

以元件識別為鍵，值為屬性字典。常見元件包括：

page：全域頁面（ft.Page）
app_bar：頂部應用列
navigation_rail：側邊導覽列
navigation_container：內容容器
home_view：首頁視圖（支援 overlay_color、overlay_opacity、force_bgcolor）

屬性會透過 setattr 直接寫入 Flet 控件，欄位名需與控件屬性一致。顏色欄位自動解析。

手動啟用自訂主題

將主題 JSON 檔案放入 themes/ 目錄。

修改 config.json：

{
  "ui": {
    "theme_profile": "aurora.json"
  }
}

重新啟動應用或觸發主題重載。

解析失敗時，應用將回退到預設主題並記錄警告日誌。

範例主題

專案儲存庫提供範例：docs/themes/xuan_niao.json。複製到設定目錄後，設定 theme_profile 為 "xuan_niao.json" 即可使用。

歡迎基於此範本建立您的專屬主題，並提交至小樹壁紙主題商店！