Install

Use npm install

$ npm install iportal --save

荐：使用 Typescript 进行开发

Start

应用启动前须进行模块配置。

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

执行 satrt 命令以启动应用。

Title

模块的标题，在页面切换时会体现在文档标题上。

export default { config: { title: 'Home Page' } }

注：frameworks 与 system 类型模块可无需定义。

Source

定义模块的 HTML 源代码，可进行两种方式的定义，选其中一种即可。

源码模式

export default { config: { title: 'Home Page', source: { html: ` <html lang="en"> <head></head> <body> { anything } </body> </html> ` } } }

链接模式

export default { config: { title: 'Home Page', source: { src: 'http://yoursite.com' } } }

注：使用链接模式时需符合同源策略，否者某些能力将无法开启，比如 Capture、Apply、Inject 等。

Index

frameworks 类型专有

定义应用的默认模块入口。

*value: string

export default { config: { title: '', index: 'home' } }

当应用启动时将首先初始化模块名为 “home” 的模块内容。

注：在框架模块 (即 [rel = frameworks]) 中必须指定 index 首页模块，除非你期望由框架模块来承载首屏内容。

Rel

定义模块的类型。

模块分为三种类型，“module”、“framework”、“system”

*value: 'module' | 'frameworks' | 'system'

export default { config: { title: '', rel: 'module' } }

1. “system” 类型的模块是放置在 Main Tree 下的，切不随着任何的模块路由而改变的，比如 app 中的辅助浮标、日期/信号头部栏、系统下拉通知等等。比如下面视频中的 AssistiveTouch 功能就是一个“system” 类型的模块的功能。

2. “framework” 类型则一般是具有框架模式的模块，比如淘宝首页中包含底部导航栏的部分，该导航栏是多个页面所共有的，所以它可以是一个框架层的模块，框架层的模块相对系统层的模块的区别是有着更低层的级别，比如窗口切换的时候框架层可以随之切换，而系统层则不会随之切换。

3. “module” 类型则是最常见的类型，我们可以理解为一个纯粹的页面，同时模块类型还分为自由类型和嵌入类型，后面的 [free] 配置中会讲到。

注：“framework” 框架类型的模块是唯一的。未定义该值时默认为 module 类型。

Free

定义模块的窗口类型。

value: boolean

export default { config: { title: '', free: true } }

该设置下模块以“全屏模式”运行，即不受框架模块约束，假设框架模块中带有 tab 能力时，该模块设置 free 为 true，此时模块将覆盖框架层运行，反之模块则会在框架层之内运行。

Level

对模块的显示层级进行定义。

value: number

export default { config: { title: 'Home Page', level: 1 } }

一般首页模块的层级为 0，根据页面访问层级逐渐增大。

模块层级关系还将反应在转场动画上，从小到大为正向动画，反之从大到小时是逆向动画

当历史回退到层级为 0 的模块时，会触发 singleLock 配置相关内容

注：同层级模块间的动画效果会被关闭。

Color

定义模块的窗口背景色。

value: string

export default { config: { title: '', free: true, color: '#bd243f' } }

设置模块的默认背景色可以进行更加无缝化的过渡，当转场开始时，模块可能还处于加载状态，此时会以设定背景色来填充模块区域。

注：请确保背景色与模块主色一致。未设置时，默认值会根据浏览器设置的颜色模式自动填充黑色/白色。

点击按钮查看效果

Animate Effect

定义模块的窗口动画效果为预置的动画效果。

export default { config: { title: '', free: true, color: '#000', animation: 'slide' } }

与‘slide’等效的动画名称： 'slide' ｜ 'slide-left' | 'slideLeft'。同理其他书写形式。

注：动画的默认效果为 slide。

Custom Effect

自定义模块的窗口动画效果。

value: (e: TransformAnimateEvent) => void | Promise ｜ [(e: TransformAnimateEvent) => void | Promise, (e: TransformAnimateEvent) => void | Promise

const getAnimate = (type: number) => { return (e: TransformAnimateEvent) => { let inO: number, outO: number, inV: Animate, outV: Animate switch (type) { case 0: inO = 1 outO = 0 inV = e.in outV = e.out break case 1: default: inO = 0 outO = 1 inV = outV = e.in } inV.duration(0).ease('ease-out-expo').to(0, 0, 0).opacity(inO).end(function () { outV.duration(767).opacity(outO).end(function () { e.callback(false) }) }) setTimeout(() => { e.callback(false) }, 1200) } } export default { config: { title: '', free: true, color: '#000', animation: [getAnimate(0), getAnimate(1)] } }

TransformAnimateEvent 为自定义动画中提供的可用对象

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 模式下不需要用到 } interface TransformActionOrigin { x: number, y: number }

