iportal/README.md

web-portal

# Introduce
web-portals， 一个页面间管理框架。

寄语：iportal 虽然能加速页面无缝跳转，同时也提供了良好的性能与内存管理方案，但是依然需要我们对独立的页面性能进行保障，在此我建议使用 web-component 来封装你的组件，因为它有着更好的表现。

# Install：
```bash
$ npm i iportal --save
```

# Start:
```ts
import { application } from 'iportal'

// 配置模块
application.setting({
  modules: {
    frameworks: {...},
    home: () => {
      return new Promise(async (resolve, reject) => {
        import('../home').then(resolve).catch(reject)
      })
    }
  }
})

// 启动 app
application.start()
```


---

## API:

### setting
接受一个配置对象 { modules: {...} }, modules 中为模块的配置对象，同时接受一个 Promise，可以按需异步加载模块配置；当模块在被需要时会提前进行预载入。模块配置主要包含 config 和 resources 和 events，分别是基础配置、预载资源配置、事件处理。在下面的配置介绍中会详细介绍。

---
### start
启动应用，当配置完毕后即可执行该命令，程序将开始立刻进行渲染。

---
### install
当你希望你的 Application 在离线时依然保持可访问性或需要一个更快的访问速度，则可以选择将应用安装到本地，该命令接受两个参数：
* options: { swPathUrl?: string, scope?: string, source?: Array<string>}
1. swPathUrl: serverworker 脚本地址, 此为自定义安装逻辑，如果包含此项其他两项则不会生效
2. scope: 缓存资源路径
3. source: 需要安装的资源文件列表
* version：安装版本号，需要保持唯一。

其返回值为 Promise<ServiceWorkerRegistration>。

---
## Module.resouce：
根据资源类型配置资源 url 数组，在预载入时会根据该配置做预载。
```ts
 interface ModuleResources {
  script?: Array<string>
  image?: Array<string>
  worker?: Array<string>
  video?: Array<string>
  audio?: Array<string>
  font?: Array<string>
  style?: Array<string>
}
```
注意：html 中的 script、css 标签等非脚本异步加载的资源则无需单独配置，此处仅用于脚本执行后的依赖资源，比如 css 中的 font 字体，某场景的主题素材等。

## Module.config：
---
### 类型声明
** [rel?: 'module' | 'frameworks' | 'system'] **
> iportal 在设计之处就考虑做一个系统级的框架，在 iportal 中的模块共分为三种类型，普通模块类型：“module”、框架类型：“framework”、系统类型：“system”；它们的主要区别是所在的容器层级是不一样的

1. “system” 类型的模块是放置在 Main Tree 下的，切不随着任何的模块路由而改变的，比如 app 中的辅助浮标、日期/信号头部栏、系统下拉通知等等。比如下面视频中的 AssistiveTouch 功能就是一个“system” 类型的模块的功能。
2. “framework” 类型则一般是具有框架模式的模块，比如淘宝首页中包含底部导航栏的部分，该导航栏是多个页面所共有的，所以它可以是一个框架层的模块，框架层的模块相对系统层的模块的区别是有着更低层的级别，比如窗口切换的时候框架层可以随之切换，而系统层则不会随之切换。
3. “module” 类型则是最常见的类型，我们可以理解为一个纯粹的页面，同时模块类型还分为自由类型和嵌入类型，后面的 [free] 配置中会讲到。

---

### 标题
** [title: string] **
模块的标题，会在页面切换时修改文档标题

---

### 文档资源
** [source?: { src?: string, html?: string }] **
_src 和 html 二选一_
1. src：页面的 url 链接。当配置的 src 不同域时，一些额外特性无法工作，如后面将讲到的：自动媒体卫士、能力注入、窗口拦截等。
2. html：页面的源文件，此时需要注意页面中没有 “localtion.href” 的跳转形式，因为这样不能被捕捉，而导致窗口失效；可参考后面 [apply] 的配置。

---

### 元素渲染
** [render?: (target: HTMLElement) => void] **
除了 source 模式外还可以通过 render 方法来渲染元素到对应的节点上，可供系统模块和框架模块使用，不推荐普通模块使用该方法渲染。

---

### 超时
** [timeout?: number] **
页面生命周期的倒计时，页面符合缓存条件或设置背景运行时，页面在退出并二次进入前会检查过期情况，当检测到过期时会进行模块的更新操作。

---

### “全屏”模块
**  [free?: boolean] **
该设置下模块以“全屏模式”运行，即不受框架模块约束，比如框架模块中带有 tab 能力时，设置 free 为 true 时，模块将覆盖框架层运行，反之模块则会在框架层之间运行。

---

### 后台运行
**  [background?: boolean] **
_该配置决定了模块做切换时是否会被立即销毁_

