配置 app.json 文件

可以通过配置 app.json 文件,设置 SWAN 的界面、路径、多 TAB 等。

app.json 配置项列表如下

属性 类型 必填 描述
pages Array.< string> 设置页面路径
window Object 设置页面展现
preloadRule Object 分包预下载规则
tabBar Object 底部 tab 栏的表现
requiredBackgroundModes string[] 需要在后台使用的能力,如「音乐播放」
subPackages Array.< object> 分包结构配置
networkTimeout Object 网络超时
permission Object 小程序接口权限相关设置
routes Array.< object> 小程序自定义路由相关设置
dynamicLib Object 引入动态库,详情请参考使用动态库

代码示例

{
    "pages": [
        "component/component",
        "api/api"
    ],
    "subPackages": [
        {
            "root": "subpackage",
            "pages": [
                "pages/subpageone/subpageone",
                "pages/subpagetwo/subpagetwo"
            ]
        }
    ],
    "window": {
        "navigationBarTitleText": "Demo",
        "navigationBarBackgroundColor": "#000000",
        "navigationBarTextStyle": "white",
        "navigationStyle": "default",
        "backgroundColor": "#ffffff",
        "backgroundTextStyle": "dark",
        "enablePullDownRefresh": "true",
        "onReachBottomDistance":"50"
    },
    "preloadRule":
    {
       "pages/index": {
            "network": "all",
            "packages": ["subpackage"]
        }
    },
    "tabBar": {
        "list": [
            {
                "pagePath": "component/component",
                "text": "首页",
                "iconPath":"/images/API_normal.png",
                "selectedIconPath":"/images/API_selected.png"
            },
            {
                "pagePath": "api/api",
                "text": "详情",
                "iconPath":"/images/component_normal.png",
                "selectedIconPath":"/images/component_selected.png"
            }
        ],
        "backgroundColor" : "#ffffff",
        "borderStyle": "white",
        "color": "#000",
        "selectedColor": "#6495ED"
    },
    "requiredBackgroundModes": ["audio"],
    "networkTimeout": {
        "request": 30000,
        "connectSocket": 10000,
        "uploadFile": 10000,
        "downloadFile": 10000
    },
    "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息将用于小程序位置接口的效果展示" // 高速公路行驶持续后台定位
    }
  }
}

# pages

pages 接受一个数组,每一项都是一个字符串,指定 SWAN App 都有哪些页面。每一项代表页面的[路径 + 文件名],数组第一项代表 SWAN 初始页面。

SWAN 中新增或减少页面的话,需要在 pages 中进行配置。

配置项中不需要加文件后缀名, SWAN 会自动解析。

如,开发目录为:

├── app.js
├── app.json
├── app.css
├── project.config.json
└──  pages
    └── index
        ├── index.swan
        ├── index.css
        ├── index.js
        └── index.json
    └── detail
        ├── detail.swan
        ├── detail.css
        ├── detail.js
        └── detail.json

则需要在 app.json 中书写

代码示例

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

提示

  • 开发者工具在 app.json 的 pages 中填写页面路径可自动生成文件夹。

# window

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

属性 类型 默认值 描述 最低版本
navigationBarBackgroundColor HexColor #000000 导航栏背景颜色,如 "#000000"
navigationBarTextStyle String white 导航栏标题颜色,目前有效值 black/white
navigationBarTitleText String 导航栏标题文字内容
navigationStyle String default 导航栏样式,有效值:default(默认样式) custom(自定义导航栏),只保留右上角胶囊按钮 2.10.34
backgroundColor HexColor #ffffff 背景颜色
backgroundTextStyle String dark 下拉背景字体、loading 图的样式,有效值 dark/light
backgroundColorTop HexColor #ffffff 顶部窗口的背景色,仅 iOS 支持
backgroundColorBottom HexColor #ffffff 底部窗口的背景色,仅 iOS 支持
enablePullDownRefresh Boolean false 是否开启下拉刷新
onReachBottomDistance Number 50 页面上拉触底事件触发时距页面底部距离,单位为 px
textSizeAdjust String auto 小程序页面是否禁止响应字体大小的设置,有效值:auto(默认响应)、none(不响应) 基础库版本 3.200.1

注意

  • navigationStyle 全局配置AndroidiOS从基础库版本 2.10.34 开始支持, 但子页面配置支持情况Android从基础库版本 2.10.34 开始支持,iOS从基础库 3.0.39 开始支持, 做低版本兼容时,通过 swan.getSystemInfo 或者 swan.getSystemInfoSync 获取百度 APP 版本号进行兼容判断,具体见下表;
  • 无其它特殊说明,请使用 SWAN 基础库版本进行兼容判断。

