# View

## static currentState

> 获取当前的浏览状态。

**签名：**

`View.currentState:` [`ViewState`](/lei-xing/viewstate) 

**可用版本：**`1.6.2+`

**返回：**

当前的浏览状态，反映了当前活动视图的浏览信息。

## static context

> 公用数据存取上下文，用于跨视图存取数据。\
> 当需要抽取变量，使得可以跨视图访问时，开发者应当尽可能地使用公用上下文，而非 `window`，以降低变量污染的可能。

**签名：**

`View.context:` [`ViewContext`](/viewcontext) 

**可用版本：**`1.6.2+`

**返回：**

公用的数据存取上下文。

## static checkIfBrowserHistorySupportsPushPopAction()

> 判断浏览器的 `history` 对象是否支持 `pushState` API。

**签名：**

`View.checkIfBrowserHistorySupportsPushPopAction(): boolean`

**可用版本：**`1.6.2+`

**入参：**

无

**返回：**

`true` - 浏览器的 `history` 对象支持 `pushState` API。否则返回 `false`。

## static getViewContainerDomElement()

> 获取视图容器对应的 DOM 元素。

**签名：**

`View.getViewContainerDomElement(): HTMLElement`

**可用版本：**`1.6.2+`

**入参：**

无**。**

**返回：**

视图容器对应的 DOM 元素。如果开发者没有另外设置，将返回 `document.body`。

## static find()

> 从 DOM 树中获取匹配给定选择器的 DOM 元素。

**签名：**

`View.find(rootObj?: HTMLElement, selector: string): HTMLElement`

**可用版本：**`1.6.2+`

**入参：**

* `rootObj?: HTMLElement` - 检索 DOM 元素的根元素，可选。默认为视图容器。
* `selector: string` - 选择器。

**返回：**

给定根元素下，匹配给定选择器的 DOM 元素。如果没有 DOM 元素与之对应，则返回 `null` 。

**调用举例：**

```javascript
/**
 * 从 视图容器 中检索 class 名包含 btn 的 DOM 元素
 */
var btnObj = View.find(".btn");

/**
 * 从 containerObj 中检索 class 名包含 btn 的 DOM 元素
 */
btnObj = View.find(containerObj, ".btn");

```

## static findAll()

> 从 DOM 树中获取匹配给定选择器的多个 DOM 元素。

**签名：**

`View.findAll(rootObj?: HTMLElement, selector: string): NodeList | null`

**可用版本：**`1.6.2+`

**入参：**

* `rootObj?: HTMLElement` - 检索 DOM 元素的根元素，可选。默认为视图容器。
* `selector: string` - 选择器。

**返回：**

给定根元素下，匹配给定选择器的多个 DOM 元素。如果给定的 `rootObj` 为 `null` ，则返回 `null` 。

## static ofId()

> 获取视图实例。

**签名：**

`View.ofId(viewId: string, viewNamespace?: string): View`

**可用版本：**`1.6.2+`

**入参：**

* `viewId: string` - 视图ID。
* `viewNamespace?: string` - 视图隶属的命名空间。可选，默认为：`default`。

**返回：**

匹配的视图实例。

{% hint style="warning" %}
如果视图容器中没有 DOM 元素与给定的 ID 和 命名空间 匹配，则抛出异常。
{% endhint %}

## static ifExists()

> 判断视图是否存在。

**签名：**

`View.ifExists(viewId: string, viewNamespace?: string): boolean`

**可用版本：**`1.6.2+`

**入参：**

* `viewId: string` - 视图ID。
* `viewNamespace?: string` - 视图隶属的命名空间。可选，默认为：`default`。

**返回：**

`true` - 视图存在，`false` - 视图不存在。

{% hint style="warning" %}
如果在 View\.js 完成初始化之前调用该方法，无论视图是否真正存在，都将返回 `false` 。
{% endhint %}

## static listAll()

> 列举所有视图。

**签名：**

`View.listAll(viewName?: string): View[]`

**可用版本：**`1.6.2+`

**入参：**

* `viewName?: string` - 视图名称，可选。如果为空，则返回所有视图实例。否则返回声明为该名称的视图实例。不区分大小写。

**返回：**

匹配给定名称的，或者所有实例化的视图实例组成的数组。

## static listAllViewNames()

> 列举被视图声明了的所有视图名称。

**签名：**

`View.listAllViewNames(): string[]`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

被视图声明的所有视图名称。如果没有任何视图声明有视图名称，将返回空数组。

{% hint style="info" %}
视图名称在视图的 DOM 骨架上，使用 `data-view-name` 属性声明。
{% endhint %}

## static setAsDefault()

> 设置给定的视图为默认视图。

**签名：**

`View.setAsDefault(viewId: string, viewNamespace?: string): View`

**可用版本：**`1.6.2+`

**入参：**

* `viewId: string` - 视图ID。
* `viewNamespace?: string` - 视图隶属的命名空间。可选，默认为：`default`。

**返回：**

`window.View` 以供开发者链式调用。

## static isDirectlyAccessible()

> 判断所有视图默认是否可以直接访问。

**签名：**

`View.isDirectlyAccessible(): boolean`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

`true` - 视图默认可以直接访问，`false` - 视图默认不可以直接访问。

{% hint style="info" %}
如果没有单独声明，视图将使用该默认值决定自己是否可以直接访问。
{% endhint %}

## static setIsDirectlyAccessible()

> 设置所有视图默认是否可以直接访问。

**签名：**

`View.setIsDirectlyAccessible(isDirectlyAccessible: boolean): View`

**可用版本：**`1.6.2+`

**入参：**

* `isDirectlyAccessible: boolean` - 是否可以直接访问。

**返回：**

`window.View` 以供开发者链式调用。

## static setViewIsDirectlyAccessible()

> 设置特定视图是否可以直接访问。

**签名：**

`View.setIsDirectlyAccessible(viewId: string, viewNamespace?: string, isDirectlyAccessible: boolean): View`

**可用版本：**`1.6.2+`

**入参：**

* `viewId: string` - 视图ID。
* `viewNamespace?: string` - 视图隶属的命名空间。可选，默认为：`default` 。
* `isDirectlyAccessible: boolean` - 是否可以直接访问。

**返回：**

`window.View` 以供开发者链式调用。

{% hint style="info" %}
有别于 `viewInstance.setIsDirectlyAccessible()` ，该方法可以在 View\.js 完成初始化之前调用。
{% endhint %}

## static getActiveView()

> 获取当前的活动视图。

**签名：**

`View.getActiveView(): View | null`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

当前处于活动状态的视图。如果没有视图处于活动状态（如：View\.js 尚未完成初始化），则返回 `null` 。

## static getDefaultView()

> 获取默认视图。

**签名：**

`View.getDefaultView(): View | null`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

默认视图。如果 View\.js 尚未完成初始化，则返回 `null` 。

## static getSwitchAnimation()

> 获取设置的视图跳转动画执行器。

**签名：**

`View.getSwitchAnimation():` [`ViewSwitchAnimation`](/lei-xing/viewswitchanimation) `| null`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

设置的视图跳转动画执行器。如果没有设置，则返回 `null` 。

## static setSwitchAnimation()

> 设置视图跳转动画执行器。

**签名：**

`View.setSwitchAnimation(animation:` [`ViewSwitchAnimation`](/lei-xing/viewswitchanimation)`): View`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

`window.View` 以供开发者链式调用。

## static getActiveViewOptions()

> 获取体现在地址栏中的，当前活动视图的视图选项集合。

**签名：**

`View.getActiveViewOptions(): Object | null`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

当前活动视图的视图选项集合。视图选项以 key-value 的形式存放在集合中。如果没有任何视图选项，则返回 `null` 。

**调用举例：**

```javascript
var options = View.getActiveViewOptions();

var paramValue1 = options["param-name1"],
    paramvalue2 = options.paramName2;

```

## static hasActiveViewOptions()

> 判断当前活动视图的视图选项集合中，是否含有给定键名的参数。

**签名：**

`View.hasActiveViewOptions(name: string): boolean`

**可用版本：**`1.6.2+`

**入参：**

* `name: string` - 参数的键名。

**返回：**

`true` - 视图选项集合不为 `null` ，且集合中含有 key 为给定键名的数据。否则，返回 `false` 。

## static getActiveViewOptions()

> 从当前活动视图的视图选项集合中，获取给定键名的参数取值。

**签名：**

`View.getActiveViewOptions(name: string): string | null`

**可用版本：**`1.6.2+`

**入参：**

* `name: string` - 参数的键名。

**返回：**

参数取值。如果集合为 `null` ，或参数不存在，则返回 `null` 。

## static setActiveViewOptions()

> 为当前活动视图设置视图选项。

**签名：**

`View.setActiveViewOptions(name: string, value: string): View`

**可用版本：**`1.6.2+`