数组中的第一个函数为正向动画，第二个函数为逆向动画。如果值为函数，则可通过参数进行动画控制，比如 direction、historyDirection 等。

Background

定义模块是否被允许在后台运行。

value: boolean ｜ 'auto'

export default { config: { title: '', free: true, background: true } }

value = false：模块切换动画结束后会被立即销毁。

value = true：模块不会被销毁（仅当页面 load 成功时）；例外情况是当 timeout 超时时，在启动前会被销毁。

value = 'auto'：当设置成自动时模块会进行智能的判断是否销毁，当触发以下几种情况时则会被销毁：
ⅰ. 页面设置了 src，且不同源时；
ⅱ. 页面中包含了 object、embed、applet、iframe 对象时；
ⅲ. 页面中包含了 video、audio 标签时，且开启智能媒体管理时自动暂停播放出错时；
ⅳ. 页面中存在节点变动操作在 3 秒钟内超过 10 次时；
ⅴ. 页面中总的节点操作在后台运行超过 1000 次时；

Timeout

定义模块的有效时常，单位毫秒。

value: number

export default { config: { title: '', free: true, timeout: 36000 } }

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

注：若该值设置为 0 时，则背景运行将不会生效。

Limit

frameworks 类型专有

定义应用最大可缓存在后台的模块数量。

value: number

export default { config: { title: '', free: true, limit: 7 } }

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

Resource

根据资源类型配置资源 url 数组，在预载入时会根据该配置做预载。

value: number

interface ModuleResources { script?: Array<string> image?: Array<string> worker?: Array<string> video?: Array<string> audio?: Array<string> font?: Array<string> style?: Array<string> } export default { config: { title: '', free: true }, resource: { script: [ 'http://xxx.com/js/index.js', ], image: [ 'http://xxx.com/img/background.jpg', ] } }

注：html 中的 script、css 标签等非脚本异步加载的资源则无需单独配置，此处仅用于脚本执行后的依赖资源，比如 css 中的 font 字体，某场景的主题素材等。

Prerender

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

value: Array<string>

export default { config: { title: '', free: true, prerender: ['module1', 'module2', 'module3'] } }

Components

在模块中注册 Web Components。使用 Web Components 能够极大提升页面性能。

value: ((w: Window) => CustomElementConstructor)[]

export default { config: { title: '', free: true }, components: [getComponents1, getComponents2, getComponents3] }

组件例子

export const ScopeCodeHighlighter = (w): CustomElementConstructor => { class CodeHighlighter extends w.HTMLElement { constructor () { super() const shadowRoot = this.attachShadow({ mode: 'open' }) shadowRoot.appendChild(tmpl.content.cloneNode(true)) ... } } return CodeHighlighter as unknown as CustomElementConstructor }

注：模块初始化时将进行调用获取组件函数，同时会将注册上下文 Window 传入，同时返回组件对象 CustomElementConstructor 用于在上下文中进行注册。

MediaGuard

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

value: Array<string>

export default { config: { title: '', free: true, mediaGuard: true } }

Portals

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

value: Array<string>

export default { config: { title: '', free: true, portals: true } }

AllowHost

frameworks 类型专有

当没有设置 [capture] 时，可通过该配置来过滤掉不需要捕获的 host 地址，反之则会自动进行捕获。该配置主要用于防止 url 参数访问的安全防护。当 frameworks 模块设置了 [capture] 时，则会忽略该配置。

value: Array<string>

export default { config: { title: '', free: true, allowHost: [ 'aaa.com', 'bbb.com', 'ccc.com' ] } }

Sandbox

value: string

export default { config: { title: '', free: true, sandbox: 'allow-modals' } }

Capture

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

value: string | ((resolve: { path: string; origin: string; host: string; search: string }, url: string) => boolean]

export default { config: { title: '', free: true, capture: (resolve) => { return resolve.path === '/abc/abc' } } }

Apply

在同源模块中将自动执行这些预置的应用：
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 的匹配，仅匹配元素才增加高亮效果；

value: Array<'smart-setTimeout' | 'smart-setInterval' | 'link-in-new-window' | 'tap-highlight' | ['tap-highlight', string]>]

