开发
API

全局配置

app.json 是一个用来对头条小程序进行全局配置的文件,用来配置页面的路径,窗口样式表现等。

app.json 的配置选项如下:

{
  "pages": ["pages/index/index", "pages/logs/logs"],
  "window": {
    "navigationBarTitleText": "Demo"
  },
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "日志"
      }
    ]
  },
  "permission": {
    "scope.userLocation": {
      "desc": "用于提供个性化服务及体验"
    }
  },
  "networkTimeout": {
    "request": 60000,
    "connectSocket": 60000,
    "uploadFile": 60000,
    "downloadFile": 60000
  },
  "cookie": {
    "enableStore": true
  },
  "skeleton": {
    "page": {
      "pages/index/index": "pages/index/index.sk"
    },
    "config": {
      "timeout": 1500
    }
  }
}

配置项说明

属性类型必填描述最低版本
entryPagePathstring小程序默认启动首页
pagesstring[]配置页面路径
windowobject配置默认页面的窗口表现
tabBarobject配置底部 tab 的表现
navigateToMiniProgramAppIdListarray需要跳转的小程序列表,相关 api 见 tt.navigateToMiniProgram1.15.0
permissionobject配置部分授权弹窗的副标题
networkTimeoutobject网络超时时间
subpackagesarray分包结构配置1.88.0
preloadRuleobject分包预下载规则1.88.0
component2boolean启用新的自定义组件流程2.45.0
cookieobjectCookie 机制配置2.45.0
skeletonobject框架骨架屏配置2.47.0

entryPagePath

指定小程序的默认启动路径(首页)。如果不填,将默认为 pages 列表的第一项。不支持带页面路径参数。

{
  "entryPagePath": "pages/index/index"
}

pages

这个字段用于配置小程序用到的所有页面路径,配置每项是 路径 + 文件名 这个结构。配置项的第一个页面路径就是小程序启动展示的第一个页面

需要注意:保证单个页面的 .json.js.ttml.ttss 资源都放在每个页面路径的首层。

如开发目录如下:

|____app.ttss
|____app.json
|____project.config.json
|____pages
|       |____index
|       |        |____index.js
|       |        |____index.json
|       |        |____index.ttml
|       |        |____index.ttss
|____app.js

那么 app.json 应该这样配置:

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

window

这个字段用于设置小程序的状态栏、导航条、标题、窗口背景色。需要注意的是,这里的窗口是指由端上控制的页面,与开发者用代码绘制的页面不是同一个概念。因此对于 backgroundColor 这类配置项,与开发者在代码中编写的样式不会有优先级覆盖关系。

属性类型默认值描述
navigationBarBackgroundColorHexColor#000000导航栏背景颜色,如"#000000";不支持 alpha 值,如"#AABBCCDD"
navigationBarTextStyleStringwhite导航栏标题颜色,仅支持 black/white,同时影响:标题颜色、右胶囊颜色、左返回箭头颜色
navigationBarTitleTextString导航栏标题文字内容
navigationStyleStringdefault导航栏样式默认展示 default 模式,在「功能管理」-「页面结构自定义」完成权限申请后可使用 custom 模式。注意:使用 custom 需要申请权限,未获得权限但仍旧使用自定义能力的小程序,将无法上传代码包。详细参考 获取小程序页面结构自定义能力规范
backgroundColorHexColor#ffffff窗口的背景色
backgroundTextStyleStringdark下拉 loading 的样式,仅支持 dark/light
backgroundColorTopHexColor同 backgroundColor顶部窗口的背景色,仅 iOS 支持
backgroundColorBottomHexColor同 backgroundColor底部窗口的背景色,仅 iOS 支持
enablePullDownRefreshBooleanfalse是否开启下拉刷新,详见页面相关事件处理函数
onReachBottomDistanceNumber50页面上拉触底事件触发时距页面底部距离,单位为 px
transparentTitleStringN/A仅在 navigationStyle 为 default 时该字段生效,用来控制导航栏透明设置。默认 none,支持 always 一直透明 / auto 滑动自适应 / none 不透明
skeletonobject框架骨架屏配置,仅支持配置 config 属性,优先级高于 app.json2.47.0

tabBar

如果你的小程序包含多个 tab(客户端窗口的底部或顶部有 tab 栏可以切换页面),可以通过 tabBar 配置项指定 tab 栏的表现,以及 tab 切换时显示的对应页面。比如设置 tab 展示标题和 tab 颜色等。

属性类型必填默认值描述
colorHexColortab 上的文字默认颜色
selectedColorHexColortab 上的文字选中时的颜色
backgroundColorHexColortab 的背景色
borderStyleStringblacktabbar 上边框的颜色, 仅支持 black/white
listArraytab 的列表,详见 list 属性说明,最少 2 个、最多 5 个 tab
customBooleanfalse自定义 tabbar,主要解决开发者调用 tt.hideTabBar出现的闪烁问题,后续支持更多辅助开发者自定义 tabbar 的能力

其中 list 接受一个数组,数组中的每个项都是一个对象,其属性值如下:

属性类型必填描述
pagePathString页面路径,必须在 pages 中先定义
textStringtab 上按钮文字
iconPathString图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px
selectedIconPathString选中时的图片路径,icon 大小限制为 40kb,建议尺寸为 81px * 81px

当小程序需要使用 tt.navigateToMiniProgram 接口跳转到其他小程序时,需要先在配置文件中声明需要跳转的小程序appId列表,最多允许填写 10 个。

page.json

头条小程序的每一个页面的窗口表现也可以通过页面目录下的.json文件进行配置,这个页面的独立配置会比 app.json 要简单;

