主題協議

主題協議

小樹壁紙 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" 即可使用。

歡迎基於此模板創建你的專屬主題，並提交至小樹壁紙主題商店！