页面开发

开发 .swan 文件

这部分是每个智能小程序页面的展现模板,类似于 Web 开发中的 HTML ,SWAN 模板中使用的标签均为 SWAN 组件规定的标签。

  1. <view s-for="item in items" class="single-item" bind:tap="oneItemClick" bind:touchstart="oneItemTouchStart" bind:touchmove="oneItemTouchmove" bind:touchcancel="oneItemTouchcancel" bind:touchend="oneItemTouchEnd">
    <image src="{{item.imgsrc}}" class="single-img"></image>
    <view class="single-text-area">
    <text class="single-title">
    {{item.title}}
    </text>
    <view s-if="{{item.tags}}" class="tag-area">
    <text s-for="tag in item.tags" class="{{tag.className}}">
    {{tag.content}}
    </text>
    </view>
    </view>
    </view>
    <view class="view-more" bind:tap="loadMore">
    <text>点击加载更多</text>
    </view>

基础数据绑定

  1. <!-- xxx.swan -->
    <view>
    Hello My {{ name }}
    </view>

  1. // xxx.js
    Page({
    data: {
    name: 'SWAN'
    }
    });

循环

开发者可以通过在元素上添加s-for指令,来渲染一个列表。

示例

  1. <view>
    <view s-for="p in persons">
    {{p.name}}
    </view>
    </view>

  1. Page({
    data: {
    persons: [
    {name: 'superman'},
    {name: 'spiderman'}
    ]
    }
    });

条件

开发者可以通过在元素上添加s-if指令,来在视图层进行逻辑判断:示例

  1. <view s-if="is4G">4G</view>
    <view s-elif="isWifi">Wifi</view>
    <view s-else>Other</view>

  1. Page({
    data: {
    is4G: true,
    isWifi: false
    }
    });

事件

事件处理

开发者可以使用bind: + 事件名来进行事件绑定

  1. <view class="view-more" bind:tap="loadMore">
    点击加载更多
    </view>

  1. Page({
    loadMore: function () {
    console.log('加载更多被点击');
    }
    });

目前支持的事件类型有:

类型触发条件
touchstart手指触摸开始
touchmove手指触摸后进行移动
touchend手指触摸结束
touchcancel手指触摸动作被打断,如来电提醒等
tap手指触摸后马上离开动作

事件对象

当开发者绑定方法到事件,事件触发时,SWAN 会给触发的方法传递事件对象,事件对象因事件不同而不同,目前基础的事件对象结构为:

属性类型说明
typeString事件类型
currentTargetObject事件触发的属性集合

dataset

开发者可以在组件中自定义数据,并在事件发生时,由 SWAN 所在事件对象中,传递给绑定函数。

示例代码:

  1. <view data-swan="1" bind:tap="viewtap">dataset-test</view>

  1. Page({
    viewtap: function (event) {
    console.log('value is:', event.currentTarget.dataset.swan);// 输出1
    }
    });

touches

开发者在接收到触摸类事件后,在事件对象上,可以接收到当前停留在屏幕上的触摸点。

Touch 对象

属性类型描述
pageX , pageYNumber距离文档左上角的距离,横向为 X,纵向为 Y
clientX , clientYNumber距离屏幕视口左上角距离,横向为 X,纵向为 Y

开发 .css 文件

CSS 结尾的样式文件,类似于常规 CSS,用以渲染界面时进行样式描述。

开发 .js 文件

SWAN 智能小程序中,JS 文件是控制交互逻辑的动态语言。如,在 SWAN 模板中书写了以下代码:

  1. <view>{{ me }}</view>
    <button bind:tap="setName">点击变值</button>

在 JS 中可以对于视图中的行为进行监听,并触发界面的变化。

  1. Page({
    setName: function() {
    this.setData({ me: "aaa" });
    }
    })

说明

  • 书写 SWAN App 的逻辑层请使用 JavaScript ;
  • 逻辑层将数据进行更新后,会触发视图更新;
  • 在 app.js 中使用 App 方法、在页面 JS 中使用 Page 方法,来进行页面的逻辑管理;
  • 可以在 SWAN 命名空间下,使用各种 API 端能力;
  • 框架中不可使用 window, document, location, navigator, localStorage, history等Web、浏览器 API。

