FinClip为企业提供小程序生态圈技术产品,开发者可在FinClip小程序开发帮助中心找到相关FinClip小程序指引

# DarkMode 适配指南

基础库 2.12.2 及以上版本支持,工具调试请使用 1.8.11 及以上版本,SDK 请使用 2.35.1 以上。

# SDK 开启暗黑模式

小程序 SDK 初始化时,需要设置 autoAdaptDarkMode = true(2.44.5版本废弃) 开启暗黑模式。2.44.5版本开始可以设置themeStyle(浅色模式、深色模式、跟随系统)来指定小程序的主题模式。

    # 基础组件开启 DarkMode

    基础组件的样式可以通过theme属性进行配置,例如:

      # 小程序开启 DarkMode

      app.json中配置darkmodetrue,即表示当前小程序已适配 DarkMode,所有基础组件均会根据系统主题展示不同的默认样式,navigation bar 和 tab bar 也会根据下面的配置自动切换。

      # 相关配置

      app.json中配置darkmodetrue时,小程序部分配置项可通过变量的形式配置,在变量配置文件中定义不同主题下的颜色或图标,方法如下:

      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 深色模式下的变量定义

      lightdark下均可以key: value的方式定义变量名和值,例如:

      {
        "light": {
          "navBgColor": "#f5f6f7",
          "navTxtStyle": "black"
        },
        "dark": {
          "navBgColor": "#1a1a1a",
          "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": "#f5f6f7",
              "navTxtStyle": "black",
              "bgColor": "#ffffff",
              "bgTxtStyle": "light",
              "bgColorTop": "#eeeeee",
              "bgColorBottom": "#efefef",
              "tabFontColor": "#000000",
              "tabSelectedColor": "#30c8121",
              "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": "#1a1a1a",
              "navTxtStyle": "white",
              "bgColor": "#1e1e1e",
              "bgTxtStyle": "dark",
              "bgColorTop": "#1a1a1a",
              "bgColorBottom": "#1e1e1e",
              "tabFontColor": "#ffffff",
              "tabSelectedColor": "#51a937",
              "tabBgColor": "#1a1a1a",
              "tabBorderStyle": "white",
              "iconPath1": "image/icon1_dark.png",
              "selectedIconPath1": "image/selected_icon1_dark.png",
              "iconPath2": "image/icon2_dark.png",
              "selectedIconPath2": "image/selected_icon2_dark.png",
          }
      }
      

      # 获取当前系统主题

      如果app.json中声明了"darkmode": trueft.getSystemInfoft.getSystemInfoSync的返回结果中会包含theme属性,值为lightdark。 如果app.json未声明"darkmode": true,则无法获取到theme属性(即themeundefined)。

      # 监听主题切换事件

      支持2种方式:

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

      # WXSS 适配

      WXSS中,支持通过媒体查询 prefers-color-scheme 适配不同主题,与 Web 中适配方式一致,例如:

      /* 一般情况下的样式 begin */
      .some-background {
          background: white;
      }
      .some-text {
          color: black;
      }
      /* 一般情况下的样式 end */
      
      @media (prefers-color-scheme: dark) {
          /* DarkMode 下的样式 start */
          .some-background {
              background: #1b1b1b;
          }
          .some-text {
              color: #ffffff;
          }
          /* DarkMode 下的样式 end */
      }
      

      # 开发者工具调试

      开发者工具 1.8.11 版本开始已支持 DarkMode 调试,在模拟器顶部可以切换 深色/浅色 模式进行,如图:

      © FinClip with ❤ , Since 2017