**入参：**

* `name: string` - 参数的键名。
* `value: string` - 参数的取值。

**返回：**

`window.View` 以供开发者链式调用。

## ~~static passBy()~~

> “穿过”视图，用于在不渲染界面、不触发关联事件的情况下 “伪造” 视图的访问记录。
>
> 该方法自 `1.7.0` 开始被废弃（仍然可用），开发者可使用等价的 `View.navBy()` 替代。

**签名：**

`View.passBy(viewId: string, viewNamespace?: string): View`

**可用版本：**`1.6.2+`

**入参：**

* `viewId: string` - 视图ID。
* `viewNamespace?: string` - 视图隶属的命名空间。可选，默认为：`default` 。

**返回：**

`window.View` 以供开发者链式调用。

**调用举例：**

```javascript
/**
 * 导航至 我的银行卡列表 界面。
 *
 * 通过伪造 profile 的访问记录，实现 “虽然用户看到的是 银行卡列表 界面，
 * 但点击页面中的返回按钮，将返回到 个人中心 界面”的目的
 */
View.passBy("profile").navTo("my-bankcard-list");

/**
 * 1秒后页面将返回至 个人中心
 */
setTimeout(function(){
    View.back();
}, 1000);
```

## static navBy()

> 以 压入堆栈 的方式 “略过” 视图，用于在不渲染界面、不触发关联事件的情况下 “伪造” 视图的访问记录。

**签名：**

`View.navBy(viewId: string, viewNamespace?: string): View`

**可用版本：**`1.7.0+`

**入参：**

* `viewId: string` - 视图ID。
* `viewNamespace?: string` - 视图隶属的命名空间。可选，默认为：`default` 。

**返回：**

`window.View` 以供开发者链式调用。

**调用举例：**

```javascript
/**
 * 导航至 我的银行卡列表 界面。
 *
 * 通过伪造 profile 的访问记录，实现 “虽然用户看到的是 银行卡列表 界面，
 * 但点击页面中的返回按钮，将返回到 个人中心 界面”的目的
 */
View.navBy("profile").navTo("my-bankcard-list");

/**
 * 1秒后页面将返回至 个人中心
 */
setTimeout(function(){
    View.back();
}, 1000);
```

## static changeBy()

> 以 替换栈顶 的方式 “略过” 视图，用于在不渲染界面、不触发关联事件的情况下 “伪造” 视图的访问记录。

**签名：**

`View.changeBy(viewId: string, viewNamespace?: string): View`

**可用版本：**`1.7.0+`

**入参：**

* `viewId: string` - 视图ID。
* `viewNamespace?: string` - 视图隶属的命名空间。可选，默认为：`default` 。

**返回：**

`window.View` 以供开发者链式调用。

**调用举例：**

```javascript
/**
 * 导航至 我的银行卡列表 界面。
 *
 * 通过伪造 my-wallet 的访问记录，实现 “虽然用户看到的是 银行卡列表 界面，
 * 但点击页面中的返回按钮，将返回到 我的钱包 界面”的目的
 */
View.navTo("profile").changeBy("my-wallet").navTo("my-bankcard-list");

/**
 * 1秒后页面将返回至 我的钱包
 */
setTimeout(function(){
    View.back();
}, 1000);
```

## static navTo()

> 以 压入堆栈 的方式跳转至目标视图。

**签名1：**

`View.navTo(viewId: string, viewNamespace?: string, ctrl:` [`ViewSwitchCtrl`](/lei-xing/viewswitchctrl)`): View`

**可用版本：**`1.6.2+`

**签名2：**

`View.navTo(viewInstance: View): View`

**可用版本：**`1.7.0+`

**入参：**

* `viewId: string` - 视图ID，或视图名称，或伪视图，或外部链接。

> 支持的伪视图包括：
>
> * `:back` - 前进，等同于 `View.back()`；
> * `:forward` - 后退，等同于 `View.forward()` ；
> * `:default-view` - 默认视图；
>
> 例如：
>
> ```javascript
> /**
>  * 后退，等同于 View.back()
>  *
>  * 第一个参数指定了跳转目标；
>  * 第二个参数指定了跳转控制选项，其中，关键字：'params' 用于指定视图参数集合。
>  */
> View.navTo(":back", {
>     params: {
>         paramName1: "boo"
>     }
> });
>
> /**
>  * 后退，等同于 View.forward()
>  */
> View.navTo(":forward", {
>     params: {
>         paramName1: "boo"
>     }
> });
>
> /**
>  * 跳转至默认视图
>  * 第二个参数指定了跳转控制选项，其中，关键字：'options' 用于指定视图选项集合。
>  */
> View.navTo(":default-view", {
>     params: {
>         paramName1: "boo"
>     },
>     options: {
>         paramName2: "foo"
>     }
> });
> ```

> 当为视图名称时，需要使用 `~` 符号前缀，例如：
>
> ```javascript
> /**
>  * 跳转至视图名称为 profile 的第一个视图上去
>  */
> View.navTo("~profile"，{
>     params: {
>         param1: "value1"
>     },
>     options: {
>         param2: "value2"
>     }
> });
> ```

> 当为外部链接，且链接地址为完整路径时，可以直接赋值为链接地址，例如：
>
> ```javascript
> /**
>  * 跳转至完整的外部链接
>  */
> View.navTo("http://view-js.com");
> ```
>
> 如果外部链接地址不完整，则需要使用 `@` 符号前缀，例如：
>
> ```javascript
> /**
>  * 跳转至当前目录下的 index.html 页面
>  */
> View.navTo("@index.html");
> ```

* `viewNamespace?: string` - 视图隶属的命名空间。可选，默认为：`default` 。
* `ctrl?:` [`ViewSwitchCtrl`](/lei-xing/viewswitchctrl) - 视图跳转控制。可选。
* `viewInstance: View` - 视图实例。

**返回：**

`window.View` 以供开发者链式调用。

**调用举例：**

```javascript
/**
 * 以“压入堆栈”的方式跳转至 myNamespace 命名空间下, ID为 targetVieWId 的视图
 *
 * 第一个参数指定了跳转目标；
 * 第二个参数指定了跳转控制选项，其中，关键字：'params' 用于指定视图参数集合，
 * 'options' 用于指定视图选项集合。
 */
View.navTo("targetViewId", "myNamespace", {

    /**
     * 开发者可以在视图参数集合指定任意数量的参数，参数取值可以是
     * 任意合法的js类型
     */
    params: {
        paramName1: "boo",/* 传导字符串 */
        paramName2: true,/* 传导枚举值 */
        paramName3: ['str', 123, false, new Object()],/* 传导数组 */
        paramName4: View.find(".container"),/* 传导DOM元素 */
        paramName5: function(data){doSth(data);}/* 传导回调方法 */
    },
    
    /**
     * 视图选项只支持字符串类型
     */
    options: {
        paramName1: "boo"
        paramName2: "bar"
    }
    
});
```

{% hint style="info" %}
自 `1.7.0` 开始，开发者可以通过 `View.addSwitchInterceptor()` 方法添加拦截器，阻止视图跳转动作的执行。
{% endhint %}

## static changeTo()

> 以 替换栈顶 的方式跳转至目标视图。

**签名1：**

`View.changeTo(viewId: string, viewNamespace?: string, ctrl:` [`ViewSwitchCtrl`](/lei-xing/viewswitchctrl)`): View`

**可用版本：**`1.6.2+`

**签名2：**

`View.changeTo(viewInstance: View): View`

**可用版本：**`1.7.0+`

**入参：**

* `viewId: string` - 视图ID，或视图名称，或伪视图，或外部链接。

> 支持的伪视图包括：
>
> * `:default-view` - 默认视图；

> 例如：
>
> ```javascript
> /**
>  * 跳转至默认视图
>  * 第二个参数指定了跳转控制选项，其中，关键字：'options' 用于指定视图选项集合。
>  */
> View.changeTo(":default-view", {
>     params: {
>         paramName1: "boo"
>     },
>     options: {
>         paramName2: "foo"
>     }
> });
> ```

> 当为视图名称时，需要使用 `~` 符号前缀，例如：
>
> ```javascript
> /**
>  * 跳转至视图名称为 profile 的第一个视图上去
>  */
> View.changeTo("~profile"，{
>     params: {
>         param1: "value1"
>     },
>     options: {
>         param2: "value2"
>     }
> });
> ```

> 当为外部链接，且链接地址为完整路径时，可以直接赋值为链接地址，例如：
>
> ```javascript
> /**
>  * 跳转至完整的外部链接
>  */
> View.changeTo("http://view-js.com");
> ```
>
> 如果外部链接地址不完整，则需要使用 `@` 符号前缀，例如：
>
> ```javascript
> /**
>  * 跳转至当前目录下的 index.html 页面
>  */
> View.changeTo("@index.html");
> ```

