食用指南 - AnimeUI

# Theme Development Guide

伴随AnimeUI 2.0重磅来袭的还有其自带的主题系统

并以此来将作为装饰属性的配色和风格的转移到了主题开发上

赋予主题一定的定制能力。

# 什么是主题系统

主题系统是一套允许使用者对全局配色、界面功能等进行自定义的应用拓展模型。

主题系统包括主题配色(Theme-Blending) 和主题风格(Theme-Style)两个部分。

# 如何使用主题系统

在AnimeUI应用的左下角，有一个小箭头，展开它可以看到当前的主题配色和主题风格名称

格式为： [主题配色名] | [主题风格名]

其中，右边的小齿轮用于快速切换主题配色，默认切换的是上一个暗/亮色主题配色 (当前为亮色，就切换到上一个暗色主题配色; 当前为暗色，就切换到上一个亮色主题配色)

左边的小魔法棒用于快速切换上一个主题风格。

快速主题切换

应用左下角的快速主题切换的切换模式是最近主题优先 当点击切换主题时，切换到的上一个主题并不按照配置文件中指出的主题顺序

# 主题系统的构成

AnimeUI的多主题系统基于对上一版的重新构思与改进， 给予了现代单页应用界面配置外的更多可玩性， 使可定制程度大大提高的同时又兼顾易用性，经过数月的构思打磨，便有了当前的多主题系统。

AnimeUI将主题系统划分为 主题配色(Theme-Blending) 和 主题风格(Theme-Style) 两部分, 其各有侧重点。

主题配色(Theme-Blending) 主要通过设置配色变量或颜色变量的方式来实现整体色彩视觉上的定制修改， 配置较为简单。

主题风格(Theme-Style) 则拥有更强大的功能，通过直接注入CSS样式或者JavaScript代码的方式进行更高自由度的定制修改， 同时也是修改一些未暴露到UI界面上设置的一个解决方案。（如快捷键的修改）

但不必担心其开发过于复杂，对于界面中一些通用组件或者功能，AnimeUI专门为主题风格提供了很多实用的API， 辅助主题开发以更简便而高效的方式进行的同时， 又让其保持像对传统多页面网页一样简单而直观。

称谓省略

AnimeUI的 主题系统(Theme-System) 包括 主题配色(Theme-Blending) 和 主题风格(Theme-Style)两部分，将其合称为主题(Theme)

而本文档中仅出现"主题"而未指明是主题风格还是主题配色的时候就通指二者都有。

# 目录结构

除内置主题外的其余所有主题都放在 /themes/ 目录下

主题配色位于 /themes/blendings/ 目录下

主题风格位于 /themes/styles/ 目录下

无论是主题风格还是主题配色的单元都是相应目录下的一个文件夹。 而文件夹的名称就代表着主题配色或者主题风格的唯一标识。

在文件夹内都会使用一个特定规则的JSON文件作为主题的入口。

对于名为[name]的主题配色，其入口JSON文件名为[name].json

对于名为[name]的主题风格，其入口JSON文件名为entry.json

具体规则详见:

Tips

本指北系列中的JSON文件配置的展示均照从根级开始的层级细粒度展示

为了保持简洁只展示相关属性，其他属性同默认上下文。

JSON配置示例中可能会使用注释， 但考虑到性能，实际用于加载的JSON配置文件，暂不允许注释!

# 主题配色

查看我们的主题配色开发指北教程

# 主题风格

查看我们的主题风格开发指北教程

附录：

# 全局子主题

为了提高在频繁更新情况下主题的易用性和保持对一般用户的友好性，AnimeUI提供了一套内置全局子主题。

其配置和开发方式基本同普通主题配色和主题风格一致，但具有更高的优先级。 一般用于个人独立配置，不可用于分享发布。

# 全局子主题的作用

全局子主题分为 Global-SubTheme-Blending(全局子主题配色) 和 Global-SubTheme-Style(全局子主题风格)

全局子主题本质也是一个主题，你可以在 themes/blendings和themes/styles 看到一个 custom 的文件夹

这就是自带的全局子主题 custom 预设。

打开里面你大概会发现里面内容什么都没有。

但在里面做的所有设定，都会以比其他主题更高的优先级呈现效果

估计你已经猜到了，如果你并不想完整的做一个主题共享出来, 或是仅仅想对别人做的主题进行部分修改， 那么在这个预设全局子主题中实现将会是很好的方式。

在主题更新或者AnimeUI系统更新时，你便只需直接拷贝覆盖custom主题而无需做任何配置。

Tips

全局子主题 不具有继承特性，也即 dark 选项 在全局子主题配色中是无效的。

同时，全局子主题风格也不具有运行时上下文，即依赖于当前主题风格上下文的API将无法工作，比如resolvePath。 这可能导致一些路径拼接习惯上的不同。但由于全局子主题名称通常为固定值，手动加上子主题路径前缀即可。

# 配置子主题

在主题根配置JSON文件中，有一个 internal 属性

{
  "internal": {
    "title": "主题内嵌相关配置",
    "hint": "默认无需修改",
    "withCustom": "custom"
  }
}
1
2
3
4
5
6
7

在这个属性内有一个 withCustom 属性，它指定了一个全局的用户子主题名。

不管是全局子主题配色(Global-SubTheme-Blending) 还是 全局子主题风格(Global-SubTheme-Style)，其名称都必须一致为这个withCustom指定的字符值。

同时这个主题名也是开发主题时取名的保留字段。这个属性非必要并不建议修改。

# 禁用子主题

因为无论 预设子主题 中有没有填充内容，主题系统都会默认加载这个主题。

如果你想禁用它 (以便于省下那么一个网络请求的话)

将其配置为false即可.

// 禁用全局子主题
{
  "internal": {
    "withCustom": false
  }
}
1
2
3
4
5
6

←