教程 其他 框架 组件 接口

script 脚本

用来定义页面数据和实现生命周期接口

语法

支持 ES6 语法

模块声明

可以通过 import 引入功能模块,在代码中调用模块方法(具体参看接口部分文档说明)

import fetch from '@system.fetch'

代码引用

JS 代码引用推荐使用 import 来导入, 例如:

import utils from '../Common/utils.js'

注意: 快应用环境不是 node 环境,不要引用 node 原生模块,如 import fs from 'fs'

对象

页面级组件

属性类型描述
data deprecatedObject | Function页面级组件的数据模型,能够转换为 JSON 对象;属性名不能以$或_开头, 不要使用 for, if, show, tid 等保留字
如果是函数,返回结果必须是对象,在组件初始化时会执行函数获取结果作为 data 的值
使用 data 方式声明的属性会被外部数据覆盖,因此存在一定安全风险,推荐使用下面的 public,protected,private 来声明属性(注意:它们不能与 data 同时声明)
public 1000+Object页面级组件的数据模型,影响传入数据的覆盖机制:public 内定义的属性允许被传入的数据覆盖,如果外部传入数据的某个属性未被声明,在 public 中不会新增这个属性
protected 1000+Object页面级组件的数据模型,影响传入数据的覆盖机制:protected 内定义的属性,允许被应用内部页面请求传递的数据覆盖,不允许被应用外部请求传递的数据覆盖
private 1000+Object页面级组件的数据模型,影响传入数据的覆盖机制:private 内定义的属性不允许被覆盖

自定义组件

属性类型描述
dataObject | Function自定义组件的数据模型,能够转换为 JSON 对象;属性名不能以$或_开头, 不要使用 for, if, show, tid 等保留字
如果是函数,返回结果必须是对象,在组件初始化时会执行函数获取结果作为 data 的值
propsArray | Object定义组件外部可传入的所有属性;属性名不能以$或_开头, 不要使用 for, if, show, tid 等保留字
在模板代码中,请使用短横线分隔命名代替驼峰命名。如,属性定义 props: ['propA'],可通过<tag prop-a='xx'>方式传递到组件内部
支持 prop 验证 1010+

prop 验证 1010+

在自定义组件中,可将 props 定义为带验证需求的对象。其中,key 为属性名,value 为属性对应的验证需求。验证失败则输出错误提示日志,增加 prop 验证有利于规范自定义组件的使用

定义:

属性类型描述
type 1010+-检查属性值的类型。支持单一类型和多种可能类型,可在原生和自定义构造函数中任意选择,单独或组合使用
  • 原生构造函数:String | Number | Boolean | Function | Object | Array | Symbol
  • 自定义构造函数
default 1010+-设置属性的默认值
required 1010+Boolean设置属性是否必填
validator 1010+Function设置自定义验证函数。若函数的返回值为真,则通过验证;否则验证失败

示例:

<script>
  export default {
    props: {
      // 单一类型检查的简写
      propA: Number,
      // 多种可能类型的简写
      propB: [String, Number],
      // 必填的字符串
      propC: {
        type: String,
        required: true
      },
      // 带默认值的数字
      propD: {
        type: Number,
        default: 100
      },
      // 带有默认值的对象
      propE: {
        type: Object,
        default () {
          return { message: 'hello' }
        }
      },
      // 自定义验证函数
      propF: {
        validator (value) {
          return value === 'hello'
        }
      }
    }
  }
</script>

公共对象

属性类型描述
$appObject应用对象
$pageObject页面对象
$validBoolean页面对象是否有效
$visibleBoolean页面是否处于用户可见状态

应用对象

可通过$app访问

属性类型描述
$defObject使用this.$app.$def获取在app.ux中暴露的对象
$dataObject使用this.$app.$data获取在manifest.jsonconfig.data中声明的全局数据

页面对象

可通过$page访问