* `viewNamespace?: string` - 视图隶属的命名空间。可选，默认为：`default` 。
* `ctrl?:` [`ViewSwitchCtrl`](/lei-xing/viewswitchctrl) - 视图跳转控制。可选。
* `viewInstance: View` - 视图实例。

**返回：**

`window.View` 以供开发者链式调用。

{% hint style="info" %}
自 `1.7.0` 开始，开发者可以通过 `View.addSwitchInterceptor()` 方法添加拦截器，阻止视图跳转动作的执行。
{% endhint %}

## static **addSwitchInterceptor**()

> 添加视图跳转拦截器。

**签名：**

`View.addSwitchInterceptor(interceptor:` [`ViewSwitchInterceptor`](/lei-xing/viewswitchinterceptor)`): View`

**可用版本：**`1.7.0+`

**入参：**

* `interceptor: ViewSwitchInterceptor` - 拦截器。

**返回：**

`window.View` 以供开发者链式调用。

**调用举例：**

```javascript
/**
 * 添加拦截器：“修改密码” 页面要求登录
 */
View.addSwitchInterceptor(function(meta){
    var targetViewId = meta.targetView.id;
    /* 如果目标视图不是 “修改密码”，则放行 */
    if("change-password" !== targetViewId)
        return true;
    
    if(user.isLogined())
        return true;
    
    toast("请登录");
    //...
    
    return false;
});

/**
 * 添加拦截器：“删除商品” 页面要求有权限
 */
View.addSwitchInterceptor(function(meta){
    var targetViewId = meta.targetView.id;
    /* 如果目标视图不是 “删除商品”，则放行 */
    if("delete-goods" !== targetViewId)
        return true;
    
    if(user.isAuthorized(targetViewId))
        return true;
    
    toast("没有权限");
    //...
    
    return false;
});
```

{% hint style="info" %}
拦截器将按添加顺序顺序执行。
{% endhint %}

## static get**SwitchInterceptors**()

> 获取添加的视图跳转拦截器列表。顺序与添加顺序保持一致。

**签名：**

`View.getSwitchInterceptors():` [`ViewSwitchInterceptor`](/lei-xing/viewswitchinterceptor)`[]`

**可用版本：**`1.7.0+`

**入参：**

无。

**返回：**

与添加顺序保持一致的视图跳转拦截器列表。

## static setNoViewToNavBackAction()

> 设置在“没有视图可以继续向前返回”的情况下，尝试返回时要执行的动作。\
> 开发者可以借助该特性，实现 “没有页面可以继续向前返回时，跳转至首页” 的效果。

**签名：**

`View.setNoViewToNavBackAction(action: Function): View`

**可用版本：**`1.6.2+`

**入参：**

* `action: Function` - 要执行的动作。

**返回：**

`window.View` 以供开发者链式调用。

**调用举例：**

```javascript
View.setNoViewToNavBackAction(function(){
    View.changeTo(":default-view");
});
```

## static back()

> 返回至上一个视图。

**签名：**

`View.back(ctrl?:` [`ViewBackForwardCtrl`](/lei-xing/viewbackforwardctrl)`): View`

**可用版本：**`1.6.2+`

**入参：**

* `ctrl?:` [`ViewBackForwardCtrl`](/lei-xing/viewbackforwardctrl) - 视图跳转控制。可选。

**返回：**

`window.View` 以供开发者链式调用。

## static forward()

> 前进至下一个视图。

**签名：**

`View.forward(ctrl?:` [`ViewBackForwardCtrl`](/lei-xing/viewbackforwardctrl)`): View`

**可用版本：**`1.6.2+`

**入参：**

* `ctrl?:` [`ViewBackForwardCtrl`](/lei-xing/viewbackforwardctrl) - 视图跳转控制。可选。

**返回：**

`window.View` 以供开发者链式调用。

## static setDocumentTitle()

> 设置文档标题。\
> 在视图之间发生跳转时，View\.js 会自动使用目标视图定义的标题更新文档标题。如果目标视图没有定义标题，则会使用初始化阶段捕获的浏览器标题呈现。如果初始化阶段的文档不是文档的最终标题，开发者需要在适当时机执行该方法。\
> View\.js 默认在 `DOMContentloaded` 事件触发后进行初始化。

**签名：**

`View.setDocumentTitle(title: string): View`

**可用版本：**`1.6.2+`

**入参：**

* `title: string` - 文档标题。

**返回：**

`window.View` 以供开发者链式调用。

## static reDoLayout()

> 执行所有视图的布局动作。\
> 每个视图实例都可以通过 `setLayoutAction()` 方法设置自己的布局动作。布局动作默认在视图进入时由 View\.js 自动执行。必要时，开发者可以通过调用本方法强制所有视图重新布局。

**签名：**

`View.reDoLayout(): View`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

`window.View` 以供开发者链式调用。

## static ifCanGoBack()

> 判断是否可以继续向前返回。亦即，历史堆栈中，是否还有更早的视图浏览记录。

**签名：**

`View.ifCanGoBack(): boolean`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

`true` - 可以继续向前返回；`false` - 已经返回到底了。

## static beforeInit()

> 添加 View\.js 初始化前要执行的处理器。

**签名：**

`View.beforeInit(action: Function): View`

**可用版本：**`1.6.2+`

**入参：**

* `action: Function` - 处理器。

**返回：**

`window.View` 以供开发者链式调用。

{% hint style="info" %}
所有处理器均以 同步 的方式被触发。
{% endhint %}

## static ready()

> 添加 View\.js 就绪后要执行的处理器。

**签名：**

`View.ready(action: Function): View`

**可用版本：**`1.6.2+`

**入参：**

* `action: Function` - 处理器。

**返回：**

`window.View` 以供开发者链式调用。

{% hint style="info" %}
所有处理器均以 同步 的方式被触发。
{% endhint %}

## ~~static setInitializer()~~

> 设置 View\.js 的初始化触发器。

**签名：**

`View.setInitializer(initializer:` [`ViewInitializer`](/lei-xing/viewinitializer)`, execTime?:` [`ViewInitializeTime`](/lei-xing/viewinitializetime)`): View`

**可用版本：**`1.6.2+`

**入参：**

* `initializer:` [`ViewInitializer`](/lei-xing/viewinitializer) - 初始化触发器。
* `execTime?:` [`ViewInitializeTime`](/lei-xing/viewinitializetime) - 触发器的执行时机。默认为：`'domready'` 。

**返回：**

`window.View` 以供开发者链式调用。

{% hint style="warning" %}
自 `1.7.0` 开始，本方法被标记为 “已废弃” （仍然可用），建议开发者使用新增的 `View.init()` 方法实现手动初始化 。
{% endhint %}

## static init()

> 初始化 View\.js 。       

**签名：**

`View.init(): View`

**可用版本：**`1.7.0+`

**入参：**

无。

**返回：**

`window.View` 以供开发者链式调用。

## static on()

> 添加宏观事件监听器。预置的宏观事件包括：\
> 1\. `beforechange` - 活动视图即将切换（同步触发）\
> 2\. `change` - 活动视图正在切换（同步触发）\
> 3\. `afterchange` - 活动视图切换完成（异步触发）
>
> 开发者也可以使用该方法监听自定义事件。

**签名：**

`View.on(eventName: string, handle:` [`ViewEventListener`](/lei-xing/vieweventlistener)`): View`

**可用版本：**`1.6.2+`

**入参：**

* `eventName: string` - 事件名称。
* `handle:` [`ViewEventListener`](/lei-xing/vieweventlistener) - 事件监听器 。

**返回：**

`window.View` 以供开发者链式调用。

**调用举例：**

```javascript
/**
 * 监听预置事件
 */
View.on("change", function(e){
    var info = e.data;
    
    /**
     * 跳转到的目标视图
     */
    var targetView = e.data.targetView;
    //...
});

/**
 * 监听自定义事件
 */
View.on("myEvent", function(e){
    var data = e.data;
    // doSth(data);
});
```

## static off()

> 移除宏观事件监听器。预置的宏观事件包括：\
> 1\. `beforechange` - 活动视图即将切换（同步触发）\
> 2\. `change` - 活动视图正在切换（同步触发）\
> 3\. `afterchange` - 活动视图切换完成（异步触发）

**签名：**

`View.off(eventName: string, handle:` [`ViewEventListener`](/lei-xing/vieweventlistener)`): View`

**可用版本：**`1.6.2+`

**入参：**

* `eventName: string` - 事件名称。
* `handle:` [`ViewEventListener`](/lei-xing/vieweventlistener) - 事件监听器 。

**返回：**

`window.View` 以供开发者链式调用。

## static fire()

> 发起宏观事件。

**签名：**

`View.fire(eventName: string, data?: any): View`

**可用版本：**`1.6.2+`

**入参：**