* false：模块切换动画结束后会被立即销毁。
* true：模块不会被销毁（仅当页面 load 成功时）；例外情况是当 timeout 超时时，在启动前会被销毁。
* “auto”：当设置成自动时模块会进行智能的判断是否销毁，当触发以下几种情况时则会被销毁：
    ⅰ. 页面设置了 src，且不同源时；
    ⅱ. 页面中包含了 object、embed、applet、iframe 对象时；
    ⅲ. 页面中包含了 video、audio 标签时，且开启智能媒体管理时自动暂停播放出错时；
    ⅳ. 页面中存在节点变动操作在 3 秒钟内超过 10 次时；
    ⅴ. 页面中总的节点操作在后台运行超过 1000 次时；

---

### 单向流模式
** [singleFlow: boolean] **
frameworks 模块专有，只允许页面的历史记录往 level 较小的模块回退，当前一个历史模块的 level 层级大于等于时则进行跳过；例如从生成订单模块的到支付模块再到我的订单模块，完成后进行回退时可选择直接回到订单生成前页面，而无需经过订单过程中的模块页面。

---

### 退出锁
** [singleLock: boolean] **
frameworks 模块专有，当页面回退到程序出口（level === 0 的模块）时，进行返回操作时不会回退，而是会记录回退次数，并 trigger 给 application 事件来决定是否允许退出；需要注意的是，如果用户访问 iportal 容器页时没有进行任何点击跳转操作则将直接退出应用，除非页面设置了[preindex] 配置，且配置生效时。

从其他页面进入到 iportal 容器页时，当点击浏览器返回按钮是并不会退出应用页面，而是会通过 [holdBack] 配置进行判断是否应该被退出，并同时返回用户点击返回按钮的次数。

---

### 退出控制
** [holdBack?: (backCount： number) => boolean] **
frameworks 模块专有，需[singleLock]开启时有效，当用户进行返回操作，且页面即将退出时，会通过该函数（如果被阻止，backCount 为点击返回的次数）进行校验，返回 true 时为阻止应用页面退出，否则则是允许退出。

---

### 应用首页
** [index: string] **
设置应用的默认首页，该首页模块建议进行 source -> html 的配置，因为这样可以同步加载该模块，以提升初次加载性能。

---

### 插入前置页面
**  [preindex: string] **
当页面 url 指定到某个模块访问时，如果指定模块名不等于 index 时，则可以通过该配置设置一个前置模块名，此时访问链接时会优先访问地址页面，但是当点击浏览器返回时不会立刻退出，而是会到达这个前置模块页面。

---

### 模块层级
** [level: number] **
模块的层级，层级为 0 时为根模块，当历史回退到此时会触发 singleLock 配置相关内容。模块层级还会影响预置动画的形式，比如 A < B 时，模块以 slide 预置动画执行时则会是 从左到右的动画模式，反之模块则以 从右到左的动画模式运行。

---

### 依赖预渲染
**  [prerender?: Array[string]]  **
当前模块中如果存在链接到其他模块，且希望能预先载入这些模块，通俗讲即当前页面中如果有 a 链接可能会跳转到某个模块时，则需要设置该属性。页面会在空闲时对页面中 source -> src 或者 source -> html 的内容进行预加载，包括文档中的 css 以及 js 等静态资源的预载。

---

### 后台极限
** [limit?: number] **
默认为 5, 最大值为 100。其表示为应用中所允许的最多同时后台运行的页面，当超过时会根据访问前后对最先访问的模块进行销毁，如果配置了 background = true 则不受影响。

---

### 404
** [notFind?: string] **
404 模块，所请求的模块页面不存在时会自动路由到该模块，若未配置时则会自动跳转到名为 404 的模块。

---

### 框架背景色
** [color?: string] **
模块的默认背景色，当动画切换场景时，模块还处于加载时会以该背景色来填充。默认值会根据浏览器设置的颜色模式自动填充 黑色/白色。

---

### Portals 特性
** [portal?：boolean]  **
设置为 portal 的页面必须 [free] 也设置为 true，portal 页面会在转场动画结束后执行激活操作，激活后页面会完全转移到全新的浏览器上下文中。当浏览器不支持 portal 能力时会自动降级为一般沙盒模。

---