开发 .json 文件

小程序页面可以使用.json文件来对本页面的窗口表现进行配置。

页面的配置只能设置 app.json 中部分 window 配置项的内容,页面中配置项会覆盖 app.json 的 window 中相同的配置项。

配置示例

  1. {
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "智能小程序接口功能演示",
    "backgroundColor": "#eeeeee",
    "backgroundTextStyle": "light"
    }

页面配置项列表

属性类型默认值描述最低版本
navigationBarBackgroundColorHexColor#000000导航栏背景颜色,如 #000000-
navigationBarTextStyleStringwhite导航栏标题颜色,仅支持 black / white-
navigationBarTitleTextString导航栏标题文字内容-
navigationStyleStringdefault导航栏样式,仅支持以下值:default(默认样式) custom(自定义导航栏),只保留右上角胶囊按钮,在页面级配置优先级高于全局配置iOS 百度 App11.2, Android 百度 App版本11.1
backgroundColorHexColor#ffffff窗口的背景色-
backgroundTextStyleStringdark下拉 loading 的样式,仅支持 dark / light-
enablePullDownRefreshBooleanfalse是否全局开启下拉刷新。详见 Page.onPullDownRefresh-
onReachBottomDistanceNumber50页面上拉触底事件触发时距页面底部距离,单位为px。详见Page.onReachBottom-
disableScrollBooleanfalse设置为 true 则页面整体不能上下滚动。只在页面配置中有效,无法在 app.json 中设置iOS 百度 App10.8,Android暂不支持

说明:

  • 页面的.json只能设置 window 相关的配置项,以决定本页面的窗口表现,所以无需写 window 这个键;
  • navigationStyle 全局配置AndroidiOS从百度 App版本11.1.0开始支持, 但子页面配置支持情况Android百度 App版本11.1开始支持,iOS百度 App版本11.2开始支持, 做低版本兼容时,通过 swan.getSystemInfo 或者 swan.getSystemInfoSync 获取百度 App版本号进行兼容判断,具体见下表;
  • 无其它特殊说明,请使用canIUse或者SWAN基础库版本进行兼容判断。
    navigationStyle配置
顶bar设置iOSAndroidWebView组件页面备注
百度 App定义的顶bar无版本限制无版本限制无版本限制-
顶bar全局透明设置百度 App版本>=11.1百度 App版本>=11.1不生效-
顶bar子页面透明设置百度 App版本>=11.2百度 App版本>=11.1不生效每个page的json文件可以单独配置navigationStyle

适配提示

百度 App原生顶bar高度 = 状态栏高度(通过 swan.getSystemInfo 或者 swan.getSystemInfoSync 获取)+ action高度(iOS为44px,Android为38px)

页面路由

页面栈

框架以栈的形式维护了当前的所有页面。 当发生路由切换的时候,页面栈的表现如下:

路由方式页面栈表现
初始化新页面入栈
打开新页面新页面入栈
页面重定向当前页面出栈,新页面入栈
页面返回页面不断出栈,直到目标返回页,新页面入栈
Tab 切换页面全部出栈,只留下新的 Tab 页面

getCurrentPages()

getCurrentPages() 函数用于获取当前页面栈的实例,以数组形式按栈的顺序给出,第一个元素为首页,最后一个元素为当前页面。

Tip:
不要尝试修改页面栈,会导致路由以及页面状态错误。

路由方式

对于路由的触发方式以及页面生命周期函数如下:

路由方式触发时机路由前页面路由后页面
初始化智能小程序打开的第一个页面onLoad, onShow
打开新页面调用 API swan.navigateTo 或使用组件 onHideonLoad, onShow
页面重定向调用 API swan.redirectTo 或使用组件 onUnloadonLoad, onShow
页面返回调用 API swan.navigateBack 或使用组件 或用户按左上角返回按钮onUnloadonShow
Tab 切换调用 API swan.switchTab 或使用组件 或用户切换 Tab各种情况请参考下表
重启动调用 API swan.reLaunch 或使用组件 onUnloadonLoad, onShow