export default { config: { title: '', free: true, apply: ['smart-setTimeout', 'link-in-new-window'] } }

Events

定义模块事件监听

value: Array<string>

export default { config: { title: '', free: true }, events: { transformEnd: () => { // ... } } }

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

Preindex

frameworks 类型专有

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

value: string | ((resolve: { path: string; origin: string; host: string; search: string }, url: string) => boolean]

export default { config: { title: '', preindex: 'home' } }

NotFind

frameworks 类型专有

404 模块，所请求的模块页面不存在时会自动路由到该模块，若未配置时则会自动跳转到名为 404 的模块。

value: string

export default { config: { title: '', notFind: 'fund' } }

SingleFlow

frameworks 类型专有

只允许页面的历史记录往 level 较小的模块回退，当前一个历史模块的 level 层级大于等于时则进行跳过。

value: boolean

export default { config: { title: '', singleFlow: true } }

例如：从生成订单模块的到支付模块再到我的订单模块，完成后进行回退时可选择直接回到订单生成前页面，而无需经过订单过程中的模块页面。

SingleLock

frameworks 类型专有

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

value: boolean

export default { config: { title: '', singleLock: true, holdBack: (event) => { // 判断是否退出 return true } } }

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

HoldBack

frameworks 类型专有

需[singleLock]开启时有效，当用户进行返回操作，且页面即将退出时，会通过该函数（如果被阻止，backCount 为点击返回的次数）进行校验，返回 true 时为阻止应用页面退出，否则则是允许退出。

value: (backCount： number) => boolean]

export default { config: { title: '', singleLock: true, holdBack: (event) => { // 判断是否退出 return true } } }

Transient

标记该模块为临时模块，在切换到后台时，模块不仅会被销毁，同时模块配置数据也将一并被删除，无特殊情况下一般无需单独配置。

value: boolean

export default { config: { title: '', free: true, transient: true } }

注：通过新窗口打开的 url 类型模块，会被自动进行该标记。

ModuleManifestProcess

frameworks 类型专有

当模块载入时，模块配置会先经此函数处理再返回。

value: (config：ModuleManifest)=> ModuleManifest]

export default { config: { title: '', moduleManifestProcess: (manify) => { ... 处理 return newManify } } }

TouchBorder

设置时模块的边缘触摸事件会得到监听，比如双击模最块顶部执行回到顶部的操作，触摸模块的最左侧可用来执行模块的跟手动画等等。

value: (borders: ModuleTouchBorder, module: Module, application: Application) => void

export default { config: { title: '', touchBorder: (borders, module, application) => { ... 处理模块跟手效果/或点击顶部回到顶部效果 } } }

Inject

当同源模块时可在页面载入前对页面注入默认的功能和方法，比如提前注入一些 bridge 方法，通用变量，改写一些全局对象等等。

value: (w: Window, m: Module) => void]

export default { config: { title: '', inject: (moduleWindow, module) => { ... } } }

Render

除了 source 模式外还可以通过 render 方法来渲染元素到对应的节点上，可供系统模块和框架模块使用，不推荐普通模块使用该方法渲染。

value: (target: HTMLElement) => void]

export default { config: { title: '', render: (target) => { ... target.appendChild(...) // or ReactDOM.render(<App />, target) } } }

SafeArea

frameworks 类型专有

设定应用的安全边距。

value: string | Array<string>

export default { config: { title: '', safeArea: ['44px', '0px', '0px', '0px'] } }

值为数字时，分别按顺序表示顶部、右侧、底部、左侧的安全边距。

设置该值后将会在符合同域原则下的模块中注入 CSS 全局变量：--application-safe-area-top、--application-safe-area-right、--application-safe-area-bottom、--application-safe-area-left 四个对应的安全边际值。

如果需要动态的修改这个值则可以通过发送 “safeAreaChange” 事件来进行更新。

例如:

application.trigger('safeAreaChange'，['88px', '0px', '0px', '0px'])

GlobalCSSVariables

frameworks 类型专有

设定应用的全局 CSS 变量。

value: { [key: string]: string }

export default { config: { title: '', globalCSSVariables: { '---common-background-color': '#fff', '---common-button-color': 'blue', } } }

与 [safeArea] 类似，同样只能在同域原则下有效，与其相比具有能力覆盖的效果。

如果需要动态的修改或增加这个值则可以通过发送 “globalCSSVariablesChange” 事件来进行更新。

例如:

application.trigger('globalCSSVariablesChange'，{ '---common-button-color': 'red' })