如果 app.json 的 window 字段里面配置了某个页面的窗口样式,同时该页面也在自己的 .json 文件中做了对应字段的配置的话,框架会优先采用页面里面的 .json 相应配置项。

具体的配置字段如下:

属性类型默认值描述最低支持版本
navigationBarBackgroundColorHexColor#000000导航栏背景颜色,如"#000000"
navigationBarTextStyleStringwhite导航栏标题颜色,仅支持 black/white
navigationBarTitleTextString导航栏标题文字内容
navigationStyleStringdefault导航栏样式,仅支持 default/custom。custom 模式可自定义导航栏,只保留右上角胶囊状的按钮。注意:custom 需要申请权限,否则会阻碍代码包上传,2022 年 5 月 23 日会强制变动。
backgroundColorHexColor#ffffff窗口的背景色
backgroundTextStyleStringdark下拉 loading 的样式,仅支持 dark/light
enablePullDownRefreshBooleanfalse是否开启下拉刷新,详见页面相关事件处理函数。
disableScrollBooleanfalse设置为 true 则页面整体不能上下滚动;只在 page.json 中有效,无法在 app.json 中设置该项
disableSwipeBackBooleanfalse禁止页面右滑手势返回
onReachBottomDistanceNumber50页面上拉触底事件触发时距页面底部距离,单位为 px
usingComponentsObject自定义组件配置,详情请见“使用自定义组件”
hideRecordMenuButtonBooleanfalse是否要隐藏右上角菜单栏 “拍抖音” 按钮
hideAnchorButtonBooleanfalse是否要对所有场景隐藏 “添加到视频/将此页添加到直播” 按钮
hideAnchorButtonConfigObject可针对具体场景进行隐藏添加到视频/将此页添加到直播”按钮,此字段在 hideAnchorButton 为 false 时生效2.56.0

例子:

{
  "navigationBarBackgroundColor": "#ffffff",
  "navigationBarTextStyle": "black",
  "navigationBarTitleText": "头条接口功能演示",
  "backgroundColor": "#eeeeee",
  "backgroundTextStyle": "light",
  "usingComponents": {
    "my-component": "path/to/a/custom/component"
  },
  "hideAnchorButton": false,
  "hideAnchorButtonConfig": {
    "023009": true"021014": false"021017": true
  }
}

permission

部分授权弹窗的副标题支持开发者自定义,每次提审后会审核该文案,如不通过,直接打回;

不可自定义副标题的权限是:个人信息、手机号。

副标题如下图所示:

如果开发者没有填写某个 scope, 就使用该 scope 的默认文案,各 scope 的默认文案如下:

scope默认文案
scope.userLocation用于提供个性化服务及体验
scope.address一键访问“今日头条/抖音/皮皮虾”收货地址,便捷管理
scope.record用于采集声音
scope.album用于选取图片视频,或保存图片视频到你的相册
scope.camera用于拍摄图片、录制视频

networkTimeout

各类网络请求的超时时间,单位均为毫秒。

属性类型必填默认值描述
requestnumber60000tt.request 的超时时间,单位:毫秒。
connectSocketnumber60000tt.connectSocket 的超时时间,单位:毫秒。
uploadFilenumber60000tt.uploadFile 的超时时间,单位:毫秒。
downloadFilenumber60000tt.downloadFile 的超时时间,单位:毫秒。

subpackages

基础库 1.88.0 及以上版本支持

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

写成 subPackages 也支持

preloadRule

基础库 1.88.0 及以上版本支持

声明分包预下载的规则。

基础库 2.45.0 及以上版本支持

配置小程序 Cookie 相关功能,详见小程序 Cookie 机制。

属性类型必填默认值描述
enableStoreBooleanfalse是否开启小程序 Cookie 存储

skeleton

基础库 2.47.0 及以上版本支持

配置小程序框架骨架屏能力,详见小程序框架骨架屏。

object 类型,其属性值如下:

属性名类型默认值必填说明
configConfig包含超时移除及自动生成配置等
pageobject页面路径同骨架屏文件的对应关系

Config 类型说明

object 类型,属性如下:

属性名类型默认值必填说明
timeoutnumber2000设置骨架屏超时移除时间,单位为 ms。为 0 时关闭超时移除
loading'spin' | 'chiaroscuro' | 'shine''spin'骨架屏显示时的动画
imageobject{shape:'rect', color:'#efefef'}该配置接受 2 个字段,colorshapecolorshape 用于确定骨架页面中图片块的颜色和形状,颜色值支持 16 进制,形状支持两个枚举值,circle (圆形)和 rect(矩形)
buttonobject{color:'#efefef'}该配置接收 1 个字段colorcolor 用来确定骨架页面中被视为按钮块的颜色
backgroundColorstring'#fff'骨架屏背景色
mode'fullscreen' | 'auto''fullscreen'默认为使用绝对定位占满全屏。当对自定义组件使用,作为局部加载的样式时,可设置为 auto,高度随内容高度撑开
cssUnit'px' | 'rem' | 'vw' | 'vh' | 'vmin' | 'vmax''vw'CSS单位。元素绝对定位都使用 vwvh
decimalnumber4生成骨架屏页面中 css 值保留的小数点位数,默认为 4

Bug & Tip

  • Tip:小程序仅支持竖屏,不支持横屏配置;不支持配置窗口大小;
  • Tip:配置 navigationStyle: custom 需要在“小程序开发者平台-功能管理-页面结构自定义”申请权限,否则会阻碍代码包上传,2022 年 5 月 23 日会强制变动。但是 custom 即使申请通过了白名单,能力也会受到限制,主要体现在左上角按钮(新增样式,于 5 月 23 日上线)部分不能定制化。如果要获取左上角按钮位置信息可以参考 getCustomButtonBoundingClientRect。
点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助