Tab 切换对应的生命周期(以 A、B 页面为 Tabbar 页面,C 是从 A 页面打开的页面,D 页面是从 C 页面打开的页面为例):

当前页面路由后页面触发的生命周期(按顺序)
AANothing happend
ABA.onHide(), B.onLoad(), B.onShow()
AB(再次打开)A.onHide(), B.onShow()
CAC.onUnload(), A.onShow()
CBC.onUnload(), B.onLoad(), B.onShow()
DBD.onUnload(), C.onUnload(), B.onLoad(), B.onShow()
D(从转发进入)AD.onUnload(), A.onLoad(), A.onShow()
D(从转发进入)BD.onUnload(), B.onLoad(), B.onShow()

说明:

  • navigateTo, redirectTo 只能打开非 tabBar 页面。
  • switchTab 只能打开 tabBar 页面。
  • reLaunch 可以打开任意页面。
  • 页面底部的 tabBar 由页面决定,即只要是定义为 tabBar 的页面,底部都有 tabBar。
  • 调用页面路由带的参数可以在目标页面的 onLoad 中获取。

Page

Page() 函数用来注册一个页面。接受一个 object 参数,其指定页面的初始数据、生命周期函数、事件处理函数等。

object 参数说明:
属性类型描述
dataObject页面的初始数据
onLoadFunction监听页面加载的生命周期函数
onReadyFunction监听页面初次渲染完成的生命周期函数
onShowFunction监听页面显示的生命周期函数
onHideFunction监听页面隐藏的生命周期函数
onUnloadFunction监听页面卸载的生命周期函数
onPullDownRefreshFunction监听用户下拉动作
onReachBottomFunction页面上拉触底事件的处理函数
onShareAppMessageFunction用户点击右上角转发
onErrorFunction错误监听函数
其他不限开发者可以添加任意的函数或数据到 object 参数中,在页面的函数中用 this 可以访问


示例:
  1. Page({
    data: {
    name: 'swan'
    },
    onLoad: function () {

    },
    onReady: function() {
    // Do something when page ready.
    },
    onShow: function() {
    // Do something when page show.
    },
    onHide: function() {
    // Do something when page hide.
    },
    onUnload: function() {
    // Do something when page close.
    },
    onPullDownRefresh: function() {
    // Do something when pull down.
    },
    onReachBottom: function() {
    // Do something when page reach bottom.
    },
    onShareAppMessage: function () {
    // return custom share data when user share.
    }
    });

智能小程序框架,会将同页面的 .swan 文件与 .js 中定义的 Page 对象中的 data ,进行组合渲染。

组件

智能小程序中提供了丰富多样的组件,开发者可以在 .swan 文件中,使用预设好的组件,拼装完成自己的智能小程序的页面。

如:使用 slider 组件

  1. <slider min="200" max="1500" value="{{switchDuration}}"></slider>

即可在页面上展示一个 slider 组件。

也可以在 slider 组件上绑定事件,在相应的组件事件发生时,得到回调与组件信息:

  1. <slider min="200" max="1500" value="{{switchDuration}}" bind:change="changeSlider"></slider>

  1. Page({
    changeSwitchDuration: function () {
    console.log('changeSwitchDuration');
    }
    });

API

智能小程序为开发者提供了百度 App 提供的丰富的端能力。使用方式比较简单,直接调用 SWAN 对象上的端能力方法,或者 Page 对象中 this 上挂载的方法。

showToast

  1. swan.showToast({
    title: '我是标题'
    });

也有很多挂载在 Page 对象与 SWAN 上的方法,如 createCanvasContext ,在 SWAN 对象与 Page 对象上均有。所以,你可以这样用:

  1. Page({
    data: {},
    onLoad: function () {
    this.createCanvasContext();
    }
    });

也可以这样用:

  1. Page({
    data: {},
    onLoad: function () {
    swan.createCanvasContext();
    }
    });

但是推荐使用第一种方法,可以在当前 Page 上精准查找,避免一些问题。具体方法的挂载,在 API 章节 会有详细介绍。

全局配置调试与发布