自定义组件

基础库

npm 功能

SJS 语法参考

小程序配置

我的收藏

全局配置

app.json 是小程序的全局配置文件，用来配置页面文件的路径、窗口样式、网络超时时间、多 tab 等属性的表现。

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
    }
  }
}

配置项说明

属性	类型	必填	描述	最低支持版本
entryPagePath	string	否	小程序默认启动首页
pages	string[]	是	配置页面路径
window	object	否	配置默认页面的窗口表现
tabBar	object	否	配置底部 tab 的表现
navigateToMiniProgramAppIdList	array	否	需要跳转的小程序列表，相关 API 请参见 tt.navigateToMiniProgram。	1.15.0
permission	object	否	配置部分授权弹窗的副标题
networkTimeout	object	否	网络超时时间
subpackages	array	否	分包结构配置	1.88.0
preloadRule	object	否	分包预下载规则	1.88.0
component2	boolean	否	支持在 `created` 生命周期中修改自定义组件初始数据，开启后，自定义组件将在 `created` 生命周期执行完成后开始渲染。从而解决当初始数据依赖计算逻辑时，自定义组件展示数据由默认值到真正数据切换时的闪动问题。注意：不涉及初始渲染数据的逻辑放到其他生命周期中，避免影响整体渲染耗时	2.45.0
cookie	object	否	Cookie 机制配置	2.45.0
skeleton	object	否	框架骨架屏配置	2.47.0
workers	string	否	Worker 代码放置的目录或单个文件路径	2.78.0
referrerPolicy	object	否	支持开发者自定义配置网络资源添加 referer 请求头，详情可见：网络资源请求添加 referer 规则	3.16.0
usePrivacyCheck	boolean	否	启用隐私相关功能，详情可见：小程序隐私协议开发指南	3.19.0
publishVideoHookPriorityList	string[]	否	配置 openType="uploadDouyinVideo" 以外的其他「视频发布和挂载」场景，使用 Page.onShareAppMessage 还是 Page.onShareAppMessage 钩子函数，详见 publishVideoHookPriorityList	3.2.0

说明：

•

小程序仅支持竖屏，不支持横屏配置；不支持配置窗口大小。

•

配置 navigationStyle: custom 需要在“小程序开发者平台-功能管理-页面结构自定义”申请权限，否则会阻碍代码包上传，2022 年 5 月 23 日会强制变动。但是 custom 即使申请通过了白名单，能力也会受到限制，主要体现在左上角按钮（新增样式，于 5 月 23 日上线）部分不能定制化。如果要获取左上角按钮位置信息可以参考 getCustomButtonBoundingClientRect。

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 这类配置项，与开发者在代码中编写的样式不会有优先级覆盖关系。

属性	类型	默认值	描述	最低支持版本
navigationBarBackgroundColor	HexColor	#000000	导航栏背景颜色，如"#000000"；不支持 alpha 值，如"#AABBCCDD"。
navigationBarTextStyle	String	white	导航栏标题颜色，仅支持 black/white，同时影响：标题颜色、右胶囊颜色、左返回箭头颜色。
navigationBarTitleText	String		导航栏标题文字内容
navigationStyle	String	default	导航栏样式，仅支持 default/custom。custom 模式可自定义导航栏，具体效果样式效果参照页面自定义结构文档。具体申请入口在「控制台」-「我的应用」-「具体小程序」-「能力」-「互动能力」中完成自定义导航栏权限申请。注意：custom 需要申请权限，否则会阻碍代码包上传，2022 年 5 月 23 日会强制变动。详细参考获取小程序页面结构自定义能力规范。
backgroundColor	HexColor	#ffffff	窗口的背景色
backgroundTextStyle	String	dark	下拉 loading 的样式，仅支持 dark/light。
backgroundColorTop	HexColor	同 backgroundColor	顶部窗口的背景色，仅 iOS 支持。
backgroundColorBottom	HexColor	同 backgroundColor	底部窗口的背景色，仅 iOS 支持。
enablePullDownRefresh	Boolean	false	是否开启下拉刷新，详见页面相关事件处理函数。
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位为 px。
transparentTitle	String	N/A	仅在 `navigationStyle` 为 `default` 时该字段生效，用来控制导航栏透明设置。支持： •always：一直透明 •auto：滑动自适应 •none：不透明默认为 none。
skeleton	object	否	框架骨架屏配置，仅支持配置 config 属性，优先级高于 `app.json`。	2.47.0

tabBar

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

