小程序 app.json 全局配置和 app.tyss 全局样式

app.json 全局配置

小程序根目录下的 app.json 文件用来对小程序进行全局配置，决定页面文件的路径、窗口表现、设置网络超时时间、设置多 tab 等。

以下是一个基本配置示例：

{
  "themeLocation": "theme.json",
  "pages": ["pages/page1/index", "pages/page2/index"],
  "window": {
    "navigationBarBackgroundColor": "#ffffff"
  }
}

完整配置项如下：

属性	类型	必填	描述	基础库
entryPagePath	string	否	小程序默认启动页面
pages	Array	是	设置页面路径
window	Object	否	设置小程序窗口表现
darkmode	boolean	否	支持暗黑模式, 默认值: true	2.14.0
themeLocation	string	否	主题配置文件相对路径
tabBar	Object	否	设置底部 tabbar 的表现
usingComponents	Object	否	定义全局自定义组件

 

entryPagePath

指定小程序的默认启动路径（首页），必须是 pages 中的其中一项目。如果不填，将默认为 pages 列表的第一项。不支持带页面路径参数。

 

pages

用于指定小程序由哪些页面组成，每一项都对应一个页面的路径（不含文件后缀） 信息。框架会自动去加载同名的 .json、.js、.tyml 和 .tyss 等文件。未声明的页面文件不会打包到小程序应用当中。

未指定 entryPagePath 时，数组的第一项代表小程序的初始页面（首页）。

小程序中新增/减少页面，都需要对 pages 数组进行修改。

如开发目录为：

├── pages
│   ├──index
│   │    ├── index.json
│   │    ├── index.js
│   │    ├── index.tyml
│   │    └── index.tyss
│   └──logs
│        ├── logs.json
│        ├── logs.js
│        └── logs.tyml
├── app.json
├── app.js
└── app.tyss

app.json 中应当如下配置：

{
  "pages": ["pages/index/index", "pages/logs/logs"]
}

配置中路径不需要添加 / 前缀，默认以当前配置文件（app.json）所在目录为基准。

 

window

用于设置小程序的状态栏、导航条、标题、窗口背景色。

属性	类型	默认值	描述
backgroundColor	HexColor	#ffffff	窗口的背景色
backgroundColorBottom	string	#ffffff	底部窗口的背景色，仅 iOS 支持
backgroundColorTop	string	#ffffff	顶部窗口的背景色，仅 iOS 支持
backgroundTextStyle	string	dark	下拉 loading 的样式，仅支持 dark / light
custom	Boolean	false	自定义导航栏，只保留右上角胶囊按钮。
enablePullDownRefresh	boolean	false	是否开启全局的下拉刷新。
navigationBarBackgroundColor	HexColor	#ffffff	导航栏背景颜色，如 #000000
navigationBarTextStyle	string	black	导航栏标题颜色，仅支持 black / white
navigationBarTitleText	string		导航栏标题文字内容
navigationStyle	string	default	default 默认样式 custom 自定义导航栏，只保留右上角胶囊按钮。
onReachBottomDistance	number	50	页面上拉触底事件触发时距页面底部距离，单位为 px。
boardMenus	array[]		自定义菜单配置, 容器版本 ≥ 2.3.0
pageOrientation	string	portrait	屏幕旋转设置，默认值为portrait（竖屏），可选landscape（横屏）, auto 自动

其中 navigationBarBackgroundColor、navigationBarTextStyle、backgroundColor、 backgroundTextStyle、backgroundColorTop 和 backgroundColorBottom 支持主题变量配置。如配置了 themeLocation 主题配置文件后，可使用其中声明的变量。

示例：

{
  "window": {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "接口功能演示",
    "backgroundColor": "@bgColor",
    "backgroundTextStyle": "light",
    "disableScroll": true
  }
}

boardMenus

自定义菜单项目

