APIbeta

NavbarView

Introduce

1
2
import bpui from 'bpui.js';
bpui.navbarView

navbarView 组件用于对app页面进行导航功能, 可以设置页面堆栈的大小, 以便存储浏览过的页面;

navbarView是一个单例对象, 全局只能有一个navbarView. 可以使用api进行控制, 而无需使用 ref.

navbarView提供了插件, 注入了变量 $navbar 可以用来调用导航组件方法.

history导航模式

为记录路由导航, 在history状态中使用参数 `_` 表示当前的导航标记. 如果项目需要使用名称为_的history状态, 可以设置属性`seqName` 指定另外一个名称.

内部使用`history`模式路由导航, 支持IE10及以上浏览器

使用时会覆盖vue-router的相关方法, 项目不能安装vue-router, 否则无法启动;

可以使用vue-router的一些方法, 如: `$router`, `$route`, `router-link`;

路由改变监控 IRouter.on(‘routeChanged’)

可以使用基础库中的路由方法来监控路由变化

可使用全局方法设置配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/**
 * set navbarview default config.
 */
bp.setNavbarDefaultCfg(cfg: {
  /**
   * default retain page dom in `push` method.
   */
  retainPageInPush?: boolean,
  /**
   * It will refresh page when change routes between different layouts.
   */
  allLayouts?: string[],
}): void;

props

名称 类型 是否必须 描述
cacheSize number 最大的页面层级, 将保留的page dom个数. (默认为无限制, 初次设置之后修改无效)
rootRoutePath string 初始页面的路径 (如果不指定, 则默认为 /; (初次设置之后修改无效) )
rootRouteParams Object 初始页面的参数 (初次设置之后修改无效)
pageClass string 或 array 导航视图页面的样式类名或类名数组
pageBgColor string 页面背景颜色
pageAnimation string 默认转场动画的类名; 内部提供的有:
-slide 左右切换
-fade 渐变
-lift 上下
-‘’ 无动画(默认)
appMode boolean 表明是否为app模式, app模式路由的最上层为rootRoutePath; 否则为浏览器正常history; (默认为false, 初次设置之后修改无效)
scrollToAnchorBehavior ‘instant’ 或 ‘smooth’ 使用 router-link 或 方法跳转到如 to=’#xxx’ 的anchor时的页面滚动行为. 默认为 smooth.

导航条相关属性

名称 类型 是否必须 描述
containStatusBar boolean 是否包含状态栏. (ios webapp模式为true, 其他默认为false).
barTextColor string 导航条左右按钮文本颜色
barTitleColor string 导航条标题文本颜色
barBgColor string 导航条背景色
barHidden boolean (微信浏览器中忽略这个值; 其他默认为false) 导航栏隐藏状态
backIconComponent Component 定义返回按钮的图标;

加载组件属性

名称 类型 是否必须 描述
errorComponent Component 加载错误时显示的组件;
loadingComponent Component 加载页面时显示的组件;
loadingDelay number 延迟显示加载页面; 默认为200
loadingTimeout number 加载组件的超时时间; 默认为 Infinity

特别属性

名称 类型 是否必须 描述
seqName string 为记录路由而使用的地址查询参数名.(只能指定一次,动态修改无效)

指定container样式.

需要对页面最外层container指定样式时, 可以使用下列方式

1
<navbarView pageClass="containerClass"></navbarView>

可以通过pageClass属性传递容器类名类名数组设置最外层样式.

events

名称 描述
hiddenChanged(event):void 导航条隐藏改变事件.

除事件外, 页面组件还可以定义如下的方法, 导航组件将在适当时触发.

名称 描述
viewAppear(popData:any):void 页面显示, popData为页面pop传递回来的数据. (对navbar的信息设置请写在此方法内).
viewDisappear():void 页面即将消失.
viewClickLeftItem():boolean 点击左侧按钮触发; 如果明确返回false, 则不进行默认回退处理.
viewClickRightItem():void 点击右侧按钮触发.

在viewWillAppear方法中调用navbar相关方法设置navbar时, 设置的状态只会作用于当前的页面; 而所有导航页面的默认状态由navbarView组件创建时的属性和样式决定

页面滚动

1
2
3
4
5
// 页面平滑滚动用:
window.scrollTo({ top: 0, left: 0, behavior: "smooth" })

// 页面瞬间滚动用:
window.scrollTo({ top: 0, left: 0, behavior: "instant" })

内置动画类型

1
type AnimateType = 'slide'|'slideOut'|'fade'|'fadeOut'|'lift'|'liftOut'|'none'|string,
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
/**
 * slide 带50%偏移
 */
.slide-enter {
  transform: translateX(100vw);
}
.slide-enter-active {
  transition: transform 0.3s;
  z-index: 99999;
}
.slide-enter-to {
  transform: translateX(0vw);
}
.slide-leave {
  transform: translateX(0vw);
}
.slide-leave-active {
  transition: transform 0.3s;
}
.slide-leave-to {
  transform: translateX(-50vw);
}

/**
 * slideOut 带50%偏移
 */
.slideOut-enter {
  transform: translateX(-50vw);
}
.slideOut-enter-active {
  transition: transform 0.3s;
}
.slideOut-enter-to {
  transform: translateX(0vw);
}
.slideOut-leave {
  transform: translateX(0vw);
}
.slideOut-leave-active {
  transition: transform 0.3s;
  z-index: 99999;
}
.slideOut-leave-to {
  transform: translateX(100vw);
}

methods

setBarHiddenForce

1
2
3
4
/**
  * @desc: 设置可见度 (常规的setBarInfo方法中的hidden对微信无法起作用).
  */
setBarHiddenForce(isHidden:boolean): NavbarView;