* `eventName: string` - 事件名称。
* `data?: any` - 事件关联数据 。

**返回：**

`window.View` 以供开发者链式调用。

**调用举例：**

```javascript
/**
 * 监听 "myEvent" 事件
 */
View.on("myEvent", function(e){
    console.log(e.data["key2"]);
});

/**
 * 触发事件："myEvent"，并携带自定义数据
 */
View.fire("myEvent", {
    "key1": "value1",
    "key2": 123,
    "key3": true
});

// 控制台异步输出 123
```

## static SWITCHTYPE\_HISTORYFORWARD

> 视图切换方式：浏览器前进。只读。

**签名：**

`View.SWITCHTYPE_HISTORYFORWARD: string` 

**可用版本：**`1.6.2+`

## static SWITCHTYPE\_HISTORYBACK

> 视图切换方式：浏览器后退。只读。

**签名：**

`View.SWITCHTYPE_HISTORYBACK: string` 

**可用版本：**`1.6.2+`

## static SWITCHTYPE\_VIEWNAV

> 视图切换方式：“压入堆栈” 式前进。只读。

**签名：**

`View.SWITCHTYPE_VIEWNAV: string` 

**可用版本：**`1.6.2+`

## static SWITCHTYPE\_VIEWCHANGE

> 视图切换方式：“替换栈顶” 式前进。只读。

**签名：**

`View.SWITCHTYPE_VIEWCHANGE: string` 

**可用版本：**`1.6.2+`

## static SWITCHTRIGGER\_APP

> 视图跳转动作触发来源：应用程序。只读。

**签名：**

`View.SWITCHTRIGGER_APP: string` 

**可用版本：**`1.6.2+`

## static SWITCHTRIGGER\_NAVIGATOR

> 视图跳转动作触发来源：浏览器。只读。

**签名：**

`View.SWITCHTRIGGER_NAVIGATOR: string` 

**可用版本：**`1.6.2+`

## id

> 获取视图的ID。只读。

**签名：**

`viewInstance.id: string` 

**可用版本：**`1.6.2+`

**返回：**

视图的ID。

## namespace

> 获取视图隶属的命名空间。只读。

**签名：**

`viewInstance.namespace: string` 

**可用版本：**`1.6.2+`

**返回：**

视图隶属的命名空间。

{% hint style="info" %}
除非另外声明，否则视图的命名空间将默认为：`default` 。
{% endhint %}

## logger

> 获取视图内置的日志句柄。只读。

**签名：**

`viewInstance.logger:` [`View.Logger`](/view.logger) 

**可用版本：**`1.6.2+`

**返回：**

视图内置的日志数据句柄。

## config

> 获取视图内置的配置集合。只读。

**签名：**

`viewInstance.config:` [`ViewConfigurationSet`](/viewconfigurationset) 

**可用版本：**`1.6.2+`

**返回：**

视图内置的配置集合。

## context

> 获取视图内置的数据存取上下文。只读。

**签名：**

`viewInstance.context:` [`ViewContext`](/viewcontext) 

**可用版本：**`1.6.2+`

**返回：**

视图内置的数据存取上下文。

## getId()

> 获取视图的ID，等同于 `id` 属性。

**签名：**

`viewInstance.getId(): string` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

视图的ID。

## getNamespace()

> 获取视图隶属的命名空间，等同于 `namespace` 属性。

**签名：**

`viewInstance.getNamespace(): string` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

视图隶属的命名空间。

{% hint style="info" %}
除非另外声明，否则视图的命名空间将默认为：`default` 。
{% endhint %}

## getContext()

> 获取视图内置的数据存取上下文，等同于 `context` 属性。

**签名：**

`viewInstance.getContext():` [`ViewContext`](/viewcontext) 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

视图内置的数据存取上下文。

## clearContext()

> 清空视图内置的数据存取上下文，移除上下文内的所有数据。

**签名：**

`viewInstance.clearContext(): View`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

视图实例本身，以供开发者链式调用。

## getDomElement()

> 获取视图的 DOM 骨架元素。

**签名：**

`viewInstance.getDomElement(): HTMLElement`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

视图的 DOM 骨架元素。

## getName()

> 获取视图的名称。视图名称，通过在视图的 DOM 骨架元素上声明 `data-view-name` 属性完成声明。\
> 该方法向后兼容 `data-view-group` 属性。

**签名：**

`viewInstance.getName(): string | null`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

视图在 DOM 骨架上声明的名称。

## ~~getGroupName()~~

> 获取视图隶属的群组名称。视图群组名称，通过在视图的 DOM 骨架元素上声明 `data-view-group` 属性完成声明。\
> 该方法，以及 `data-view-group` 属性已废弃，请使用 `getName()` 方法和 `data-view-name` 属性。

**签名：**

`viewInstance.getGroupName(): string | null`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

视图隶属的群组名称。

## find()

> 在视图的 DOM 骨架元素内部查找匹配给定选择器的 DOM 元素。

**签名：**

`viewInstance.find(selector: string): HTMLElement | null`

**可用版本：**`1.6.2+`

**入参：**

* `selector: string` - css 选择器

**返回：**

视图内匹配的 DOM 元素。如果没有元素与给定的选择器相匹配，则返回 `null` 。

## findAll()

> 在视图的 DOM 骨架元素内部查找匹配给定选择器的 DOM 元素集合。

**签名：**

`viewInstance.findAll(selector: string): NodeList`

**可用版本：**`1.6.2+`

**入参：**

* `selector: string` - css 选择器

**返回：**

视图内匹配的 DOM 元素列表。

## setLayoutAction()

> 设置视图的布局动作。

**签名：**

`viewInstance.setLayoutAction(action: Function): View`

**可用版本：**`1.6.2+`

**入参：**

* `action: Function` - 布局动作

**返回：**

视图实例本身，以供开发者链式调用。

**调用举例：**

```javascript
var view = View.ofId("myView");

var headerObj = view.find("header"),
    bodyObj = view.find(".body");

/**
 * 设置布局动作：
 * 主内容高度 = 总高度 - 头部高度
 */
view.setLayoutAction(function(){
    /* 布局空间的高度 */
    var availableHeight = View.layout.getLayoutHeight();
    
    bodyObj.style.height = (availableHeight - headerObj.offsetHeight) + "px";
});
```

## getLayoutAction()

> 获取设置的视图布局动作。

**签名：**

`viewInstance.getLayoutAction(): Function`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

设置的视图布局动作。

{% hint style="info" %}
如果开发者没有设置布局动作，该方法将返回一个空方法。
{% endhint %}

## hasParameter()

> 判断视图参数中是否含有给定键名的参数。

**签名：**

`viewInstance.hasParameter(paramName: string): boolean`

**可用版本：**`1.6.2+`

**入参：**

* `paramName: string` - 参数的键名。区分大小写。

**返回：**

`true` - 视图参数中有给定键名的参数；`false` - 没有给定键名的参数。

{% hint style="info" %}
方法应该在视图是活动状态时调用，否则永远会得到 `false` 。因为视图参数将会在视图离开被重置。
{% endhint %}

## getParameter()

> 获取视图参数。

**签名：**

`viewInstance.getParameter(paramName?: string): any | null`

**可用版本：**`1.6.2+`

**入参：**

* `paramName?: string` - 参数的键名，可选。如果没有指定该参数，将返回所有视图参数构成的集合。区分大小写。

**返回：**

视图参数中匹配给定键名的参数取值。如果没有指定参数键名，则返回整个参数集合。如果视图跳转时没有指定视图参数，则返回 `null` 。

{% hint style="warning" %}
视图离开后，`getParameter()` 方法仍然可以获取到最后一次传入的参数。但重新进入时，再次调用将获取到新传入的参数。
{% endhint %}

## setIfAutoSaveParamsToContext()

> 设置是否自动保存视图参数至视图上下文。如果赋值为 `true` ，则视图每次进入时，如果视图参数不为空且为一个有效对象，View\.js 将自动使用名称形如：“\_autosavedparams\_qx4esdf74k” 的键将其存储至视图上下文中。

**签名：**

`viewInstance.setIfAutoSaveParamsToContext(autoSave?: boolean): View`

**可用版本：**`1.6.3+`

**入参：**

* `autoSave?: boolean` - 是否自动保存，可选。默认为：`true` 。

**返回：**

视图实例本身，以供开发者链式调用 。

{% hint style="info" %}
视图参数在每次进入视图时均会被重置。通过自动保存至上下文，结合 `view.seekParameter()` 方法，开发者可以在没有收到入参时，继续使用最后一次收到的参数。

从 `1.7.0` 版本开始，开发者也可以在调用 `view.seekParmeter()` 方法时，指定 “不存上下文中检索” 。
{% endhint %}

{% hint style="warning" %}
自动保存动作，仅当视图参数是一个不为 `null` 的有效对象时才执行。一经保存，将覆盖既有取值。
{% endhint %}

