1.3.6.1 QN.navigator

优质

小牛编辑

147浏览

2023-12-01

1.1. API 调用

1.1.1. QN.navigator.push(options)

1.1.2. QN.navigator.go(options)

打开/跳转页面

API 调用入参

参数名	类型	是否可选	默认值	含义
`options`	`Object`			选项
`options.url`	`String`			需要跳转的URL
`options.title`	`Object`	`optional`		新页面的 `title`
`options.query`	`Object`	`optional`		跳转到 URL 时要传递的 `query` 参数
`options.settings`	`Object`	`optional`		设置项
`options.settings.animate`	`Boolean`	`optional`	`false`	切换时是否启用动画效果
`options.settings.clearTop`	`Boolean`	`optional`	`false`	新开页面后，是否关闭除了新页面之外的所有其他页面
`options.settings.resolveURL`	`Boolean`	`optional`	`true`	在 H5 页面中 push 新页面的时候，是否自动解析 URL
`options.success`	`Function`	`optional`		调用成功的回调函数
`options.error`	`Function`	`optional`		调用失败的回调函数

options.settings.resolveURL
- 当在 H5 页面中 push 新页面时，如果 push 的是 qap:// 协议的页面，会自动根据 qap.json 中的 WebRootPath 字段将 url 解析成 http:// 对应的页面。如果你不希望进行自动解析，可以将 resolveURL 的值设置为 false。

API 响应结果