setBarInfo

1
2
3
4
5
6
7
8
9
10
11
12
/**
  * @desc: 设置导航条信息.
  */
setBarInfo(cfg:{
  title?: string,
  /** 标题的文本颜色 */
  titleColor?: string,
  /** 背景色 */
  bgColor?: string,
  /** 是否隐藏(对微信h5无效) */
  hidden?: boolean,
}): NavbarView;

getBarInfo

1
2
3
4
5
6
7
8
9
10
11
12
/**
  * @desc: 获取导航条基础信息.
  */
getBarInfo(): {
  title?: string,
  /** 标题的文本颜色 */
  titleColor?: string,
  /** 背景色 */
  bgColor?: string,
  /** 是否隐藏 */
  hidden?: boolean,
};

setBarLeftItem

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/**
  * @desc: 设置bar左侧.
  * @param icon: 可以为 Dom, string, vue-obj, vue-component. 
  *              - ''  : 不显示图标;
  *              - null: 根据auto来自动判断是否显示返回图标.
  */
setBarLeftItem(cfg:{
  text?: string,
  /**
    * 可以为 Dom, string, vue-obj, vue-component. 
    *  - ''  : 不显示图标;
    *  - null: 根据auto来自动判断是否显示返回图标.
    */
  icon?: any,
  textColor?: string,
}): NavbarView;

setBarRightItem

1
2
3
4
5
6
7
8
9
10
11
12
13
/**
  * @desc: 设置bar右侧.
  */
setBarRightItem(cfg:{
  text?: string,
  /**
    * 可以为 Dom, string, vue-obj, vue-component. 
    *  - ''  : 不显示图标;
    *  - null: 根据auto来自动判断是否显示返回图标.
    */
  icon?: any,
  textColor?: string,
}): NavbarView;

push

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/**
  * @desc: push a page.
  * @param animate: 所有允许的动画, 例如: slide, fade, lift
  *                 ''   - 无动画.
  *                 null - 默认动画
  * @param query: url查询参数
  * @param data: 下一个页面viewAppear 中附带的参数
  * @param retainPage: 表示是否保留当前的页面组件; 为false时将销毁当前页面的dom.
  */
push(cfg:{
  path: string,
  query?: { [key: string]: any },
  animate?:AnimateType,
  data?: any,
}, retainPage?: boolean = false):void;
push(path:string, retainPage?: boolean = false):void;

可以使用 bpui.setNavbarDefaultCfg(..) 接口设置默认的retainPage行为.

除使用方法进行导航外, 还可以使用 router-link 组件;

系统对 router-link进行了重写; 总体兼容, 但做了一些修改:

例如

1
2
3
<router-link to="/page1" animate="slide" data="附带的数据">跳转</router-link>
<router-link :back="true" data="附带的数据">回退</router-link>
<router-link to="/page1" :replace="true" data="附带的数据">替换本页面</router-link>

pop

回退操作可以指定一个 data 数据, 回退时, 前一个页面的 viewAppear 方法将传递这个数据.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/**
  * @desc: pop a page.
  * @param data: 下一个页面viewAppear 中附带的参数
  */
pop(cfg?:{animate?:AnimateType, data?:any}):void;

/**
  * @desc: pop to top-page.
  * @param data: 下一个页面viewAppear 中附带的参数
  */
popToTop(cfg?:{animate?:AnimateType, data?:any}):void;

/**
  * @desc: pop to to route page.
  * @param n: 负值表示退后的步数.
  * @param cfg.data: 下一个页面viewAppear 中附带的参数
  */
popTo(n:number, cfg?:{animate?:AnimateType, data?:any}):void;

replace

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/**
  * @desc: replace current route.
  *        root页面不可被replace; 如果当前是root页面, 则等同于push.
  * @param animate: 所有允许的动画, 例如: slide, fade, lift
  *                 ''   - 无动画.
  *                 null - 默认动画
  * @param query: url查询参数
  * @param data: 下一个页面viewAppear 中附带的参数
  */
replace(cfg:{
  path: string,
  query?: { [key: string]: string },
  animate?:AnimateType,
  data?: any,
}):void;
replace(path:string):void;

自定义navbar

提供名为navbar的组件实现自定义navbar

1
2
3
<navbar>
  自定义内容
</navbar>

自定义navbar可以放置在任意位置, 但只有最后一个navbar会生效;

使用自定义的navbar后, 依然可以使用 setBarInfo({hidden:true}) api进行bar的显示控制.

双向绑定问题

使用自定义navbar时, 自定义内容必须如果未包含在一个元素内时将无法响应内容改变, 如:

1
2
3
<navbar>
  {{str}}
</navbar>

str变化时, 界面无法响应改变;

需要将内容,至少包裹在一个元素内以能够双向绑定,如:

1
2
3
<navbar>
  <div>{{str}}</div>
</navbar>

自定义主题

图标

组件中使用到的图标名称都是以 bp-navbar_ 开头, 使用到的图标有:

图标名称 描述
bp-navbar_arrowLeft 返回按钮
bp-navbar_loading 默认加载组件中的加载图标

可以使用bpui.icons.registerSvgIcon('bp-navbar_arrowLeft', <svg file>)方式, 进行组件图标自定义

样式结构

组件的样式结构如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
.bp-navbarView {
  /* 导航条 */
  .bp-navbarView_bar {
    .bp-navbarView_leftItem {} 
    .bp-navbarView_centerItem {}
    .bp-navbarView_rightItem {}
  }
  /* 页面 */
  .bp-navbarView_page {
    /* 页面内容页 */
    &>div {}
  }
}

scss样式文件存放在@bpui/navbar-view/style 目录下, 可以复制修改以定制主题