主题协议

主题协议

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

欢迎基于此模板创建你的专属主题，并提交至小树壁纸主题商店！

壁纸源协议