属性类型描述
actionString获取打开当前页面的 action。仅在当前页面是通过 filter 匹配的方式打开时有效,否则为 undefined。参见manifest 文件
uriString获取打开当前页面的 uri。仅在当前页面是通过 filter 匹配的方式打开时有效,否则为 undefined。参见manifest 文件
name 1030+String获取当前页面路由的名称,与manifest 文件router.pages 中对应的属性名一致
path 1030+String获取当前页面路由的 path,与manifest 文件router.pages 中对应的 path 一致
component 1030+String获取当前页面路由的 component,与manifest 文件router.pages 中对应的 component 一致

方法

数据方法

属性类型参数描述
$setFunctionkey: String
value: Any
添加数据属性,用法:this.$set('key',value) this.$vm('id').$set('key',value)
$deleteFunctionkey: String删除数据属性,用法:this.$delete('key') this.$vm('id').$delete('key')

公共方法

属性类型参数描述
$elementFunctionid: String 组件 id获取指定 id 的组件 dom 对象,如果没有指定 id,则返回根组件 dom 对象用法:<template> <div id='xxx'></div> </template> this.$element('xxx') 获取 id 为 xxx 的 div 组件实例对象 this.$element() 获取根组件实例对象
$rootFunction获取顶层 ViewModel
$parentFunction获取父亲 ViewModel
$childFunctionid: String 组件 id获取指定 id 的自定义组件的 ViewModel 用法:this.$child('xxx') 获取 id 为 xxx 的 div 组件 ViewModel
$vm deprecatedFunctionid: String 组件 id请使用上面this.$child('xxx')替代
$rootElement deprecatedFunction请使用上面this.$element()替代
$forceUpdateFunction更新 ViewModel 数据,可能会触发 DOM 操作,如:创建节点、更新节点、删除节点等;这些 DOM 操作不一定在数据更新时立即执行,而是在开发者的业务代码执行后触发;
若开发者期望数据更新时立即执行相应的 DOM 操作,可使用:this.$forceUpdate();一般不推荐使用

事件方法

属性类型参数描述
$onFunctiontype: String 事件名
handler: Function 事件句柄函数
添加事件处理句柄用法:this.$on('xxxx', this.fn) fn 是在<script>中定义的函数
$offFunctiontype: String 事件名
handler: Function 事件句柄函数
删除事件处理句柄用法:this.$off('xxxx', this.fn) this.$off('xxx') 删除指定事件的所有处理句柄
$dispatchFunctiontype: String 事件名向上层组件发送事件通知用法:this.$dispatch('xxx')正常情况下,会一直向上传递事件(冒泡)如果要停止冒泡,在事件句柄函数中调用evt.stop()即可
$broadcastFunctiontype: String 事件名向子组件发送事件通知用法:this.$broadcast('xxx')正常情况下,会一直向下传递事件如果要停止传递,在事件句柄函数中调用evt.stop()即可
$emitFunctiontype: String 事件名
data: Object 事件参数
触发事件,对应的句柄函数被调用用法:this.$emit('xxx') this.$emit('xxx', {a:1})传递的事件参数可在事件回调函数中,通过evt.detail来访问,例如evt.detail.a
$emitElementFunctiontype: String 事件名
data: Object 事件参数
id: String 组件 id (默认为-1 代表根元素)
触发组件事件, 对应的句柄函数被调用用法:this.$emitElement('xxx', null, 'id') this.$emitElement('xxx', {a:1})传递的事件参数可在事件回调函数中,通过evt.detail来访问,例如evt.detail.a
$watchFunctiondata: String 属性名, 支持'a.b.c'格式,不支持数组索引
handler: String 事件句柄函数名, 函数的第一个参数为新的属性值,第二个参数为旧的属性值
动态添加属性/事件绑定,属性必须在 data 中定义,handler 函数必须在<script>定义;当属性值发生变化时事件才被触发用法:this.$watch('a','handler')

应用方法 1010+

可通过$app访问

属性类型参数描述
exit 1010+Function退出快应用,结束应用生命周期。
调用方法:this.$app.exit()

页面方法

可通过$page访问