## getIfAutoSaveParamsToContext()

> 判断该视图是否自动保存视图参数至视图上下文。

**签名：**

`viewInstance.getIfAutoSaveParamsToContext(): boolean`

**可用版本：**`1.6.3+`

**入参：**

无。

**返回：**

`true` - 自动保存；`false` - 不自动保存。

## setDataFetchAction()

> 设置视图渲染所需要的数据的获取方法。该方法用于辅助实现视图进入时的完整性体验。

**签名：**

`viewInstance.setDataFetchAction(action:` [`ViewDataFetchAction`](/lei-xing/viewdatafetchaction)`): View`

**可用版本：**`1.7.0+`

**入参：**

无。

**返回：**

视图实例本身，以供开发者链式调用 。

## getDataFetchAction()

> 获取设置的视图渲染所需要的数据的获取方法。

**签名：**

`viewInstance.getDataFetchAction():` [`ViewDataFetchAction`](/lei-xing/viewdatafetchaction)

**可用版本：**`1.7.0+`

**入参：**

无。

**返回：**

设置的视图渲染所需要的数据的获取方法。如果开发者没有设置，则返回 `null` 。

## fetchData()

> 获取视图渲染所需要的数据。

**签名：**

`viewInstance.fetchData(): Promise | Thenable`

**可用版本：**`1.7.0+`

**入参：**

无。

**返回：**

`Promise` 实例（浏览器支持 `Promise`）; `Thenable` - 包含有 then 方法的对象（浏览器不支持 `Promise`）

## seekParameter()

> 搜寻视图收到的参数。

**签名：**

`viewInstance.seekParameter(paramName: string, ifRetrieveFromContext?: boolean): any | null`

**可用版本：**`1.6.2+`

**入参：**

* `paramName: string` - 参数的键名。
* `ifRetrieveFromContext?: boolean` - 是否从上下文中检索参数（仅当自动保存视图参数至视图上下文时有效），可选。默认为：`true` 。\
  该参数是 `1.7.0` 新增的。

**返回：**

视图参数，或视图选项，或地址栏 queryString 中匹配给定键名的参数取值，或最后一次收到的、自动保存至视图上下文中的视图参数 。

{% hint style="info" %}
该方法如下方式工作：

1. 尝试从 视图参数 中检索同名参数，有则返回，没有则执行步骤2；
2. 尝试从 视图选项 中检索同名参数，有则返回，没有则执行步骤3；
3. 尝试从 queryString 中 检索同名参数，有则返回对应的取值，没有则执行步骤4；
4. 如果 `ifRetrieveFromContext` 为 `true`，尝试从 自动保存至视图上下文的视图参数 中检索同名参数，没有则返回 `null`。

> 步骤 4 是 `1.6.3` 新增的。
> {% endhint %}

**调用举例：**

{% tabs %}
{% tab title="action.js" %}

```javascript
/**
 * 从 商品详情 页面跳转至 确认订单 界面
 *
 * 跳转前，页面的URL为：http://domain/main.html?id=G01#goods-detail
 */
View.navTo("confirm-order", {
    params: {
        inventory: 100 /* 库存量：100 */
    },
    options: {
        count: 1 /* 购买个数：1 */
    }
});
```

{% endtab %}

{% tab title="init.js" %}

```javascript
var view = View.ofId("confirm-order");

/**
 * 跳转后，页面的URL为 http://domain/main.html?id=G01#confirm-order!count=1
 */
view.on("enter", function(){
    console.log(view.seekParameter("id")); // -> "G01"
    console.log(view.seekParameter("inventory")); // -> 100
    console.log(view.seekParameter("count")); // -> "1"
});
```

{% endtab %}
{% endtabs %}

## isReady()

> 判断视图是否已经就绪。

**签名：**

`viewInstance.isReady(): boolean`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

`true` - 视图已经就绪；`false` - 视图尚未就绪 。

{% hint style="info" %}
视图在第一次进入时，`enter` 事件触发前变为就绪状态。关联事件名称为：`ready` 。
{% endhint %}

## isActive()

> 判断视图是否处于活动状态，亦即视图当前是否为活动视图。

**签名：**

`viewInstance.isActive(): boolean`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

`true` - 视图处于活动状态；`false` - 视图没有处于活动状态 。

## isDefault()

> 判断视图是否是默认视图。

**签名：**

`viewInstance.isDefault(): boolean`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

`true` - 视图是默认视图；`false` - 视图不是默认视图 。

## isDirectlyAccessible()

> 判断视图是否可以直接访问。

**签名：**

`viewInstance.isDirectlyAccessible(): boolean`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

`true` - 视图可以直接访问；`false` - 视图不可以直接访问 。

## setAsDirectlyAccessible()

> 设置视图是否可以直接访问。

**签名：**

`viewInstance.setDirectlyAccessible(isDirectlyAccessible?: boolean): View`

**可用版本：**`1.6.2+`

**入参：**

* `isDirectlyAccessible?: boolean` - 是否可以直接访问，可选。默认为：`true` 。

**返回：**

视图本身，以供开发者链式调用。

## setTitle()

> 设置视图标题。当视图变为活动状态，View\.js 将自动使用设置的视图标题更新浏览器标题。

**签名：**

`viewInstance.setTitle(title: string): View`

**可用版本：**`1.6.2+`

**入参：**

* `title: string` - 视图标题。

**返回：**

视图本身，以供开发者链式调用。

{% hint style="info" %}
如果活动视图没有设置视图标题，View\.js 将使用初始化阶段捕获的浏览器标题更新浏览器标题。
{% endhint %}

## getTitle()

> 获取设置的视图标题。

**签名：**

`viewInstance.getTitle(): string | null`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

设置的视图标题。如果尚未设置过标题，则返回 `null` 。

## setFallbackViewId()

> 设置回退视图的ID（及命名空间）。

**签名：**

`viewInstance.setFallbackViewId(viewId: string, viewNamespace?: string): View`

**可用版本：**`1.6.2+`

**入参：**

* `viewId: string` - 要回退显示的视图的ID。
* `viewNamespace?: string` - 要回退显示的视图隶属的命名空间，可选。默认为： `default` 。

**返回：**

视图本身，以供开发者链式调用。

## getFallbackView()

> 获取最终要回退显示的视图。

**签名：**

`viewInstance.getFallbackViewId(): View`

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

最终回退显示的视图。

## on()

> 添加视图实例事件监听器。预置的实例事件包括：\
> 1\. `leave` - 离开视图（异步触发）\
> 2\. `beforeenter` - 即将进入视图（同步触发）\
> 3\. `ready` - 视图就绪（同步触发）\
> 4\. `enter` - 进入视图（同步触发）\
> 5\. `afterenter` - 视图已经进入（同步触发）\
> \
> 开发者也可以使用该方法监听自定义事件。

**签名：**

`viewInstance.on(eventName: string, handle:` [`ViewEventListener`](/lei-xing/vieweventlistener)`): View`

**可用版本：**`1.6.2+`

**入参：**

* `eventName: string` - 事件名称。
* `handle:` [`ViewEventListener`](/lei-xing/vieweventlistener) - 事件监听器 。

**返回：**

当前视图实例，以供开发者链式调用。

**调用举例：**

```javascript
var view = View.ofId("myView");

/**
 * 监听预置事件
 */
myView.on("enter", function(e){
    var id = view.seekParameter("id");
    // doSth(id);
});

/**
 * 监听自定义事件
 */
viwe.on("myEvent", function(e){
    var data = e.data;
    // doSth(data);
});
```

## off()

> 移除视图实例事件监听器。预置的实例事件包括：\
> 1\. `leave` - 离开视图（异步触发）\
> 2\. `beforeenter` - 即将进入视图（同步触发）\
> 3\. `ready` - 视图就绪（同步触发）\
> 4\. `enter` - 进入视图（同步触发）\
> 5\. `afterenter` - 视图已经进入（同步触发）

**签名：**

`viewInstance.off(eventName: string, handle:` [`ViewEventListener`](/lei-xing/vieweventlistener)`): View`

**可用版本：**`1.6.2+`

**入参：**

* `eventName: string` - 事件名称。
* `handle:` [`ViewEventListener`](/lei-xing/vieweventlistener) - 事件监听器 。

**返回：**

当前视图实例，以供开发者链式调用。

## fire()

> 发起视图实例事件。

**签名：**

`viewInstance.fire(eventName: string, data?: any): View`

**可用版本：**`1.6.2+`

**入参：**

* `eventName: string` - 事件名称。
* `data?: any` - 事件关联数据 。

**返回：**

当前视图实例，以供开发者链式调用。

**调用举例：**