• key：菜单项的 key 值，必须唯一。
• text：菜单项的标题，支持多语言。
• iconPath：菜单项的图标路径，不支持网络图片，支持主题变量配置。

{
  "window": {
    "boardMenus": [
      {
        "key": "home",
        "iconPath": "@iconPath1",
        "text": "版本1"
      },
      {
        "key": "share",
        "iconPath": "@selectedIconPath1",
        "text": "tab1"
      },
      {
        "key": "share",
        "iconPath": "/assets/images/tab/component_selected.png",
        "text": "@I18n.t('tab2')"
      }
    ]
  }
}

tabBar

如果小程序是一个多 tab 应用（客户端窗口的底部或顶部有 tab 栏可以切换页面），可以通过 tabBar 配置项指定 tab 栏的表现，以及 tab 切换时显示的对应页面。

属性	类型	必填	描述	描述
color	HexColor	是		tab 上的文字默认颜色，仅支持十六进制颜色
selectedColor	HexColor	是		tab 上的文字选中时的颜色，仅支持十六进制颜色
backgroundColor	HexColor	是		tab 的背景色，仅支持十六进制颜色
borderStyle	string	否	black	tabbar 上边框的颜色， 仅支持 black / white
list	Array	是		tab 的列表，详见 list 属性说明，最少 2 个、最多 5 个 tab

其中 color、selectedColor、backgroundColor 和 borderStyle 支持主题变量配置。如配置了 themeLocation 主题配置文件后，可使用其中声明的变量。

其中 list 接受一个数组，只能配置最少 2 个、最多 5 个 tab。tab 按数组的顺序排序，每个项都是一个对象，其属性值如下：

属性	类型	必填	说明
pagePath	string	是	页面路径，必须在 pages 中先定义
text	string	是	tab 上按钮文字
iconPath	string	否	图片路径，icon 大小限制为 40kb，建议尺寸为 81x81px，不支持网络图片。
selectedIconPath	string	否	选中时的图片路径，icon 大小限制为 40kb，建议尺寸为 81x81px，不支持网络图片。

其中 selectedIconPath 和 iconPath 支持主题变量配置。如配置了 themeLocation 主题配置文件后，可使用其中声明的变量。

 

darkmode

是否支持暗黑模式，默认为 true 当设置为 false 时，小程序不支持暗黑模式，且不会触发 onThemeChange 事件。

css 选择器 @media (prefers-color-scheme: dark) 不受影响，仍然会生效。

:root[theme='dark'] 选择器仅在 darkmode 为 true 时生效。

 

themeLocation

配置了 themeLocation 之后，自动支持主题配置。使用相对于 app.json 路径，定义 light 和 dark 主题变量信息。可使用到 window 和 tabBar 支持的字段中。

{
  "themeLocation": "./theme.json"
}

格式如下：

{
  "light": {
    "bgColor": "#ffffff"
  },
  "dark": {
    "bgColor": "#ffffff"
  }
}

声明主题字段变量后，可通过 @ 符号拼接应用到 app.json 配置中。

 

usingComponents

声明全局自定义组件，当一个组件被多个页面所引用时，避免重复在页面配置中声明，可使用全局声明的形式。组件路径支持：

1. 绝对路径形式，以 / 开头，表示小程序源码目录；
2. 相对路径形式，以 . 开头，基于当前 json 文件所在目录；
3. npm 三方包。

{
  "usingComponents": {
    "foo": "/absolute/foo/index", // 绝对路径
    "foo": "./relative/foo/index", // 相对路径
    "foo": "package/es/foo/index" // npm 三方包
  }
}

注意：路径地址必须精确到文件名，不可省略缺省 index。

 

app.tyss 全局样式

app.tyss 作为全局样式，作用于当前小程序的所有页面。有关样式 tyss 更详细的文档请参考 小程序样式。

注意：全局样式默认无法作用于自定义组件，需要配合自定义组件的样式配置。具体请参考文档 Component。