属性类型参数描述
setTitleBarFunctiontext: String 标题栏文字
textColor: String 文字颜色
backgroundColor: String 背景颜色
backgroundOpacity 1000+: Number 背景透明度
menu 1000+: Boolean 是否在标题栏右上角显示菜单按钮
设置当前页面的标题栏用法:this.$page.setTitleBar({text:'Hello', textColor:'#FF0000', backgroundColor:'#FFFFFF', backgroundOpacity:0.5, menu: true})
finish 1010+Function从本页面退出,结束页面生命周期。
调用方法:this.$page.finish()

生命周期接口

页面生命周期

属性类型参数返回值描述触发时机
onInitFunction监听页面初始化当页面完成初始化时调用,只触发一次
onReadyFunction监听页面创建完成当页面完成创建可以显示时触发,只触发一次
onShowFunction监听页面显示当进入页面时触发
onHideFunction监听页面隐藏当页面跳转离开时触发
onDestroyFunction监听页面退出当页面跳转离开(不进入导航栈)时触发
onBackPressFunctionBoolean监听返回按钮动作当用户点击返回按钮时触发。返回 true 表示页面自己处理返回逻辑,返回 false 表示使用默认的返回逻辑,不返回值会作为 false 处理
onMenuPressFunction监听菜单按钮动作当用户点击菜单按钮时触发

页面的生命周期接口的调用顺序:

  • 打开页面 A:onInit() -> onReady() -> onShow()
  • 在页面 A 打开页面 B:onHide()
  • 从页面 B 返回页面 A:onShow()
  • A 页面返回:onBackPress() -> onHide() -> onDestroy()

应用生命周期

onCreate()

监听应用创建,应用创建时调用

参数

onDestroy()

监听应用销毁,应用销毁时调用

参数

onError(Object) 1030+

监听应用报错,应用捕获异常时调用

参数
参数名类型描述
messageString错误描述
stackString调用栈

消息通道(BroadcastChannel) 1000+

用来实现不同页面之间的相互通信。

接口说明

在 BroadcastChannel 的构造函数中,只支持接受一个参数,就是"频道名称"(channel name)

比如:

const test = new BroadcastChannel('channel')

BroadcastChannel 定义的接口如下:

declare interface BroadcastChannel = {
  name: string,
  postMessage: (message: any) => void;
  onmessage: (event: MessageEvent) => void;
  close: () => void;
}

消息对象(MessageEvent)的类型定义如下:

declare interface MessageEvent = {
  type: string, // "message"
  data: any
}

对参数的说明:

名称类型参数描述
nameStringString:频道名称频道名称,区分不同的消息频道(注意:不同频道之间不可通信)。
postMessageFunctionObject: 消息内容用于在当前频道中广播消息。
onmessageFunctionEvent:消息对象订阅消息。在频道中接收到广播消息之后,会给所有订阅者派发消息事件。
closeFunction关闭当前的频道。

用法

假设在我们的应用中,有 A、B、C 三个页面

在页面 A 中:

const pageA = new BroadcastChannel('channel1')
pageA.postMessage('haha!')

在页面 B 中:

const pageB = new BroadcastChannel('channel1')

在页面 C 中:

const pageC = new BroadcastChannel('channel1')
pageC.onmessage = function(event) {
  console.log(event.data)
  pageC.postMessage('hello, i am here!')
}

这样,页面 A 、B 、C 都创建一个监听了 'channel1' 频道的 BroadcastChannel 对象,它们之间可以通过这个对象实现互相通信。

当 pageA 发布了 'haha!' 消息时,pageC 将收到一个消息事件,其 data 字段等于 'haha!',然后也向频道中回复一条消息。注意:自己不会收到自己发的消息。

但是 pageB 并不会收到这些消息,因为他没有实现 onmessage 方法,相当于没有接收频道中的消息,所以他实际上不是一个订阅者。

注意:在 pageA 销毁 channel 当前不与页面 context 进行上下文绑定,需要主动关闭消息通道,如下所示:

const pageA = new BroadcastChannel('tom')
pageA.close()

条匹配 "" 的结果

    没有搜索到与 "" 相关的内容