```javascript
var view = View.ofId("myView");

/**
 * 监听 "myEvent" 事件
 */
view.on("myEvent", function(e){
    console.log(e.data["key2"]);
});

/**
 * 触发事件："myEvent"，并携带自定义数据
 */
view.fire("myEvent", {
    "key1": "value1",
    "key2": 123,
    "key3": true
});

// 控制台异步输出 123
```

## getLatestEventData()

> 获取给定名称的事件最后一次触发时携带的数据。

**签名：**

`viewInstance.getLatestEventData(eventName: string): any`

**可用版本：**`1.6.2+`

**入参：**

* `eventName: string` - 事件名称。

**返回：**

事件最后一次触发时所携带的数据。

**调用举例：**

```javascript
var view = View.ofId("myView");

/**
 * 触发事件："myEvent"，并携带自定义数据
 */
view.fire("myEvent", {
    "key1": "value1",
    "key2": 123,
    "key3": true
});

// -> 'value1'
console.log(view.getLatestEventData("myEvent").key1);
```

## addTimer()

> 添加视图活动时，需要周期性执行的定时器。

**签名：**

`viewInstance.addTimer(timerName: string, timerHandle: Function, interval: Number): View`

**可用版本：**`1.7.0+`

**入参：**

* `timerName: string` - 定时器名称，不区分大小写。
* `timerHandle: Function` - 定时器处理句柄。
* `interval: Number` - 定时器周期性执行间隔。单位：毫秒。

**返回：**

视图本身，以供开发者链式调用。

{% hint style="info" %}
通过该方法创建的定时器，将在视图进入时自动开始执行，在视图离开时，自动停止。\
执行该方法时，视图处于活动状态，则定时器立即开始执行。
{% endhint %}

## startTimer()

> 启动视图定时器。

**签名：**

`viewInstance.startTimer(timerName: string): boolean`

**可用版本：**`1.7.0+`

**入参：**

* `timerName: string` - 定时器名称，不区分大小写。

**返回：**

`true` - 定时器启动成功；`false` - 定时器启动失败（定时器不存在，或已经启动）。

## startAllTimers()

> 启动视图内的所有定时器。

**签名：**

`viewInstance.startAllTimers(): View`

**可用版本：**`1.7.0+`

**入参：**

无。

**返回：**

视图本身，以供开发者链式调用。

## stopTimer()

> 停止视图定时器。

**签名：**

`viewInstance.stopTimer(timerName: string): boolean`

**可用版本：**`1.7.0+`

**入参：**

* `timerName: string` - 定时器名称，不区分大小写。

**返回：**

`true` - 定时器停止成功；`false` - 定时器停止失败（定时器不存在，或尚未启动）。

## stopAllTimers()

> 停止视图内的所有定时器。

**签名：**

`viewInstance.stopAllTimers(): View`

**可用版本：**`1.7.0+`

**入参：**

无。

**返回：**

视图本身，以供开发者链式调用。


# ViewContext

视图上下文，用于存取数据，避免变量污染。

## has()

> 判断上下文中是否含有给定键名的数据。

**签名：**

`viewContextInstance.has(name: string): boolean` 

**可用版本：**`1.6.2+`

**入参：**

* `name: string` - 数据在上下文中的唯一键名。

**返回：**

`true` - 上下文中含有给定键名的数据。否则 `false`。

## set()

> 向上下文中添加或更新数据。如果给定键名的数据尚不存在，则添加数据，否则覆盖键名对应的既有数据。

**签名：**

`viewContextInstance.set(name: string, value: any): ViewContext` 

**可用版本：**`1.6.2+`

**入参：**

* `name: string` - 数据在上下文中的唯一键名。
* `value: any` - 要设置的数据。

**返回：**

实例本身，以供开发者链式调用API。

## get()

> 从上下文中获取给定键名对应的数据。如果键名在上下文中并不存在，则返回 `undefined`。

**签名：**

`viewContextInstance.get(name: string): any | undefined` 

**可用版本：**`1.6.2+`

**入参：**

* `name: string` - 数据在上下文中的唯一键名。

**返回：**

键名对应的数据。如果数据尚不存在，则返回 `undefined`。

## remove()

> 从上下文中移除给定键名对应的数据，并返回被移除的数据。如果数据尚不存在，则返回 `undefined`。

**签名：**

`viewContextInstance.remove(name: string): any | undefined` 

**可用版本：**`1.6.2+`

**入参：**

* `name: string` - 数据在上下文中的唯一键名。

**返回：**

键名对应的数据。如果数据尚不存在，则返回 `undefined`。

## clear()

> 清空上下文中，移除上下文中的所有数据。

**签名：**

`viewContextInstance.clear(): ViewContext` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

实例本身，以供开发者链式调用API。

## listKeys()

> 列举上下文中的所有键名。

**签名：**

`viewContextInstance.listKeys(): string[]` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

上下文中所有键名组成的数组。

## size()

> 获取上下文中存放的数据个数。

**签名：**

`viewContextInstance.size(): number` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

上下文中存放的数据个数。


# ViewConfiguration

视图配置 - 单个配置项。

## getName()

> 获取配置项的名称。

**签名：**

`viewConfigInstance.getName(): string` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

配置项名称。

## getValue()

> 获取配置项的取值。

**签名：**

`viewConfigInstance.getValue(dftValue?: any): any | undefined` 

**可用版本：**`1.6.2+`

**入参：**

* `dftValue?: any` - 配置项没有赋值时，将要使用的默认值。

**返回：**

配置项取值。如果配置项尚未赋值，且没有提供默认值，则返回 `undefined`，否则返回方法中指定的默认值。

## setValue()

> 设置配置项的取值。

**签名：**

`viewConfigInstance.setValue(value: any, ifOverride?: boolean): ViewConfiguration` 

**可用版本：**`1.6.2+`

**入参：**

* `value: any` - 配置项取值。
* `ifOverride: boolean` - 如果配置项已经被赋值，是否覆盖既有取值。默认为：`false`。

**返回：**

实例本身，以供开发者链式调用。

## getApplication()

> 获取设置的配置项的应用动作（通过 `apply()` 方法应用配置时所执行的动作）。

**签名：**

`viewConfigInstance.getApplication(): ViewConfigurationApplication | undefined` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

设置的应用动作。如果没有设置，则返回 `undefined`。

## apply()

> 应用配置，执行通过 `setApplication()` 方法设置的应用动作。

**签名：**

`viewConfigInstance.apply(): ViewConfiguration` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

实例本身，以供开发者链式调用。

{% hint style="info" %}
即使没有设置过应用动作，调用方法也不会报错，只是什么也不会发生。
{% endhint %}

## reflectToDom()

> 将配置反映到 DOM 中，以借助 CSS 响应配置，如：显示/隐藏元素等。此时，视图的 DOM 骨架上将会创建属性：`data-viewconfig_name=value` ，并赋值为配置项取值的字符串表达。其中 `name` 为配置项的名称。

**签名：**

`viewConfigInstance.reflectToDom(): ViewConfiguration` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

实例本身，以供开发者链式调用。


# ViewConfigurationSet

视图配置 - 配置项集合。

## has()

> 判断配置集合中是否含有给定名称的配置项。

**签名：**

`viewConfigSetInstance.has(name: string): boolean` 

**可用版本：**`1.6.2+`

**入参：**

* `name` - 配置项名称。

**返回：**

`true` - 集合含有给定名称的配置项。否则 `false`。

## get()

> 获取给定名称对应的配置项实例。如果实例尚不存在，则自动创建后返回。

**签名：**

`viewConfigSetInstance.get(name: string):` [`ViewConfiguration`](/viewconfiguration) 

**可用版本：**`1.6.2+`

**入参：**

* `name` - 配置项名称。

**返回：**

已经存在或新创建的配置项实例。

## applyAll()

> 应用集合中的所有配置（执行所有配置项的应用动作）。

**签名：**

`viewConfigSetInstance.applyAll(): ViewConfigurationSet` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

实例本身，以供开发者链式调用。

{% hint style="info" %}
应用动作将以异步方式进行。
{% endhint %}

## listAll()

> 列举集合中的所有配置项名称。

**签名：**

`viewConfigSetInstance.listAll(): string[]` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

所有配置项名称组成的数组。


# View\.layout

视图布局API

## getLayoutWidth()

> 获取视图可布局空间的宽度，单位：像素。\
> 宽度等于视图容器的宽度，减去视图容器的左右内边距。\
> 视图的内容展现不应该超过该宽度。

**签名：**

`View.layout.getLayoutWidth(): number` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

视图可布局空间的宽度，单位：像素。

## getLayoutHeight()

> 获取视图可布局空间的高度，单位：像素。\
> 宽度等于视图容器的高度，减去视图容器的上下内边距。\
> 视图的内容展现不应该超过该高度。

**签名：**

`View.layout.getLayoutHeight(): number` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

获取视图可布局空间的高度，单位：像素。

## getBrowserWidth()

> 获取浏览器宽度，单位：像素。

