chanjet-navigator

简介

NavigationController 是一个基于栈的页面导航控制管理器，用于管理应用内各种场景页面的切换及应用页面状态恢复，主要包含以下功能：

• 应用页面场景的流转

  主要用于页面向前跳转和页面回退的处理。其核心是将页面保存到栈中进行管理，每次渲染只显示栈顶的页面，每跳转到一个新页面，就把这个页面的信息压入栈中，如果要回退到前一个页面，则进行出栈操作，回退到之前的页面去。

• 将工作圈的 Navigation Bar 上产生的点击事件通知到应用当前场景页面

• 页面场景恢复

  主要是针对当前页面被重载时进行的处理。重载发生有以下两种可能，针对这两种场景，解决如何让应用回到之前的状态，包括页面的层级深度，每个页面使用的参数

  • 刷新

  • Android系统中当前页面被杀掉后，重新进入时的场景还原

安装

使用 NavigationController 需要先安装 chanjet-navigator 的 npm 包：

npm install chanjet-navigator

或者安装 chanjet-ui 的 npm 包，chanjet-ui 已经包含 chanjet-navigator，不需要重复安装。

npm install chanjet-ui

项目中引用

如果安装的是 chanjet-navigator 的 npm 包：

import {NavigationController} from 'chanjet-navigator';

如果安装的是 chanjet-ui 的 npm 包：

import NavigationController from 'chanjet-ui/lib/navigation/NavigationController';

使用

通过简单配置，我们就可以很方便的使用起来了：

import React from 'react';
import ReactDOM from 'react-dom';

import {NavigationController} from 'chanjet-navigator';
import PageIndex from './pages/pageIndex';
import PageList from './pages/pageList';
import PageDetail from './pages/pageDetail';

const pages = {
  '/index':PageIndex,
  '/list':PageList,
  '/detail':PageDetail
}

class App extends React.Component {
  render() {
    return (<NavigationController
            	pages = {pages}
            	rootPage = {'/index'}
            	rootParams = {{data:'test'}}
           />);
  }
}
            
ReactDOM.render(<App />, document.getElementById('app'));

使用参数:

| 参数名 | 类型 | 说明 | | ---------- | ------ | --------------- | | pages | Object | 包含所有页面的索引的map对象 | | rootPage | String | 标识起始页要使用的Page | | rootParams | JSON-Object | 起始页Page需要用到的参数 |

页面流转操作的API

页面流转使用 NavigationController 的 API 方法进行操作，NavigationController 本身会作为 Page 的 props 参数传递到 Page 上，由每个 Page 根据自己的业务发起需要的操作，具体 API 方法如下：

• push

  进入新的页面

  使用代码

  //API
  push(pageKey, pageParams, pageCode);
  
  //在page中具体使用
  this.props.navigationController.push('/list');
  this.props.navigationController.push('/list', {params:'test'});
  this.props.navigationController.push('/list', null, 'page0');

  NavigationController 根据 Pages 进行查找对应的 Page 页面，找到后将页面压栈，此时应用切换到新页面，将之前的其他页面进行隐藏。

• pop

  返回上一个页面

  使用代码

  //API
  pop();
  
  //在page中具体使用
  this.props.navigationController.pop();

  当前页面出栈并被销毁，返回到前一个页面，如果当前页面是唯一页面，则不能再进行 pop 操作。

• popTo

  往前查找符合条件的最后一个页面，并返回到该页面

  使用代码

  //API
  popTo(pageKey);
  
  //在page中具体使用
  this.props.navigationController.popTo('/index');

  NavigationController 根据 pageKey 在当前所有页面中查找符合该 pageKey 的最后一个页面，如果找到了就返回到该页面，当前页(包括当前页)到该页面中间所有的页面都出栈，都会被销毁。

  * 如果没有找到，则不进行页面跳转，保持不变。

• popToRoot

  回到应用页面栈的第一个页面

  使用代码

  //API
  popToRoot();
  
  //在page中具体使用
  this.props.navigationController.popToRoot();

  NavigationController 将当前栈中除第一个页面外的所有页面都出栈并销毁。

• popAndReturn

  页面出栈并附带返回结果

  使用代码

• replace

  替换当前页面

  使用代码

  //API
  replace(pageKey, pageParams);
  
  //在page中具体使用
  this.props.navigationController.replace('/detail');
  this.props.navigationController.replace('/detail', {params:'test'});

  replace 即替换当前栈顶页面，同时移除原来的栈顶页面，replace 不限制页面在栈中的位置。

• forkTo

  从当前栈的根节点分出新的分支栈

  使用代码

  //API
  forkTo(pageKey, pageParams);
  
  //在page中具体使用
  this.props.navigationController.forkTo('/detail');
  this.props.navigationController.forkTo('/detail'', {params:'test'});

  NavigationController 首先将根页面以外的全部页面进行出栈移除，然后将要 forkTo 的页面压入栈内，完成从根页面重新进入到另一个分支页面栈，该功能可要应用于从当前功能场景快速回到应用首页，然后切换到另一种功能场景。

  * 如果要 forkTo 的页面是当前栈的根页面，则回到根页面，而不会在根页面的基础上再加入一个相同的页面，类似于执行了 popToRoot 的操作。