# 全局配置

更新时间：2025-08-22 17:00:47

小程序根目录下的 app.json 文件用来对快手小程序进行全局配置。文件内容为一个 JSON 对象，有以下属性：

属性	类型	是否必填	描述
pages	string[]	是	页面路径列表
window	object	否	全局的默认窗口表现
tabBar	object	否	底部 tab 栏
subPackages	object[]	否	分包结构配置
permission	object	否	小程序接口权限相关设置
enableShare	boolean	否	全局是否能够分享
networkTimeout	object	否	网络超时时间
workers	String	否	Worker 代码放置目录
plugins	Object	否	使用到的插件
usingComponents	Object	否	全局自定义组件配置

# pages

由一个数组组成，每一项都对应一个页面的路径（含文件名）信息。文件名不需要写文件后缀，框架会自动解析 .json, .js, .ksml, .css 四个文件进行处理。数组的第一项为小程序启动时展示的页面。
如果开发目录为：

├── app.js
├── app.json
├── app.css
├── pages
│   │── index
│   │   ├── index.ksml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.css
│   └── logs
│       ├── logs.ksml
│       └── logs.js
└── utils

则需要在 app.json 中写

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

# window

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

属性	类型	默认值	描述
navigationBarBackgroundColor	string	#ffffff	导航栏背景颜色，如 #000000 ，必须为十六进制颜色值
navigationBarTextStyle	string	black	导航栏标题颜色，有效值 black / white
navigationBarTitleText	string		导航栏标题文字内容
navigationStyle	string	default	导航栏样式，有效值：default(默认样式) custom(自定义导航栏)，只保留右上角胶囊按钮，在页面级配置优先级高于全局配置
backgroundColor	string	#ffffff	窗口的背景色，必须为十六进制颜色值。
backgroundTextStyle	string	dark	下拉 loading 的样式，有效值 dark / light
backgroundColorTop	string	#ffffff	顶部窗口的背景色，仅 iOS 支持
backgroundColorBottom	string	#ffffff	底部窗口的背景色，仅 iOS 支持
enablePullDownRefresh	boolean	false	是否全局开启下拉刷新。详见Page.onPullDownRefresh。
onReachBottomDistance	number	50	页面上拉触底事件触发时距页面底部距离，单位为 px。详见Page.onReachBottom。

# 代码示例

{
    "window": {
        "navigationBarBackgroundColor": "#ffffff",
        "navigationBarTextStyle": "black",
        "navigationBarTitleText": "快手接口功能演示",
        "backgroundColor": "#eeeeee",
        "backgroundTextStyle": "light"
    }
}

# tabBar

用于设置客户端底部的 tab 栏：可通过 tabBar 设置 tab 的颜色、个数、位置、背景色等内容。

属性	类型	必填	默认值	描述
color	string	是		tab 上文字的默认颜色，必须为十六进制颜色值。
selectedColor	string	是		tab 上的文字选中时的颜色，必须为十六进制颜色值。
backgroundColor	string	是		tab 的背景色，必须为十六进制颜色值。
borderStyle	string	否	black	tabBar 边框颜色。有效值 black/white。
list	array	是		tab 的列表，详见 list 属性说明，最少 2 个、最多 5 个 tab
position	string	否	bottom	tabBar 的位置，仅支持 bottom/top

其中 list 接受一个数组, tab 按数组的顺序排序, 属性之如下:

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

# subPackages

启用分包加载时，声明项目分包结构。

# permission

小程序接口权限相关设置。调用部分需要获取位置权限的api（如使用授权api（ks.authorize）获取scope.userLocation权限、ks.getLocation、ks.openLocation）前，需要先在此声明。

字段类型为 object，结构为：

属性	类型	必填	描述
scope.userLocation	PermissionObject	否	位置相关权限声明

# PermissionObject 结构

属性	类型	必填	说明
desc	string	是	小程序获取权限时展示的接口用途说明。最长 30 个字符。1英文字母 = 1字符 , 1汉字 = 2字符。

# scope 列表

scope	对应接口	描述
scope.userInfo	ks.getUserInfo (opens new window)	用户信息
scope.userLocation	ks.getLocation (opens new window)，ks.openLocation，ks.chooseLocation (opens new window)，ks.startLocationUpdate (opens new window)，MapContext.moveToLocation (opens new window)，address (opens new window) 组件	精确地理位置
scope.userLocationBackground	ks.startLocationUpdateBackground (opens new window)	后台定位
scope.record	CameraContext.startRecord (opens new window)，RecorderManager.start (opens new window)	麦克风
scope.writePhotosAlbum	ks.saveImageToPhotosAlbum (opens new window)，ks.saveVideoToPhotosAlbum (opens new window)	添加到相册
scope.camera	camera (opens new window)组件	摄像头

# 代码示例

{
    "pages": [
        "pages/index/index"
    ],
    "permission": {
        "scope.userLocation": {
            "desc": "你的位置信息将用于小程序位置接口的效果展示"
        }
    }
}

# enableShare

类型	说明
boolean	全局是否能够分享(分享接入介绍 (opens new window))

# networkTimeout

网络超时时间，优先级为api参数 > networkTimeout设置 > 默认值60s

字段类型为object,结构为

属性	类型	必填	描述	单位
request	number	否	ks.request超时时间	ms
connectSocket	number	否	ks.connectSocket超时时间	ms
uploadFile	number	否	ks.uploadFile 超时时间	ms
downloadFile	number	否	ks.downloadFile 超时时间	ms

# workers

使用 Worker (opens new window) 处理多线程任务时，设置 Worker 代码放置的目录

# plugins

声明小程序需要使用的插件。

# usingComponents

在 app.json 中声明的自定义组件视为全局自定义组件，在小程序内的页面或自定义组件中可以直接使用而无需再声明。建议仅在此声明几乎所有页面都会用到的自定义组件。

注：全局自定义组件会视为被所有页面依赖，会在所有页面启动时进行初始化，影响启动性能且会占用主包大小。只被个别页面或分包引用的自定义组件应尽量在页面配置中声明。