**签名：**

`View.layout.getBrowserWidth(): number` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

浏览器宽度，单位：像素。

## getBrowserHeight()

> 获取浏览器高度，单位：像素。

**签名：**

`View.layout.getBrowserHeight(): number` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

浏览器高度，单位：像素。

## isLayoutPortrait()

> 判断布局空间是否为 potrait 模式：宽度小于等于高度。

**签名：**

`View.layout.isLayoutPortrait(): boolean` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

布局空间是否为 potrait 模式。

## isLayoutLandscape()

> 判断布局空间是否为 landscape 模式：宽度大于高度。

**签名：**

`View.layout.isLayoutLandscape(): boolean` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

布局空间是否为 landscape 模式。

## isBrowserPortrait()

> 判断浏览器是否为 potrait 模式：宽度小于等于高度。

**签名：**

`View.layout.isBrowserPortrait(): boolean` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

浏览器是否为 portrait 模式。

## isBrowserLandscape()

> 判断浏览器是否为 landscape 模式：宽度大于高度。

**签名：**

`View.layout.isBrowserLandscape(): boolean` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

浏览器是否为 landscape 模式。

## getLayoutWidthHeightRatio()

> 获取布局空间的宽高比。

**签名：**

`View.layout.getLayoutWidthHeightRatio(): number` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

布局空间的宽高比。

## getBrowserWidthHeightRatio()

> 获取浏览器的宽高比。

**签名：**

`View.layout.getBrowserWidthHeightRatio(): number` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

浏览器的宽高比。

## getExpectedWidthHeightRatio()

> 获取设置的、在PC上横屏浏览应用时，页面布局空间的宽高比。\
> PC 上横屏浏览时，View\.js 默认将页面以 320 \* *568* 分辨率（iPhone5 的分辨率）渲染。此时，视图容器的高度为浏览器窗口的高度，宽度为 `高度 / 568 * 320` ，并且水平居中。\
> 开发者可以使用 `data-view-whr` 属性 和 `View.layout.setExpectedWidthHeightRatio()` 设置为其它分辨率。

**签名：**

`View.layout.getExpectedWidthHeightRatio(): number` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

PC上横屏浏览应用时，页面布局空间的宽高比。

## setExpectedWidthHeightRatio()

> 设置在PC上横屏浏览应用时，页面布局空间的宽高比。\
> PC 上横屏浏览时，View\.js 默认将页面以 320 \* *568* 分辨率（iPhone5 的分辨率）渲染。此时，视图容器的高度为浏览器窗口的高度，宽度为 `高度 / 568 * 320` ，并且水平居中。\
> 开发者可以使用 `data-view-whr` 属性 和 `View.layout.setExpectedWidthHeightRatio()` 设置为其它分辨率。

**签名：**

`View.layout.setExpectedWidthHeightRatio(): View.layout` 

**可用版本：**`1.6.2+`

**入参：**

无。

**返回：**

`View.layout` - 以供开发者链式调用API。

## init()

> 设置布局配置并初始化。

**签名：**

`View.layout.init(ops:` [`ViewLayoutInitOptions`](/lei-xing/viewlayoutinitctrl)`): View.layout` 

**可用版本：**`1.6.2+`

**入参：**

* `ops` - 配置选项。可选。

**返回：**

`View.layout` - 以供开发者链式调用API。

## doLayout()

> 根据当前的浏览模式和状态执行一次布局动作。

**签名：**

`View.layout.doLayout(async?: boolean): View.layout` 

**可用版本：**`1.6.2+`

**入参：**

* `async` - 是否异步执行。可选，默认为：`true`。

**返回：**

`View.layout` - 以供开发者链式调用API。

## addLayoutChangeListener()

> 添加 “布局空间发生变化” 监听器。

**签名：**

`View.layout.addLayoutChangeListner(listener:` [`ViewLayoutChangeLisener`](/lei-xing/viewlayoutchangelistener)`): View.layout` 

**可用版本：**`1.6.2+`

**入参：**

* `listener` - 监听器。

**返回：**

`View.layout` - 以供开发者链式调用API。

## removeLayoutChangeListener()

> 移除 “布局空间发生变化” 监听器。

**签名：**

`View.layout.removeLayoutChangeListner(listener:` [`ViewLayoutChangeLisener`](/lei-xing/viewlayoutchangelistener)`): View.layout` 

**可用版本：**`1.6.2+`

**入参：**

* `listener` - 监听器。

**返回：**

`View.layout` - 以供开发者链式调用API。


# View\.Logger

日志工具类，用于格式化输出信息至控制台。

## static ofName()

> 获取给定名称对应的实例。如果实例尚不存在，则自动创建后返回。

**签名：**

`View.Logger.ofName(name: string): View.Logger` 

**可用版本：**`1.6.2+`

**入参：**

* `name: string` - 实例名称。

**返回：**

已经存在或新创建的实例。

## debug()

> 以 debug 级别输出日志信息。

**签名：**

`loggerInstance.debug(tmpl: string, ...params): View.Logger` 

**可用版本：**`1.6.2+`

**入参：**

* `tmpl: string` - 模板字符串。
* `...params: any` - 填充模板字符串中占位符的数据。

**返回：**

空。

**调用举例：**

```javascript
var logger = View.Logger.ofName("myLogger");

var tmpl = "hello, {}";

// -> '1215 20:32:35 [myLogger]: hello, world'
logger.debug(tmpl, "world");

// -> '1215 20:32:36 [myLogger]: hello, [{"foo":"foo"}]'
logger.debug(tmpl, [{foo: "foo"}]);

// -> '1215 20:34:57 [myLogger]: 1-12, 2-true, 3-{}'
logger.debug("1-{}, 2-{}, 3-\\{}", 12, true, "str");
```

## log()

> 以 info 级别输出日志信息。

**签名：**

`loggerInstance.log(tmpl: string, ...params): View.Logger` 

**可用版本：**`1.6.2+`

**入参：**

* `tmpl: string` - 模板字符串。
* `...params: any` - 填充模板字符串中占位符的数据。

**返回：**

空。

## info()

> 以 info 级别输出日志信息。

**签名：**

`loggerInstance.info(tmpl: string, ...params): View.Logger` 

**可用版本：**`1.6.2+`

**入参：**

* `tmpl: string` - 模板字符串。
* `...params: any` - 填充模板字符串中占位符的数据。

**返回：**

空。

## warn()

> 以 warn 级别输出日志信息。

**签名：**

`loggerInstance.warn(tmpl: string, ...params): View.Logger` 

**可用版本：**`1.6.2+`

**入参：**

* `tmpl: string` - 模板字符串。
* `...params: any` - 填充模板字符串中占位符的数据。

**返回：**

空。

## error()

> 以 error 级别输出日志信息。

**签名：**

`loggerInstance.error(tmpl: string, ...params): View.Logger` 

**可用版本：**`1.6.2+`

**入参：**

* `tmpl: string` - 模板字符串。
* `...params: any` - 填充模板字符串中占位符的数据。

**返回：**

空。


# ViewLayoutInitOptions

视图布局初始化控制选项

## 可选选项

* `autoReLayoutWhenResize: boolean`\
  当布局空间发生变化时，是否自动重新布局。\
  默认值：`true`。
* `layoutAsMobilePortrait: Function`\
  当使用 移动设备 在 竖屏模式 下浏览应用时，需要执行的场景化布局动作。\
  默认动作：视图容器的宽度赋值为浏览器宽度，高度赋值为浏览器高度。
* `layoutAsMobileLandscape: Function`\
  当使用 移动设备 在 横屏模式 下浏览应用时，需要执行的场景化布局动作。\
  默认动作：视图容器的宽度赋值为浏览器宽度，高度赋值为浏览器高度。
* `layoutAsTabletPortrait: Function`\
  当使用 平板设备 在 竖屏模式 下浏览应用时，需要执行的场景化布局动作。\
  默认动作：视图容器的宽度赋值为浏览器宽度，高度赋值为浏览器高度。
* `layoutAsTabletLandscape: Function`\
  当使用 平板设备 在 横屏模式 下浏览应用时，需要执行的场景化布局动作。\
  默认动作：视图容器的宽度赋值为浏览器宽度，高度赋值为浏览器高度。
* `layoutAsPcPortrait: Function`\
  当使用 PC设备 在 类竖屏模式（窗口宽度小于等于高度）下浏览应用时，需要执行的场景化布局动作。\
  默认动作：视图容器的宽度赋值为浏览器宽度，高度赋值为浏览器高度。
* `layoutAsPcLandscape: Function`\
  当使用 PC设备 在 类横屏模式（窗口宽度大于高度）下浏览应用时，需要执行的场景化布局动作。\
  默认动作：视图容器的高度赋值为浏览器高度，宽度赋值为 `高度 / 宽高比`，其中 `宽高比` 通过 `View.layout.setExpectedWidthHeightRatio()` 设置。默认宽高比为 `320 / 568`。