navigationStyle 配置

顶 bar 设置 iOS Android WebView 组件页面 备注
百度 APP 定义的顶 bar 无版本限制 无版本限制 无版本限制
顶 bar 全局透明设置 基础库版本 2.10.34 基础库版本 2.10.34 不生效
顶 bar 子页面透明设置 基础库版本 2.10.34 基础库版本 2.10.34 不生效 每个 page 的 json 文件可以单独配置 navigationStyle

适配提示

原生顶bar高度=状态栏高度(statusBarHeight)+顶部导航栏高度(navigationBarHeight);可通过 swan.getSystemInfo 或者 swan.getSystemInfoSync 获取。

代码示例

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

参考示例: 适配各种移动机型(包含 iPad 等设备)

在开发者工具中预览效果

    <view class="wrap">
    	<view class="navBar">
    		<view class="status-height" style="height:{{statusHeight}}px">
    		</view>
    		<view class="nav" style="height:{{navHeight}}px;line-height:{{navHeight}}px">
    			<view class="nav-icon-back" bindtap="goBack">
    				<image src="{{backIcon}}"></image>
    			</view>
    			<view class="nav-icon-home" bindtap="goHome">
    				<image src="{{homeIcon}}"></image>
    			</view>
    			<view class="nav-title">{{navTitle}}
    			</view>
    		</view>
    	</view>
    </view>
    
    Component({
        properties: {
            statusHeight: {
                type: Number,
                value: 0
            },
            navHeight: {
                type: Number,
                value: 0
            },
            navTitle: {
                type: String,
                value: ''
            },
            backIcon: {
                type: String,
                value: ''
            },
            homeIcon: {
                type: String,
                value: ''
            }
        },
    
        data: {
        }, // 私有数据,可用于模版渲染
        created: function () {
        },
    
        // 生命周期函数,可以为函数,或一个在methods段中定义的方法名
        attached: function () {
            this.getHeightInfo()
        },
    
        detached: function () { },
    
        methods: {
            getHeightInfo() {
                swan.getSystemInfo({
                    success: res => {
                        this.setData({
                            statusHeight: res.statusBarHeight, //状态栏高度
                            navHeight: res.navigationBarHeight//导航栏高度
                        })
                    }
                })
            },
            goBack() {
                this.triggerEvent('goBack', { back: '您点击了返回' })
            },
            goHome() {
                this.triggerEvent('goHome', { home: '您点击了返回首页' })
            },
        }
    });
    

    代码示例 - 错误写法

    json 文件看起来同 JavaScript 的对象表达方式十分相似,但是有所不同。

    json 的 Key 必须包裹在一个双引号中,在实践中,编写 JSON 的时候,忘了给 Key 值加双引号或者是把双引号写成单引号是常见错误。

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

    # tabBar

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

    属性 类型 必填 描述
    backgroundColor HexColor tab 的背景色。
    borderStyle String tabBar 边框颜色。有效值 black/white 两种边框颜色,默认值为 black 。
    color HexColor tab 上文字的默认颜色。
    list Array tab 的列表,列表个数 2~5 个。
    list 接受一个数组,tab 按数组的顺序排序,每个项都是一个对象,其属性值如下:
    - pagePath:已在 pages 中定义的页面路径;类型:String;必填项。
    - text:tab 上显示的文字信息;类型:String;必填项。
    - iconPath:图片路径,icon 大小限制为 40kb,建议尺寸为 78px*78px,不支持网络图片;类型:String;非必填项。
    - selectedIconPath:选中时的图片路径,icon 规格同上;类型:String;非必填项。
    selectedColor HexColor tab 上的文字选中时的颜色。

    代码示例

    {
        "tabBar": {
            "list": [
                {
                    "pagePath": "pages/index/index",
                    "text": "首页",
                    "iconPath":"/images/API_normal.png",
                    "selectedIconPath":"/images/API_selected.png"
            },
                {
                    "pagePath": "pages/detail/detail",
                    "text": "详情",
                    "iconPath":"/images/component_normal.png",
                    "selectedIconPath":"/images/component_selected.png"
                }
            ],
            "backgroundColor" : "#ffffff",
            "borderStyle": "white",
            "color": "#000",
            "selectedColor": "#6495ED"
        }
    }
    
    • 自定义 tabbar

    代码示例

    <view class="wrap">
        <view class="contentLast">
            <view class="icon-bg border-top border-bottom {{color}}">
                <view class="icon-item" data-index="index4" bindtap="setTabBarStyle">
                    <image class="image" src="{{isActive4 == 'index4' ? 'https://b.bdstatic.com/searchbox/icms/searchbox/images/index-inverse-active.png' : 'https://b.bdstatic.com/searchbox/icms/searchbox/images/index-inverse-ash.png'}}" ></image>
                    <view class="{{isActive4 == 'index4' ? 'imageNameColor' : 'imageNameColorAsh'}}">首页</view>
                </view>
                <view class="icon-item" data-index="tinyVideo4" bindtap="setTabBarStyle">
                    <image class="image" src="{{isActive4 == 'tinyVideo4' ? 'https://b.bdstatic.com/searchbox/icms/searchbox/images/video-inverse-active.png' : 'https://b.bdstatic.com/searchbox/icms/searchbox/images/video-inverse-ash.png'}}" ></image>
                    <view class="{{isActive4 == 'tinyVideo4' ? 'imageNameColor' : 'imageNameColorAsh'}}">小视频</view>
                </view>
                <view class="icon-item" data-index="centre4" bindtap="setTabBarStyle">
                    <image class="image" src="{{isActive4 == 'centre4' ? 'https://b.bdstatic.com/searchbox/icms/searchbox/images/centre-inverse-active.png' : 'https://b.bdstatic.com/searchbox/icms/searchbox/images/centre-inverse-ash.png'}}"></image>
                    <view class="{{isActive4 == 'centre4' ? 'imageNameColor' : 'imageNameColorAsh'}}">个人中心</view>
                </view>
            </view>
        </view>
    </view>
    
    Page({
        data: {
            color: 'firstTab',
            isActive: 'index1',
            isActive2: 'index2',
            isActive3: 'index3',
            isActive4: 'index4'
        },
        setTabBarStyle(e) {
            this.setData('isActive4', e.currentTarget.dataset.index);
            e.currentTarget.dataset.index === 'index4'
            ? this.setData({
                'color': 'firstTab'
            })
            : '';
    
            console.log(this.data.color);
            e.currentTarget.dataset.index === 'tinyVideo4'
            ? this.setData({
                'color': 'secondTab'
            })
            : '';
    
            e.currentTarget.dataset.index === 'centre4'
            ? this.setData({
                'color': 'thirdTab'
            })
            : '';
        }
    });
    

    # requiredBackgroundModes

    基础库 3.50.36 及以上版本支持

    申明需要后台运行的能力,类型为数组。目前支持以下项目:

    audio: 后台音乐播放

    代码示例

    {
        "pages": ["pages/index/index"],
        "requiredBackgroundModes": ["audio"]
    }
    

    注:在此处申明了后台运行的接口,开发版和体验版上可以直接生效,正式版还需通过审核。

    # networkTimeout

    各类网络请求的超时时间。

    属性 类型 必填 默认值 说明
    request number 60000 swan.request 的超时时间,单位:毫秒。
    connectSocket number 60000 swan.connectSocket 的超时时间,单位:毫秒。
    uploadFile number 60000 swan.uploadFile 的超时时间,单位:毫秒。
    downloadFile number 60000 swan.downloadFile 的超时时间,单位:毫秒。

    代码示例

    
    "networkTimeout": {
        "request": 30000,
        "connectSocket": 10000,
        "uploadFile": 10000,
        "downloadFile": 10000
    }
    
    

    # permission

    小程序接口权限相关设置。

    属性 类型 必填 默认值 说明
    scope.userLocation PermissionObject 位置相关权限声明

    # PermissionObject 结构

    属性 类型 必填 默认值 说明
    desc string 小程序获取权限时展示的接口用途说明。最长 30 个字符

    代码示例

    
    "permission": {
      "scope.userLocation": {
        "desc": "你的位置信息将用于小程序位置接口的效果展示" // 高速公路行驶持续后台定位
      }
    }
    
    

    # routes

    基础库 3.160.3 及以上版本支持

    routes 为一个数组,数组中每一项代表一组路由规则,具体包含字段为:

    属性 类型 必填 描述 示例
    path string 访问路径 "home"
    page string 页面源码文件路径,从小程序包根目录开始的文件路径 "pages/home/index"

    代码示例

    // app.json
    {
        "pages": [
            "pages/home/home",
            "pages/list/list",
            "pages/detail/detail"
        ],
        "subPackage": [
            {
                "root": "packageA",
                "pages": [
                    "pages/home/home",
                    "pages/list/list",
                    "pages/detail/detail"
                ]
            }
        ],
        "routes": [
            {
                "path": "home", // 投放入口,scheme中的path
                "page": "pages/home/home" // 真实的物理存储路径
            },
            {
                "path": "list",
                "page": "pages/list/list"
            },
            {
                "path": "foo/bar",
                "page": "pages/list/list"
            }
        ]
    }
    

    更多详见自定义路由