参数名	类型	是否必须返回	含义
`result`	`Object`		响应对象
`result.code`	`String`		错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`		错误信息
`result.data`	`Object`	`optional`	新页面返回的数据（如果是请求下一个页面的时候）

调用示例

QN.navigator.push({
    url: 'http://www.taobao.com',
    title: '新开页面标题~~',
    query: { x: 1, y: 2 },
    settings: {
        animate: true,
        request: true,
    }
}).then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.push({
    url: 'http://www.taobao.com',
    title: '新开页面标题~~',
    query: { x: 1, y: 2 },
    settings: {
        animate: true,
        request: true,
    },
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.3. QN.navigator.pop(options)

1.1.4. QN.navigator.back(options)

关闭页面/后退

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.query`	`Object`	`optional`	接口调用参数
`options.query.data`	`Object`	`optional`	需要返回给前一个页面的数据
`options.settings`	`Object`	`optional`	设置项
`options.settings.animate`	`Boolean`	`optional`	切换时是否启用动画效果
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.pop({
    query: {
        data: {}
    },
    settings: {
        animate: true,
    }
}).then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.pop({
    query: {
        data: {}
    },
    settings: {
        animate: true,
    },
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.5. QN.navigator.reload(options);

刷新当前页面

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`	`optional`	选项
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.reload();

QN.navigator.reload()
.then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.reload({
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.6. QN.navigator.close(options);

关闭插件应用

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`	`optional`	选项
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.close();

QN.navigator.close()
.then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.close({
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.7. QN.navigator.setTitle(options)

设置标题

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.query`	`Object`		接口调用参数
`options.query.title`	`String`		标题文案
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

// 文字标题
QN.navigator.setTitle({
    query: {
        title: '我是标题'
    }
}).then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.setTitle({
    query: {
        title: '我是标题'
    },
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

{ console.log(result); }, error => { console.log(error); }); -->

1.1.8. QN.navigator.showTitle(options)

显示标题

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.showTitle()
.then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.showTitle({
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.9. QN.navigator.hideTitle(options)

隐藏标题

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.hideTitle()
.then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.hideTitle({
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

{ console.log(result); }, error => { console.log(error); }); QN.navigator.setBackground({ query: { color: '#F5FCFF' }, success(result) { console.log(result); }, error(error) { console.log(error); } }); ``` -->

1.1.10. QN.navigator.addButton(options)

添加导航栏自定义按钮

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.query`	`Object`		接口调用参数
`options.query.iconName`	`String`	`optional`	千牛客户端内置 icon 名称，内置 icon 列表参看本页附录
`options.query.iconImg`	`String`	`optional`	图标图片，`URL` 或 `Base64`（暂不支持 URL）
`options.query.text`	`String`	`optional`	图标文本，如果 `iconName` 和 `iconImg` 都没有值，则展示文本
`options.query.tapEvent`	`String`		按钮点击时触发的事件，该事件为 `Page` 级别事件，可以使用 `QN.on` 进行监听，注意 `tapEvent` 不要与其他事件重复
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

iconImg 示例：

类型	示例	备注
URL	`http://www.icon.com/share.png`
URL	`https://www.icon.com/share.png`
Base64	`iVBORw0KGgoAAAANSUhEUgAAAgAAAA...`

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.addButton({
    query: {
        iconName: 'share',
        text: '分享',
        tapEvent: 'Page.share', // 或 `share`
    }
}).then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.addButton({
    query: {
        iconName: 'share',
        text: '分享',
        tapEvent: 'Page.share', // 或 `share`
    },
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.11. QN.navigator.removeButton(options)

移除导航栏自定义按钮

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.query`	`Object`		接口调用参数
`options.query.tapEvent`	`String`		需要移除的按钮对应的事件（由于按钮事件事件是唯一的，因此也作为移除按钮的标识）
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.removeButton({
    query: {
        tapEvent: 'Page.share', // 或 `share`
    }
}).then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.removeButton({
    query: {
        tapEvent: 'Page.share', // 或 `share`
    },
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.12. QN.navigator.clearButtons(options)

清除导航栏自定义按钮

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.clearButtons();

QN.navigator.clearButtons()
.then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.clearButtons({
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.13. QN.navigator.addMenuItem(options)

添加导航栏菜单列表中自定义菜单项

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.query`	`Object`		接口调用参数
`options.query.iconName`	`String`		千牛客户端内置 icon 名称，内置 icon 列表参看本页附录
`options.query.iconImg`	`String`		图标图片，`URL` 或 `Base64`（暂不支持 URL）
`options.query.text`	`String`	`optional`	图标文本，如果 `iconName` 和 `iconImg` 都没有值，则展示文本
`options.query.tapEvent`	`String`		按钮点击时触发的事件，该事件为 `Page` 级别事件，可以使用 `QN.on` 进行监听，注意 `tapEvent` 不要与其他事件重复
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

iconImg 示例：

类型	示例	备注
URL	`http://www.icon.com/share.png`
URL	`https://www.icon.com/share.png`
Base64	`iVBORw0KGgoAAAANSUhEUgAAAgAAAA...`

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.addMenuItem({
    query: {
        iconName: 'share',
        text: '分享',
        tapEvent: 'Page.share', // 或 `share`
    }
}).then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.addMenuItem({
    query: {
        iconName: 'share',
        text: '分享',
        tapEvent: 'Page.share', // 或 `share`
    },
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.14. QN.navigator.removeMenuItem(options)

移除导航栏菜单列表中自定义菜单项

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.query`	`Object`		接口调用参数
`options.query.tapEvent`	`String`		需要移除的按钮对应的事件（由于按钮事件事件是唯一的，因此也作为移除按钮的标识）
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.removeMenuItem({
    query: {
        tapEvent: 'Page.share', // 或 `share`
    }
}).then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.removeMenuItem({
    query: {
        tapEvent: 'Page.share', // 或 `share`
    },
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.15. QN.navigator.clearMenuItems(options)

清除导航栏菜单列表中自定义菜单项

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

QN.navigator.clearMenuItems();

QN.navigator.clearMenuItems()
.then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.clearMenuItems({
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.1.16. QN.navigator.setSwipeBack(options)

启用/禁用iOS下页面的左滑返回，页面加载时默认为启用。

API 调用入参

参数名	类型	是否可选	含义
`options`	`Object`		选项
`options.query`	`Object`	`optional`	接口调用参数
`options.query.enable`	`Boolean`	`optional`	是否启用左滑返回
`options.success`	`Function`	`optional`	调用成功的回调函数
`options.error`	`Function`	`optional`	调用失败的回调函数

API 响应结果

参数名	类型	含义
`result`	`Object`	响应对象
`result.code`	`String`	错误码，成功为 `QAP_SUCCESS`；失败为其他
`result.msg`	`String`	错误信息

调用示例

// 禁止左滑返回
QN.navigator.setSwipeBack({
    query: {enable: false}
}).then(result => {
    console.log(result);
}, error => {
    console.log(error);
});

QN.navigator.setSwipeBack({
    query: {enable: false},
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    }
});

1.2. 导航栏内置事件

事件名称	含义	备注
Page.back	返回按钮点击事件
Page.close	关闭按钮点击事件
Page.reload	刷新按钮点击事件

当用户操作时，预置事件由千牛客户端触发，你可以监听这些事件并拦截这些按钮的默认行为：

QN.on('Page.back', function(data) {
    // 进行一些处理
    doSomeStuff();
    // 监听事件后，默认行为被拦截，因此要手动调用返回
    QN.navigator.pop();
});

1.3. 附录

1.3.1. 内置 icon 列表

icon 名称	含义	样式
`38`	38节
`1212`	双12
`activity`	活动
`add`	加号
`addressbook`	地址簿
`album`	专辑
`appreciate`	赞
`apps`	应用
`attention`	注意
`baby`	婴儿
`back`	返回
`bad`	差评
`barcode`	条码
`big`	big
`brand`	品牌
`camera`	拍照
`cameraadd`	拍照
`camerarotate`	拍照旋转
`cart`	购物车
`cascades`	瀑布流
`check`	打勾
`choiceness`	精选
`close`	关闭
`clothes`	衣服
`comment`	评论信息
`copy`	复制
`countdown`	时钟倒计时
`creative`	灵感
`delete`	删除
`deliver`	邮递快速
`discover`	发现
`down`	向下
`edit`	编辑
`emoji`	Emoji 表情
`evaluate`	评价
`explore`	探索探测
`favor`	收藏
`female`	女性
`file`	文件
`filter`	过滤
`flashlightclose`	关闭闪光灯
`flashlightopen`	打开闪光灯
`focus`	聚焦
`fold`	折叠
`footprint`	足迹
`form`	表单
`forward`	前进
`friend`	好友
`friendadd`	添加好友
`friendfamous`	星标好友
`friendfavor`	收藏好友
`game`	游戏
`goods`	商品货物
`home`	家主页
`hot`	火热
`info`	信息
`keyboard`	键盘
`light`	闪光
`lightauto`	自动闪光
`lightforbid`	禁止闪光
`like`	喜欢
`link`	链接
`list`	列表
`loading`	加载中
`location`	定位
`lock`	锁定
`male`	男性
`mark`	备注
`message`	消息
`mobile`	手机
`mobiletao`	手机淘宝
`more`	更多
`moreandroid`	更多
`my`	我的
`new`	新的
`notice`	通知
`notification`	通知
`notificationforbidfill`	禁止通知
`order`	排序
`paint`	绘制
`pay`	支付
`people`	人员
`phone`	电话
`pic`	图片
`present`	礼物
`profile`	个人信息
`pulldown`	下
`pullleft`	左
`pullright`	右
`pullup`	上
`qiang`	抢
`qrcode`	二维码
`question`	问题
`rank`	排序
`recharge`	充值
`redpacket`	红包
`refresh`	刷新
`refresharrow`	下
`refund`	退款
`remind`	提醒
`repair`	修复修理
`repeal`	撤销
`right`	右
`round`	圆
`roundadd`	添加
`roundcheck`	打勾
`roundclose`	关闭
`roundright`	右
`same`	相同
`scan`	扫码
`search`	搜索
`searchlist`	搜索列表
`selection`	精选
`send`	发送
`service`	客服服务
`settings`	设置
`share`	分享
`shop`	店铺
`similar`	相似
`sort`	分类
`square`	复选框方框
`squarecheck`	选中复选框
`tag`	标签
`tao`	淘宝
`taxi`	出租 Taxi
`ticket`	门票
`time`	时间时钟
`tmall`	天猫
`top`	返回顶部
`unfold`	下展开
`unlock`	解锁
`upstage`	奖杯
`vip`	VIP
`vipcard`	VIP卡
`voice`	语音
`wang`	旺旺
`warn`	警告
`we`	微信
`wefill`	微信
`weibo`	微博
`wifi`	网络 WIFI