### 链接捕捉
** [capture?: string | ((resolve: { path: string; origin: string; host: string; search: string }, url: string) => boolean] **
可接受一个 url path，当其他页面中存在跳转地址匹配时会被捕获，并按照该模块配置运行新窗口页面。另外也可接受一个函数，resolve 为捕获的 url 信息，当返回 true 时则表示需要捕获该链接并以新窗口打开。
注意：该能力需要在 [apply] 中开启了 link-in-new-window 时有效，同样的被捕捉页面需要保持同源原则。

---

### 准许Host
** [allowHost?: string[]] **
frameworks 模块专有，当没有设置了 [capture] 时，可通过该配置来过滤掉不需要捕获的 host 地址，反之则会自动进行捕获。该配置主要用于防止 url 参数访问的安全防护。当 frameworks 模块设置了  [capture] 时，则会忽略该配置。
注意：此项同样需遵循同源原则。

---

### 自动媒体管理
** [mediaGuard?: boolean] **
设置时会对同源页面中的 视频和音频进行智能的管理，当模块隐藏时则自动暂停正在播放的音视频，反之模块可见时则恢复暂停的音视频；同时不设置时，也可以通过窗口可见事件来自行进行管理。

---

### 全局配置处理
** [moduleManifestProcess?: (config：ModuleManifest)=> ModuleManifest] **
frameworks 模块专有，当模块载入时，模块配置会先经此函数处理再返回。

---

### 边缘触摸
 [touchBorder?: (borders: ModuleTouchBorder, module: Module, application: Application) => void]
设置时模块的边缘触摸事件会得到监听，比如双击模最块顶部执行回到顶部的操作，触摸模块的最左侧可用来执行模块的跟手动画等等。

---

### 预置能力
** [apply?: Array<'smart-setTimeout' | 'smart-setInterval' | 'link-in-new-window' | 'tap-highlight' | ['tap-highlight', string]>] **
在同源模块中将自动执行这些预置的应用：
  a. smart-setTimeout： 当模块不可见或动画过程中时，所有 setTimeout 会停止执行，相反当模块恢复可见时 setTimeout 也将恢复工作；
  b. smart-setInterval： 同 smart-setTimeout
  c. link-in-new-window： 当页面中有 a链接，或 open 方法打开页面时 会自动进行捕捉拦截，并将页面内容生成新模块的形式并进行加载展示；若设置 target='self' 时则会忽略此逻辑；同时可以设置 preset-effect="预置动画名"，clone-as="新模块名"
  d. tap-highlight：所有 a链接 在点击时会自动添加半透明蒙层高亮提示效果；
  e. ['tap-highlight', string]： 同 tap-highlight，参数为 attr 的匹配，仅匹配元素才增加高亮效果；

---

### 能力注入
** [inject?: (w: Window, m: Module) => void] **
当同源模块时可在页面载入前对页面注入默认的功能和方法，比如提前注入一些 bridge 方法，通用变量，改写一些全局对象等等。

---

### 沙盒
** [sandbox?: 'allow-same-origin' | 'allow-scripts' | 'allow-forms' | 'allow-modals' | 'allow-orientation-lock' | 'allow-popups' | 'allow-pointer-lock' | 'allow-popups-to-escape-sandbox' | 'allow-presentation' | 'allow-top-navigation' | 'allow-top-navigation-by-user-activation' | 'allow-downloads-without-user-activation' | 'allow-storage-access-by-user-activation' | 'allow-top-navigation-by-user-activation' | string] **
设置容器的沙盒限制。

### 转场动画
[animation?: string | boolean | Array<string> | [(e: TransformAnimateEvent) => void | Promise<boolean>, (e: TransformAnimateEvent) => void | Promise<boolean>]
转场动画模式，其中预置了常用动画如下：
* 动画待补充
* flip
* flipLeft
* flipDown
* flipUp
* fade
* zoom
* slide
* slideLeft
* slideRight
* slideUp
* slideDown
* flipRight
除了预置的动画外，还可以通过函数配置自定义动画，同时函数入参还会带入一些可用参数：

```ts
interface TransformAnimateEvent {
  x: number
  y: number
  in: Animate // 切入模块动画类
  out: Animate // 切出模块动画类
  view: Array<HTMLElement> // 视图数组
  width: number
  height: number
  viewport: Array<HTMLElement> // 视窗数组
  modules: Array<Module> // 切换模块数组
  reverse: boolean // 是否反向流动
  direction: number // 流动方向，1前进，-1后退
  backset: number // 流动状态，1前进，-1后退， 0替换
  origin: string | Array<number> // 触发位置
  attach: string | Array<number> // 相轴
  touches: TransformActionOrigin | undefined // 触发 touch 事件
  historyDirection: number // 浏览器前进后退方向
  callback: Function // 结束回掉函数，Promise 模式下不需要用到
}
```

---

## Module.events
模块常用事件：
* [transformStart: () => void | boolean]:  模块转场动画开始， 返回值会停止转场操作
* [transformEnd: () => void]：模块动画转场结束
* [start: () =>void]：配置启动事件
* [load: () =>void]：模块加载事件
* [loadError: () =>void]：模块加载错误事件
* [preload: () =>void]：模块预载事件
* [destroy: () =>void]：模块销毁事件