# 全局助手方法和属性
# api
描述: 即window.api, 在Vue实例中通过this.api使用，详情请查询APICloud 官方文档 - API 对象 (opens new window)
# 属性 (opens new window)
# 常量 (opens new window)
# 事件 (opens new window)
# 方法 (opens new window)
用例:
this.api.appId
# $api
类型:object描述: APICloud 官方封装的 js 框架，在Vue实例中通过this.$api使用, 具体参数详情请查询APICloud 官方文档 - APICloud 前端框架 (opens new window), 所有方法如下：
用例:
this.$api.setStorage('username', username)
# $req
描述: 网络请求，PC调试时，使用的是axios, wifi 调试和正式打包时使用的是api.ajax()方法
详情请查看网络请求
# element.getRect
返回值:DOMRect描述: 返回元素的大小及其相对于视口的位置, 是Element.getBoundingClientRect()的封装。
DOMRect:
| 属性 | 类型 | 描述 |
|---|---|---|
| bottom | float | Y 轴，相对于视口原点（viewport origin）矩形盒子的底部。只读。 |
| height | float | 矩形盒子的高度（等同于 bottom 减 top）。只读。 |
| left | float | X 轴，相对于视口原点（viewport origin）矩形盒子的左侧。只读。 |
| right | loat | X 轴，相对于视口原点（viewport origin）矩形盒子的右侧。只读。 |
| top | float | Y 轴，相对于视口原点（viewport origin）矩形盒子的顶部。只读。 |
| width | float | 矩形盒子的宽度（等同于 right 减 left）。只读。 |
| x | float | X 轴，相对于视口原点（viewport origin）矩形盒子的左侧。只读。 |
| y | float | Y 轴，相对于视口原点（viewport origin）矩形盒子的顶部。只读。 |
用例:
this.$api.dom('#id').getRect;
# element.computedStyle
返回值:CSSStyleDeclaration描述: 返回一个对象，该对象在应用活动样式表并解析这些值可能包含的任何基本计算后报告元素的所有CSS属性的值。私有的CSS属性值可以通过对象提供的 API 或通过简单地使用 CSS 属性名称进行索引来访问。是window.getComputedStyle(element)的封装。
用例:
this.$api.dom('#id').computedStyle;
# $page
类型:Object描述: 操作页面的方法对象，包含open,push,close,closeToWin,pageParam方法。
# open(url, options)
描述: 打开window页面, 若window已存在，则会把该window显示到最前面，同时若url有变化或者reload参数为true时，页面会重新加载。api.openWin()方法的封装。参数:url:类型:string是否必须: 是描述: 页面地址，可以为本地文件路径，支持相对路径和绝对路径，以及 widget://、fs:// 等协议路径，也可以为远程地址。 当winOpts.data参数不为空时，url将做为baseUrl，winOpts.data中的html引用的资源文件根路径以该url为基础。
options:类型:object,是否必须: 否描述: 打开页面的参数，包含以下几项
可选项 类型 是否必须 描述 name stringfalse可选项，要打开 window的name, 默认为win_${url},pageParam anyfalse可选项，向要打开 window页面传递的数据，无默认值winOpts objectfalse可选项，要打开页面 window的所有参数，详见官方文档 (opens new window), 内部参数可覆盖外部参数animation objectfalse可选项，页面打开的动画效果， 详见官方文档 (opens new window) animation的内部参数如下:可选项 类型 是否必须 描述 typestringfalse动画类型 subTypestringfalse动画子类型 durationnumberfalse动画过渡时间，默认300毫秒 { type: "none", // 动画类型（详见动画类型常量） subType: "from_right", // 动画子类型（详见动画子类型常量） duration: 300 // 动画过渡时间，默认300毫秒 } type 取值范围： none // 无动画效果 push // 新视图将旧视图推开 movein // 新视图移到旧视图上面 fade // 交叉淡化过渡（不支持过渡方向） flip // 翻转效果 reveal // 将旧视图移开,显示下面的新视图 ripple // 滴水效果（不支持过渡方向） curl // 向上翻一页 un_curl // 向下翻一页 suck // 收缩效果（不支持过渡方向） cube // 立方体翻滚效果 subType 取值范围： from_right // 从右边开始动画 from_left // 从左边开始动画 from_top // 从顶部开始动画 from_bottom // 从底部开始动画 （Android系统flip，ripple，curl，un_curl，suck，cube 类型不支持）
用例:
<script>
export default {
name: 'open-window-page-demo',
methods: {
openDetails() {
this.$page.open('article/details', {
name: 'articleDetailsPage',
pageParam: {
title: '标题',
content: '内容'
}
})
},
openBaidu() {
this.$page.open('https://www.baidu.com', {
animation: {
type: 'fade',
subType: 'from_right',
duration: 300
}
})
}
}
}
</script>
# push(urlOrOptions)
描述: 打开一个新的window页面,open方法的封装参数:urlOrOptions:类型:string | object是否必须: 是描述: 打开页面的参数，如果是string类型，则当作url直接传递给open()方法， 如果是object, 则包含以下几项
可选项 类型 是否必须 描述 name stringfalse要打开 window的name, 这里可以填写src/config/pages.js里面配置的页面的name，可直接打开该页面pageParam anyfalse可选项，向要打开 window页面传递的数据，无默认值winOpts objectfalse可选项，要打开页面 window的所有参数，详见官方文档 (opens new window), 内部参数可覆盖外部参数animation objectfalse可选项，页面打开的动画效果， 详见官方文档 (opens new window), 与 open()方法参数options.animation相同
用例:
<script>
export default {
name: 'open-window-page-demo',
methods: {
gotoLogin() {
this.$page.push({ name: 'login' })
},
openBaidu() {
this.$page.push('https://www.baidu.com')
},
openIndex() {
this.$page.push({
name: 'index',
pageParam: { loginTime: new Date().getTime() }
})
}
}
}
</script>
# close()
描述: 关闭当前window页面，api.closeWin()方法的封装。参数: 无
用例:
<script>
export default {
name: 'close-window-page-demo',
methods: {
close() {
this.$page.close()
},
}
}
</script>
# closeToWin(options)
描述: 关闭到指定 window，最上面显示的 window 到指定 name 的 window 间的所有 window 都会被关闭，api.closeToWin()方法的封装。参数:options:类型:object是否必须：是描述: 关闭到指定 window 的可选项， 包含以下几项
可选项 类型 是否必须 描述 name stringtrue指定 window 的名字 animation objectfalse可选项，页面打开的动画效果， 详见官方文档 (opens new window), 与 open()方法参数options.animation相同
用例:
<script>
export default {
name: 'closeToWin-demo',
methods: {
closeToIndex() {
this.$page.closeToWin({ name: 'root' })
},
}
}
</script>
# pageParam()
描述: 用于获取页面间传递的参数值，为api.openWin()、api.openFrame()、$page.open()、$page.push()、$frame.open()等方法中的pageParam参数对应值，api.pageParam属性的封装。参数: 无返回值:any
用例:
<script>
export default {
name: 'closeToWin-demo',
data () {
return {
article: null
}
},
methods: {
getData() {
this.article = this.$page.pageParam()
},
},
onReady () {
this.getData()
}
}
</script>
# $frame
类型:Object描述: 操作Frame的方法对象，包含open()方法。
# open(options)
描述: 打开 frame, 若 frame 已存在，则会把该窗口显示到最前面并显示，如果 url 和之前的 url 有变化，或者 reload 为 true 时，页面会刷新.此方法对 frameGroup 里面的 frame 不起作用，api.openFrame()方法的封装参数:options:类型:object是否必须: 否描述: 打开frame的参数，详见官方文档 (opens new window)
用例:
<script>
export default {
name: 'open-frame-demo',
methods: {
openHeader(title) {
this.$frame.open({
url: this.$n2p('header'),
name: 'common-header',
rect: {
x: 0,
y: 0,
w: 'auto',
h: 60
},
pageParam: { title }
})
},
},
onReady () {
this.openHeader('Article Title')
}
}
</script>
# $toast(options)
描述: 弹出一个定时自动关闭的提示框,api.toast()方法的封装参数:options:类型:object是否必须:true描述: 可选项，包含以下几项
可选项 类型 是否必须 描述 msg stringtrue提示消息 duration numberfalse（可选项）持续时长，单位：毫秒, 默认值 3000 location stringfalse（可选项）弹出位置，顶部、中间或底部, 默认 bottomlocation的取值范围:top // 顶部 middle // 中间 bottom // 底部
用例:
<script>
export default {
name: 'toast-demo',
onReady () {
this.$toast({ msg: '页面已经打开', location: 'top' })
}
}
</script>
# $pagesInfo
描述: 获取页面配置信息， 以数组的形式返回
用例：
console.log(this.$pagesInfo)
/**
[
{
title: "开屏广告页",
name: "index",
path: "index/index",
htmlPath: "indexindex"
},
{
title: "登录页",
name: "login",
path: "login/index",
htmlPath: "loginindex"
},
{
title: "应用首页",
name: "home",
path: "home/index",
htmlPath: "homeindex"
},
{
title: "web页面",
name: "web",
path: "home/web",
htmlPath: "homeweb"
},
...
]
*/
# $getPageMap()
描述: 获取页面配置信息, 以对象的形式返回，页面的key即配置的页面的name参数: 无返回值:object
用例：
console.log(this.$getPageMap())
/**
{
index: {
title: "开屏广告页",
name: "index",
path: "index/index",
htmlPath: "indexindex"
},
login: {
title: "登录页",
name: "login",
path: "login/index",
htmlPath: "loginindex"
},
home: {
title: "应用首页",
name: "home",
path: "home/index",
htmlPath: "homeindex"
},
web: {
title: "web页面",
name: "web",
path: "home/web",
htmlPath: "homeweb"
},
...
}
*/
# $bindKeyBackExitApp()
描述: 绑定keyback为连续按下 2 次退出应用参数: 无
用例:
<script>
export default {
name: 'bindKeyBackExitApp-demo',
onReady () {
this.$bindKeyBackExitApp()
}
}
</script>
# $n2p(name)
描述: 将页面的name转换为页面的htmlPath参数:name:类型:string是否必须：是描述:src/config/pages.js文件中配置的页面的name
返回值:类型:string描述: 页面的htmlPath
用例:
<script>
export default {
name: 'n2p-demo',
methods: {
gotoLogin() {
this.$page.open(this.$n2p('login'));
}
}
}
</script>
# $getSafeArea()
描述: 页面不被其它内容（如状态栏）遮住的区域，JSON对象，通过safeArea能够知道当前页面哪些地方被遮住，从而做出相应的调整，保证页面重要元素不被遮挡住，比如应对顶部header被状态栏遮住一部分，可以为header增加一个paddingTop, 是api.safeArea属性的封装参数: 无返回值:object
{
top: // 安全区域上边缘，对于沉浸式下window中该值通常为状态栏高度，全屏或非沉浸式下为0（iPhone X竖屏时全屏状态下也为44）
left: // 安全区域左边缘，通常为0（iPhone X横屏时为44）
bottom: // 安全区域下边缘，通常为0（iPhone X竖屏时为34，横屏时为21）
right: // 安全区域右边缘，通常为0（iPhone X横屏时为44）
}
用例:
<script>
export default {
name: 'getSafeArea-demo',
methods: {
fixHeader() {
const { top } = this.$getSafeArea()
this.$api.dom('#header').style.paddingTop = `${top}px`
}
},
onReady() {
this.fixHeader()
}
}
</script>
# $getWinSize()
描述: 获取屏幕尺寸，包括winHeight,winWidth, 是api.winHeight、api.winWidth属性的封装。参数: 无返回值:object
{
winHeight: // 屏幕高度
winWidth: // 屏幕宽度
}
用例:
const { winHeight, winWidth } = this.$getWinSize()
// TODO
# $setPullDownRefresh(callback，options)
描述: 显示默认下拉刷新组件，使用默认下拉刷新组件时会自动重新设置页面的弹动属性。api.setRefreshHeaderInfo()方法的封装。参数:callback:类型：Function是否必须: 是描述: 处于下拉刷新状态的回调
options:object类型：object是否必须: 否描述: 下拉刷新的可选项，包含以下几项
可选项 类型 默认值 描述 visible booleantrue是否可见 bgColor string当 defaultRefreshHeader为pull时为rgba(187, 236, 153, 1.0)，为swipe时为#fff背景颜色 pathColor string#0F9D58进度条的颜色， defaultRefreshHeader为swipe时生效。loadingImg string旋转箭头图片 上拉下拉时的图片地址， defaultRefreshHeader为pull时生效。textColor stringrgba(109, 128, 153, 1.0)defaultRefreshHeader为pull时生效。textDown string下拉可以刷新...下拉文字描述， defaultRefreshHeader为pull时生效。textUp string松开可以刷新...松开时文字描述， defaultRefreshHeader为pull时生效。textLoading string默认值： 加载中...加载状态文字描述， defaultRefreshHeader为pull时生效。textTime string最后更新加日期时间更新时间文字描述， defaultRefreshHeader为pull时生效。showTime booleantrue是否显示更新时间， defaultRefreshHeader为pull时生效。
用例:
<script>
export default {
name: 'setPullDownRefresh-demo',
data () {
return {
data: {}
}
},
methods: {
initData () {
this.$req.get('/url').then(rs => {
this.data = rs.data
this.api.refreshHeaderLoadDone();
})
}
},
onReady() {
this.$setPullDownRefresh(() => {
// TODO
// 在这里从服务器加载数据，
// 加载完成后调用 this.api.refreshHeaderLoadDone() 方法恢复组件到默认状态
this.initData();
})
}
}
</script>
# $randomColor(options)
描述: 生成随机颜色， 默认以 16 进制返回，可配置为rgb或rgba类型返回返回值:string参数:options:类型:object是否必须：否描述: 配置返回类型和透明度，包含以下几项
可选项 类型 默认值 描述 rgb booleanfalse是否以 rgb形式返回opacity number | 'random'1 透明度, 以 rgba形式返回
用例:
this.$randomColor()
// #ffffff
this.$randomColor({ rgb: true })
// rgb(255,255,255)
this.$randomColor({ rgb: true, opacity: 0.5 })
// rgba(255,255,255, 0.5)
this.$randomColor({ rgb: true, opacity: 'random' })
// rgba(255,255,255, 0.123)
# $isLightColor(color)
描述: 判断颜色是否为浅色，默认返回 true参数:string, 支持 16 进制类型 和rgb[a]类型的颜色表示，颜色阀值参考自 jscolor (opens new window)返回值:boolean
用例:
this.$isLightColor()
// true
this.$isLightColor('transparent')
// true
this.$isLightColor('#fff')
// true
this.$isLightColor('#000')
// false
this.$isLightColor('#ffffff')
// true
this.$isLightColor('#000000')
// false
this.$isLightColor('rgb(255,255,255)')
// true
this.$isLightColor('rgb(0,0,0)')
// false
this.$isLightColor('rgba(255,255,255, 0.8)')
// true
this.$isLightColor('rgba(0,0,0, 0.8)')
// false
# $setStatusBarStyle(optionsOrColor)
描述: 设置状态栏背景颜色和字体颜色, 是api.setStatusBarStyle方法的封装。返回值: 无参数:optionsOrColor:类型:object|string是否必须：是描述: 如果参数类型为string, 则为状态栏的背景颜色，字体颜色默认为黑色，若为object，则为配置状态栏样式的选项，包含以下几项
可选项 类型 默认值 描述 color string#000 状态栏背景颜色，只 Android 5.0 及以上有效 style 'light' | 'dark'light状态栏字体颜色，支持iOS，Android 支持小米 MIUI6.0 及以上手机，魅族 Flyme4.0 及以上手机，其他 Android6.0 及以上手机。Android 因设备厂商定制差异，频繁切换 style 不一定生效。若不设置，则自动通过 $isLightColor判断所传背景颜色是否是浅色，浅色则为dark, 否则为lightanimated booleanfalse是否有动画效果，只iOS有效 style的取值范围
dark // 状态栏字体为黑色，适用于浅色背景 light // 状态栏字体为白色，适用于深色背景
用例:
// 设置状态栏为透明背景 字体颜色为 `dark`
this.$setStatusBarStyle('transparent')
// 设置状态栏为具体颜色 字体颜色通过 `isLightColor` 判断
this.$setStatusBarStyle('#007ACC')
// 设置状态栏为透明背景 字体颜色为 `light`
this.$setStatusBarStyle({
color: 'transparent',
style: 'light'
})
// 设置状态栏为具体颜色 字体颜色为 `light`， 并有动画效果
this.$setStatusBarStyle({
color: '#007ACC',
style: 'light',
animated: true
})
← 网络请求