属性	类型	必填	默认值	描述
color	HexColor	是		tab 上的文字默认颜色
selectedColor	HexColor	是		tab 上的文字选中时的颜色
backgroundColor	HexColor	是		tab 的背景色
borderStyle	String	否	black	tabbar 上边框的颜色，仅支持 black/white。
list	Array	是		tab 的列表，详见 list 属性说明，最少 2 个、最多 5 个 tab。
custom	Boolean	否	false	自定义 tabbar，主要解决开发者调用 tt.hideTabBar 出现的闪烁问题，后续支持更多辅助开发者自定义 tabbar 的能力。

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

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

navigateToMiniProgramAppIdList

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

permission

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

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

副标题如下图所示：

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

scope	默认文案
scope.userLocation	通过 GPS 或网络位置信息获取你的大致地理位置，用于向你推荐附近的服务。用于提供个性化服务及体验。
scope.address	请求读取你在”抖音/抖音极速版/...“中的地址簿，帮助你填写地址信息。
scope.record	用于录制音频，帮助你发布音视频内容，或使用其他需要使用此权限的功能。
scope.album	用于读取相册中的图片、视频，或在相册中保存图片、视频。
scope.camera	用于拍摄照片或视频，帮助你发布音视频内容，或使用其他需要使用此权限的功能。

networkTimeout

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

属性	类型	必填	默认值	描述
request	number	否	60000	tt.request 的超时时间，单位：毫秒。
connectSocket	number	否	60000	tt.connectSocket 的超时时间，单位：毫秒。
uploadFile	number	否	60000	tt.uploadFile 的超时时间，单位：毫秒。
downloadFile	number	否	60000	tt.downloadFile 的超时时间，单位：毫秒。

subpackages

基础库 1.88.0 及以上版本支持。

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

写成 subPackages 也支持。

preloadRule

基础库 1.88.0 及以上版本支持。

声明分包预下载的规则。

基础库 2.45.0 及以上版本支持。

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

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

skeleton

基础库 2.47.0 及以上版本支持。

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

object 类型，其属性值如下：

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

Config 类型说明

object 类型，属性如下：

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

workers

基础库 2.78.0 及以上版本支持。

使用 Worker 处理多线程任务时，设置 Worker 代码放置的目录或单个文件路径。

referrerPolicy

基础库 3.16.0 及以上版本支持。

支持开发者自定义配置网络资源添加 referer 请求头，详情可见：网络资源请求添加 referer 规则。

referrerPolicy 是一个 string key-object value 键值对，目前支持以下能力配置 referer 规则：

值	能力	默认规则
canvasImage	Canvas.createImage	no-referrer，不添加 referer
video	video 组件	origin，添加 referer
previewImage	tt.previewImage	origin，添加 referer
livePlayer	live-player 组件	origin，添加 referer
innerAudioContext	InnerAudioContext	no-referrer，不添加 referer
backgroundAudioManager	BackgroundAudioManager	no-referrer，不添加 referer

具体规则是一个 object，属性如下：

参数	类型	描述
policy	string	添加 referer 的规则，有效值有且仅有两个： •origin：发送完整的 referer •no-referrer：不发送 referer 若 urlList 和 domainList 都不传，则 policy 规则适用于所有 url。若 urlList 或 domainList 有值，policy 规则只适用于匹配上的 url。例：policy="no-referrer", urlList=["www.abc.com"]，则只有 www.abc.com 不添加 referer，其余 url 均添加 referer
urlList	string[]	适用 policy 规则的 url 列表，完全匹配。若 urlList 和 domainList 都不传，则 policy 规则适用于所有 url。
domainList	string[]	适用 policy 规则的域名列表，支持泛域名，配置了 abc.com，那么 *.abc.com 都适用 policy 规则。若 urlList 和 domainList 都不传，则 policy 规则适用于所有 url。

publishVideoHookPriorityList

基础库 3.2.0 及以上版本支持，用于配置 openType="uploadDouyinVideo" 以外的其他「视频发布和挂载」场景，使用 Page.onUploadDouyinVideo 还是 Page.onShareAppMessage 钩子函数。

以下配置代表优先使用 Page.onUploadDouyinVideo 钩子函数，没有才会使用 Page.onShareAppMessage 钩子函数。

{ 
  "publishVideoHookPriorityList": ["onUploadDouyinVideo", "onShareAppMessage"]
}

不配置 publishVideoHookPriorityList 或者其他配置方式，都代表使用 Page.onShareAppMessage 钩子函数。

页面配置

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

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

具体的配置字段如下：

