智能小程序主题适配指南（各参数配置详情）

应用配置

一. 相关配置

1. 在?app.json?中配置?themeLocation，指定变量配置文件?theme.json?路径，例如：在根目录下新增?theme.json，需要配置?"themeLocation":"theme.json"。
2. 在?theme.json?中定义相关变量。
3. 在?app.json?中以 @ 开头引用变量。

支持通过变量配置的属性：

• 全局配置的?window?属性与页面配置下的属性：
  • navigationBarBackgroundColor
  • navigationBarTextStyle
  • backgroundColor
  • backgroundTextStyle
  • backgroundColorTop
  • backgroundColorBottom
• 全局配置?window.tabBar?的属性：
  • color
  • selectedColor
  • backgroundColor
  • borderStyle
  • list
    • iconPath
    • selectedIconPath

?

二. 变量配置文件 theme.json

theme.json?用于颜色主题相关的变量定义，需要先在?themeLocation?中配置?theme.json?的路径，否则无法读取变量配置。

配置文件须包含以下属性：

属性	类型	必填	描述
light	object	是	浅色模式下的变量定义
dark	object	是	深色模式下的变量定义

light 和 dark 下均可以?key:value?的方式定义变量名和值，例如：

{
  "light": {
    "navBgColor": "#f6f6f6",
    "navTxtStyle": "black"
  },
  "dark": {
    "navBgColor": "#191919",
    "navTxtStyle": "white"
  }
}

完成定义后，可在全局配置或页面配置的相关属性中以?@?开头引用，例如：

全局配置

>>?进入配置页面

{
  "window": {
    "navigationBarBackgroundColor": "@navBgColor",
    "navigationBarTextStyle": "@navTxtStyle"
  }
}

页面配置

{
  "navigationBarBackgroundColor": "@navBgColor",
  "navigationBarTextStyle": "@navTxtStyle"
}

配置完成后，小程序框架会自动根据系统主题，为小程序展示对应主题下的颜色。

?

三. 配置示例

app.json

示例省略了主题相关以外的配置项

{
  "window": {
    "navigationBarBackgroundColor": "@navBgColor",
    "navigationBarTextStyle": "@navTxtStyle",
    "backgroundColor": "@bgColor",
    "backgroundTextStyle": "@bgTxtStyle",
    "backgroundColorTop": "@bgColorTop",
    "backgroundColorBottom": "@bgColorBottom"
  },
  "tabBar": {
    "color": "@tabFontColor",
    "selectedColor": "@tabSelectedColor",
    "backgroundColor": "@tabBgColor",
    "borderStyle": "@tabBorderStyle",
    "list": [
      {
        "iconPath": "@iconPath1",
        "selectedIconPath": "@selectedIconPath1"
      },
      {
        "iconPath": "@iconPath2",
        "selectedIconPath": "@selectedIconPath2"
      }
    ]
  }
}

theme.json

{
  "light": {
    "navBgColor": "#f6f6f6",
    "navTxtStyle": "black",
    "bgColor": "#ffffff",
    "bgTxtStyle": "light",
    "bgColorTop": "#eeeeee",
    "bgColorBottom": "#efefef",
    "tabFontColor": "#000000",
    "tabSelectedColor": "#3cc51f",
    "tabBgColor": "#ffffff",
    "tabBorderStyle": "black",
    "iconPath1": "image/icon1_light.png",
    "selectedIconPath1": "image/selected_icon1_light.png",
    "iconPath2": "image/icon2_light.png",
    "selectedIconPath2": "image/selected_icon2_light.png"
  },
  "dark": {
    "navBgColor": "#191919",
    "navTxtStyle": "white",
    "bgColor": "#1f1f1f",
    "bgTxtStyle": "dark",
    "bgColorTop": "#191919",
    "bgColorBottom": "#1f1f1f",
    "tabFontColor": "#ffffff",
    "tabSelectedColor": "#51a937",
    "tabBgColor": "#191919",
    "tabBorderStyle": "white",
    "iconPath1": "image/icon1_dark.png",
    "selectedIconPath1": "image/selected_icon1_dark.png",
    "iconPath2": "image/icon2_dark.png",
    "selectedIconPath2": "image/selected_icon2_dark.png"
  }
}

四. 获取当前系统主题

ty.getSystemInfo?或?ty.getSystemInfoSync?的返回结果中会包含 theme 属性，值为 light 或 dark。

五. 监听主题切换事件

支持 2 种方式：

1. 在?App()?中传入?onThemeChange?回调方法，主题切换时会触发此回调。
2. 通过?ty.onThemeChange?监听主题变化，ty.offThemeChange?取消监听。

?

主题色变量

一. 简介

智能小程序主题色是指智能小程序的主要色调，主要用于智能小程序的背景色、文字颜色、按钮颜色等。主题色随着 App 配置而变化，同时支持 light 和 dark 两种主题色。 开发者无需关心主题色的变化。

?

二. 主题色

主题色值通过 css 变量的方式提供，开发者可在 css 中使用变量，在不同主题下，变量值会自动变化。

?

三. 主题色变量

变量名	含义
--app-B1	主背景色
--app-B2	头部导航背景
--app-B3	卡片背景
--app-B4	弹窗背景
--app-B5	底部导航背景
--app-B6	列表背景
--app-M1	主色、按钮背景
--app-M2	辅色 1(错误/警告/危险)
--app-M3	辅色 2 (成功/开关/推荐)
--app-M4	辅色 3 (提示/引导)
--app-M5	Tab 选中色

?

四. 文本色扩展

在对应的主题色下，文本色扩展了 8 种，开发者可根据需要使用。 格式为?--app-${key}-N${level}，其中 level 为 1 ~ 8 的数字。

在样式文件中使用

/* app.tyss */
.app {
  background-color: var(--app-M1);
  color: var(--app-M1-N1);
}

在配置中使用

app.json 配置文件以及页面配置文件中，可以使用主题色变量。

{
  "window": {
    "backgroundColor": "--app-B1",
  }
}

?

五. 主题色小程序

立即体验主题色小程序。?

?

样式表适配

通过对样式名或环境变量的适配，可以实现主题跟随切换。

一. 样式名适配

tyss/less?中，支持通过选择器?theme='dark' | 'light'?去切换主题。

:root {
  --main-bg-color: rgb(255, 255, 255); /* 浅色背景 */
  --main-text-color: rgb(54, 54, 54); /* 深色文字 */
}
 
:root[theme='dark'] {
  --main-bg-color: rgb(47, 58, 68); /* 深色背景 */
  --main-text-color: rgb(197, 197, 197); /* 浅色文字 */
}

二. css 环境适配

如果你想要自定义主题色，可以通过?app.tyss?内声明：

page {
  color-scheme: light;
  --custom-color: #ff0000;
}
@media (prefers-color-scheme: dark) {
  page {
    color-scheme: dark;
    --custom-color: #0000ff;
  }
}