# ViewLayoutChangeListener

布局空间变化监听器

## 签名

`(layoutWidth?: number, layoutHeight?: number, browserWidth?: number, browserHeight?: number) => void`

## 入参

1. `layoutWidth: number` - 新的布局空间的宽度
2. `layoutHeight: number` - 新的布局空间的高度
3. `browserWidth: number` - 新的浏览器的宽度
4. `browserHeight: number` - 新的浏览器的高度

## 返回

无。


# ViewConfigurationApplication

视图配置项的应用动作

## 签名

`(value: any) => void`

## 入参

1. `value: any` - 视图配置项的取值

## 返回

无。


# ViewState

视图浏览信息

## 属性

* `viewId: string` - 视图ID
* `viewNamespace: string` - 视图隶属的命名空间
* `sn: string` - 浏览时间的36进制
* `options: Object | null` - 浏览视图关联的视图选项


# ViewSwitchAnimation

视图跳转动画执行器

## 签名

`(info:` [`ViewSwitchInfo`](/lei-xing/viewswitchinfo)`) => void`

## 入参

1. `info:` [`ViewSwitchInfo`](/lei-xing/viewswitchinfo) - 跳转信息

## 返回

无。


# ViewSwitchInfo

视图跳转信息

## 属性

* `srcElement: HTMLElement | null` - 源视图的 DOM 骨架。如果视图是直接访问进入的，则为 `null`
* `targetElement: HTMLElement` - 目标视图的 DOM 骨架
* `type:` [`ViewSwitchType`](/lei-xing/viewswitchtype) - 视图跳转的方式
* `trigger:` [`ViewSwitchTrigger`](/lei-xing/viewswtichtrigger) - 视图跳转的触发来源
* `render: Function` - 界面渲染动作

{% hint style="warning" %}
界面渲染动作，由 View\.js 提供，包含了活动视图的切换和关联事件的触发等，开发者需要根据动画的播放效果，在恰当的时机，例如：动画播放完毕后，执行该方法。
{% endhint %}


# ViewSwitchType

视图跳转方式

## 枚举值

* `View.SWITCHTYPE_HISTORYFORWARD: string` - 浏览器前进
* `View.SWITCHTYPE_HISTORYBACK: string` - 浏览器后退
* `View.SWITCHTYPE_VIEWNAV: string` - 压入堆栈
* `View.SWITCHTYPE_VIEWCHANGE: string` - 替换栈顶


# ViewSwtichTrigger

视图跳转动作的触发来源

## 枚举值

* `View.SWITCHTRIGGER_APP: string` - 应用程序
* `View.SWITCHTRIGGER_NAVIGATOR: string` - 浏览器


# ViewSwitchCtrl

视图跳转控制

## 可选选项

* `params: Object | null`\
  视图参数集合。\
  默认值：`null`。
* `options: Object | null`\
  视图选项集合。\
  默认值：`null`。
* `withAnimation: boolean`\
  跳转动作是否执行跳转动画。\
  默认值：`true` 。


# ViewBackForwardCtrl

视图前进或后退跳转控制

## 可选选项

* `params: Object | null`\
  视图参数集合。\
  默认值：`null`。


# ViewEvent

事件

## 公共属性

* `type: string` - 事件类型（亦即，事件名称），例如：`enter` - 视图进入
* `timestamp: string` - 事件触发时间的时间戳
* `data: any`- 事件关联数据

## 宏观 beforechange 事件

**事件含义**

活动视图即将切换。

**发生对象**

`window.view`

**触发方式**

同步触发。

**关联数据**

[`ViewSwitchEventData`](/lei-xing/viewswitcheventdata)

## 宏观 change 事件

**事件含义**

活动视图正在切换。

**发生对象**

`window.view`

**触发方式**

同步触发。

**关联数据**

[`ViewSwitchEventData`](/lei-xing/viewswitcheventdata)

## 宏观 afterchange 事件

**事件含义**

活动视图切换完成。

**发生对象**

`window.view`

**触发方式**

异步触发。

**关联数据**

[`ViewSwitchEventData`](/lei-xing/viewswitcheventdata)

## 实例 beforeenter 事件

**事件含义**

视图即将进入。

**发生对象**

视图实例。

**触发方式**

同步触发。

**关联数据**

[`ViewInstanceEnterEventData`](/lei-xing/viewentereventdata)

## 实例 ready 事件

**事件含义**

视图就绪（第一次进入时触发）。

**发生对象**

视图实例。

**触发方式**

同步触发。

**关联数据**

[`ViewInstanceEnterEventData`](/lei-xing/viewentereventdata)

## 实例 enter 事件

**事件含义**

视图进入。

**发生对象**

视图实例。

**触发方式**

同步触发。

**关联数据**

[`ViewInstanceEnterEventData`](/lei-xing/viewentereventdata)

## 实例 afterenter 事件

**事件含义**

视图进入完成。

**发生对象**

视图实例。

**触发方式**

同步触发。

**关联数据**

[`ViewInstanceEnterEventData`](/lei-xing/viewentereventdata)

## 实例 leave 事件

**事件含义**

视图离开。

**发生对象**

视图实例。

**触发方式**

异步触发。

**关联数据**

[`ViewInstanceLeaveEventData`](/lei-xing/viewinstanceleaveeventdata)


# ViewEventListener

视图跳转事件监听器

## 签名

`(viewEvent:` [`ViewEvent`](/lei-xing/viewevent)`) => void`

## 入参

1. `viewEvent:` [`ViewEvent`](/lei-xing/viewevent) - 事件实例

## 返回

无。


# ViewSwitchEventData

视图跳转事件关联的数据

## 属性

* ~~*`currentView`*`: View | null`~~ 离开的视图。已废弃，建议使用 `sourceView`
* `sourceView: View | null` - 离开的视图
* `targetView: View` - 进入的视图
* `type:` [`ViewSwitchType`](/lei-xing/viewswitchtype) - 视图跳转的方式
* `trigger:` [`ViewSwitchTrigger`](/lei-xing/viewswtichtrigger) - 视图跳转的触发来源
* `params: Object | null` - 视图跳转携带的视图参数
* `options: Object | null` - 视图跳转携带的视图选项


# ViewInstanceEnterEventData

视图切换进入时相关事件关联的数据

## 属性

* `sourceView: View | null` - 离开的视图
* `type:` [`ViewSwitchType`](/lei-xing/viewswitchtype) - 视图跳转的方式
* `trigger:` [`ViewSwitchTrigger`](/lei-xing/viewswtichtrigger) - 视图跳转的触发来源
* `params: Object | null` - 视图跳转携带的视图参数
* `options: Object | null` - 视图跳转携带的视图选项


# ViewInstanceLeaveEventData

视图离开时，leave 事件关联的数据

## 属性

* `targetView: View` - 要进入的视图
* `type:` [`ViewSwitchType`](/lei-xing/viewswitchtype) - 视图跳转的方式
* `trigger:` [`ViewSwitchTrigger`](/lei-xing/viewswtichtrigger) - 视图跳转的触发来源
* `params: Object | null` - 视图跳转携带的视图参数
* `options: Object | null` - 视图跳转携带的视图选项


# ViewInitializer

View\.js 初始化触发器

## 签名

`(init: Function) => void`

## 入参

1. `init: Function` - 初始化动作执行句柄，由 View\.js 提供，由 开发者 在恰当时机执行。

{% hint style="warning" %}
如果 init 方法没有被执行，则 View\.js 将无法完成初始化。
{% endhint %}

## 返回

无。


# ViewInitializeTime

View\.js 的初始化时机

## 枚举值

* `'domready'` - DOM 就绪后触发。
* `'rightnow'` - 设置初始化触发器后立即触发。


# ViewSwitchInterceptor

视图跳转拦截器

## 签名

`(meta:` [`ViewSwitchEventData`](/lei-xing/viewswitcheventdata)`) => boolean`

## 入参

1. `meta:` [`ViewSwitchEventData`](/lei-xing/viewswitcheventdata) - 跳转动作的元数据描述。

## 返回

`true` - 继续执行下一个拦截器或执行视图跳转动作；`false` - 中止拦截器的继续执行或视图跳转动作。


# ViewDataFetchAction

视图渲染所需要的数据的获取方法。

## 签名

`(resolve: Function, reject: Function) => boolean`

## 入参

1. `resolve: Function` - 由 View\.js 提供，供开发者执行的，用于告知 View\.js 数据加载完成的方法。
2. `reject: Function` - 由 View\.js 提供，供开发者执行的，用于告知 View\.js 数据加载失败的方法。

## 返回

`true` - 继续执行下一个拦截器或执行视图跳转动作；`false` - 中止拦截器的继续执行或视图跳转动作。