属性	类型	默认值	描述	最低支持版本
navigationBarBackgroundColor	HexColor	#000000	导航栏背景颜色，如"#000000"。
navigationBarTextStyle	String	white	导航栏标题颜色，仅支持 black/white。
navigationBarTitleText	String		导航栏标题文字内容
navigationStyle	String	default	导航栏样式，仅支持 default/custom。custom 模式可自定义导航栏，具体效果样式效果参照页面自定义结构文档。具体申请入口在「控制台」-「我的应用」-「具体小程序」-「能力」-「互动能力」中完成自定义导航栏权限申请。注意：custom 需要申请权限，否则会阻碍代码包上传，2022 年 5 月 23 日会强制变动。
backgroundColor	HexColor	#ffffff	窗口的背景色
backgroundTextStyle	String	dark	下拉 loading 的样式，仅支持 dark/light。
enablePullDownRefresh	Boolean	false	是否开启下拉刷新，详见页面相关事件处理函数。
disableScroll	Boolean	false	设置为 true 则页面整体不能上下滚动；只在 page.json 中有效，无法在 app.json 中设置该项。
disableSwipeBack	Boolean	false	禁止页面右滑手势返回
onReachBottomDistance	Number	50	页面上拉触底事件触发时距页面底部距离，单位为 px。
usingComponents	Object		自定义组件配置，详情请见“使用自定义组件”。
hideRecordMenuButton	Boolean	false	是否要隐藏右上角菜单栏 “拍抖音” 按钮。
hideAnchorButton	Boolean	false	是否要对所有场景隐藏 “添加到视频/将此页添加到直播” 按钮。
hideAnchorButtonConfig	Object		可针对具体场景进行隐藏添加到视频/将此页添加到直播”按钮，此字段在 `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
  }
}

项目配置

project.config.json是小程序的项目配置文件，主要包括了针对小程序项目配置的一些信息，例如项目名称，App ID，项目语法，编译配置等内容。这些内容可以在开始创建项目的过程中通过开发者工具生成，开发者也可以根据需要进行修改和配置。

配置项说明

字段名	类型	说明
appid	string	小程序的 AppID
miniprogramRoot	string	指定小程序源码的目录（需为相对路径）
setting	object	项目配置
projectname	string	项目名字
disablePrivate	boolean	是否开启私有配置
packOptions	object	打包配置选项

setting

setting 中可以指定以下设置：

字段名	类型	说明
es6	boolean	是否启用 es6 转 es5
urlCheck	boolean	不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书
autoCompile	boolean	修改文件的时候自动编译
mockUpdate	boolean	下次编译模拟更新
scripts	boolean	启动自定义处理命令
mockLogin	boolean	开启宿主登录模拟
compileHotReLoad	boolean	是否开启热重载
nativeCompile	boolean	是否开启原生语言快速编译
IDEPreviewHotRestartCache	boolean	是否开启预览热启动缓存
useCompilerPlugins	string[]	编译配置
bigPackageSizeSupport	boolean	调试阶段放宽包体积限制
webDetect	boolean	是否开启 Web 化配置检测

useCompilerPlugins

编译插件配置，目前支持 typescript。

例如：

{
    "setting": {
        "useCompilerPlugins": ["typescript"]
    }
}

表示项目支持编译 typescript 文件。

packOptions

注：此配置自 4.2.7 版本起支持。

packOptions 用以配置项目在打包过程中的选项。

目前该配置支持include和ignore两个配置，其中include用以配置打包过程中需要强制带上的文件（仅限后缀白名单内），匹配的这些文件将会出现在预览或上传的结果内（该字段的优先级高于ingore字段）。ignore用以配置打包过程中需要忽略的文件，被忽略的文件不会出现在预览或上传的结果内，并且包体积计算时也会忽略这些文件。

packOptions.ignore 和 packOptions.include 为一对象数组，对象元素类型如下：

字段名	类型	说明
value	string	路径后取值
type	string	类型

其中，type 可以取的值为 folder、file、suffix、prefix、regexp、glob，分别对应文件夹、文件、后缀、前缀、正则表达式、Glob 规则。

注： value 字段的值若表示文件或文件夹路径，以小程序目录 (miniprogramRoot) 为根目录。

示例配置如下。

{
    "packOptions": {
        "ignore": [
            { "type": "file", "value": "test-folder/test.js" },
            { "type": "folder", "value": "test-folder" },
            { "type": "suffix", "value": ".jpeg" },
            { "type": "prefix", "value": "img" },
            { "type": "glob", "value": "test-folder/**/*.js" },
            { "type": "regexp", "value": "\\.sjs$" }
         ]
    }
}