# V3平台二次开发工具包
## 安装
    npm install v3-vdk --save
## 说明文档列表
- 窗体操作
- - [窗体跳转](#vdkpageredirecttoobject-object)
- - [参数获取](#vdkpagegetparamstring-key)
- - [渲染窗体到指定Dom元素](#vdkpageredirectToElementobject-object)
- - [渲染门户菜单](#vdkpagerenderFromPortalMenu-object)
- WebApi调用
- - [webApi调用](#vdkwebapiexecobject-object)
- 移动端Api
- - [视频拍摄](#vdkmobilemediacapturecapturevideofunction-successcallbackfunction-errorcallback)
- - [从手机相册选择文件](#vdkmobileimagepickergetpicturefunction-successcallbackfunction-errorcallbackobject-options)
- - [拍照](#vdkmobilecameragetpicturefunction-successcallbackfunction-errorcallbackobject-options)
- - [文件上传](#vdkmobilefiletransferfiletransferuploadstring-fileurlsfunction-callback)
- - [获取当前GPS地理位置](#vdkmobilegeolocationgetcurrentpositionfunction-successcallbackfunction-errorcallback)

---
## 窗体操作说明文档
### vdk.page.redirectTo(Object object)
关闭当前页面，跳转到指定的某个页面。
#### 参数
Object object
|属性|类型|默认值|必填|说明|
|-------|--------|-------|-------|-------|
|componentCode  |string     |   |是 |构件编号                   |
|windowCode     |string     |   |是 |窗体编号                   |
|context        |Object     |   |是 |上下文（vue实例）           |
|params         |Object     |   |否 |窗体入参                   |
|fail           |function   |   |否 |窗体跳转失败后的回调函数      |
##### object.context说明
context为vue实例对象，如在vue单文件组件中使用该接口，传递this即可
##### object.params说明
params为Object对象，其中key为入参编号，值为入参值。
##### object.fail说明
webapi调用失败后执行该函数，其参数值为Object对象。
#### 返回：void
#### 示例代码
```js
import vdk from 'v3-vdk';
vdk.page.redirectTo({
    componentCode : "componentCode1",
    windowCode : "windowCode1",
    context:this,
    params : {
        param1 : "test",
        param2 : 2,
        param3 : true
    },
    fail : function(){
        // do something
    }
});
```
---
### vdk.page.getParam(Object object)
获取窗体入参信息，key对应为窗体跳转时参数Object.object的key值。如果key不存在，将返回null。
#### 参数
Object object
|属性|类型|默认值|必填|说明|
|--------|-----------|---|---|---------|
|context |Object     |   |是 |上下文（vue实例）           |
|key     |Object     |   |是 |入参编码  |
##### object.context说明
context为vue实例对象，如在vue单文件组件中使用该接口，传递this即可
##### object.key说明
key对应为窗体入参编码
#### 返回：Any
#### 示例代码
```js
import vdk from 'v3-vdk';
let rs = vdk.page.getParam({
    context: this,
    key:"param1"
});//rs = 2
```
---
### vdk.page.redirectToElement(Object object)
渲染窗体到指定Dom元素里
#### 参数
Object object
|属性|类型|默认值|必填|说明|
|--------|-----------|---|---|---------|
|componentCode  |string         |   |是 |构件编号                   |
|windowCode     |string         |   |是 |窗体编号                   |
|el             |string/object  |   |是 |Dom元素对象或者id值                   |
|context        |Object         |   |否 |当前vue组件对象      |
|params         |Object         |   |否 |窗体入参                   |
|fail           |function       |   |否 |窗体打开失败后的回调函数      |
#### object.params说明
params为Object对象，其中key为入参编号，值为入参值。
#### object.fail说明
窗体打开失败后执行该函数。
#### object.context说明
当前vue组件对象
#### 返回：void
#### 示例代码
```js
import vdk from 'v3-vdk';
vdk.page.redirectToElement({
    componentCode : "componentCode1",
    windowCode : "windowCode1",
    context:this,
    el:'domId',
    params : {
        param1 : "test",
        param2 : 2,
        param3 : true
    },
    fail : function(){
        // do something
    }
});
```
---
### vdk.page.renderFromPortalMenu(Object object)
渲染门户菜单
#### 参数
Object object
|属性|类型|默认值|必填|说明|
|--------|-----------|---|---|---------|
|type           |string         |   |是 |打开方式可选值：1、homeTab（首页，默认值），2、modal（模态）                  |
|menuCode       |string         |   |是 |菜单编码                   |
|scope          |string         |   |否 |可选值：1、current（当前，默认值），2、parent（父级）                   |
|error          |function       |   |否 |打开失败方法      |
#### object.type说明
打开方式可选值：1、homeTab（首页，默认值），2、modal（模态）
#### object.menuCode说明
菜单编码 
#### object.scope
可选值：1、current（当前，默认值），2、parent（父级）
#### object.error说明
窗体打开失败后执行该函数。
#### 返回：void
#### 示例代码
```js
import vdk from 'v3-vdk';
vdk.page.renderFromPortalMenu({
    type : "homeTab",
    menuCode : "menuCode",
    scope:"parent",
    error : function(){
        // do something
    }
});
```
---
## webapi调用说明文档
### vdk.webapi.exec(Object object)
调用webapi。
#### 参数
Object object
|属性|类型|默认值|必填|说明|
|-------|--------|-------|-------|-------|
|apiCode        |string     |   |是 |webapi编号                 |
|componentCode  |string     |   |是 |构件编号                   |
|context        |Object     |   |是 |上下文（vue实例）           |
|params         |Object     |   |否 |webapi入参                 |
|success        |function   |   |否 |webapi调用成功后的回调函数   |
|fail           |function   |   |否 |webapi调用失败后的回调函数   |
##### object.context说明
context为vue实例对象，如在vue单文件组件中使用该接口，传递this即可
##### object.params说明
params为Object对象，其中key为webapi入参编号，值为webapi入参值。
##### object.success说明
webapi调用成功后执行该函数，其参数值为Object对象，其中key为webapi的输出参数编号，值为webapi输出参数值。
##### object.fail说明
webapi调用失败后执行该函数，其参数值为Object对象，参数格式如下：
|属性|类型|说明|
|-------|--------|-------|
|msg    |string    |webapi调用失败描述信息  |
|exceptionType  |string |异常类型           |
exceptionType的枚举值
|值|说明|
|-------|--------|
|UnLoginException|未登陆异常，需要登陆|
|UnExpectedException|系统内部异常|
|BusinessException|业务异常，通常webapi入参不符合要求|

#### 返回： void
#### 示例代码
```js
import vdk from 'v3-vdk';
vdk.webapi.exec({
    apiCode : "test",
    componentCode : "componentCode1",
    context:this,
    params : {
        a : "test",
        b : 1,
        c : true
    },
    success : function(data){
        //do something
    },
    fail : function(err){
        //do something
    }
});
```

---
## 移动端Api说明文档
### vdk.mobile.mediaCapture.captureVideo(Function successCallback,Function errorCallback)
拍摄视频
#### 参数

| 参数            | 类型     | 默认值 | 必填 | 说明     |
| --------------- | -------- | ------ | ---- | :------- |
| successCallback | Function |        | 是   | 成功回调 |
| errorCallback   | Function |        | 是   | 失败回调 |
##### successCallback说明
此api调用成功后执行该函数，其参数个数一个，类型为String，值为所拍摄视频的本地文件地址。
##### errorCallback说明
此api调用成功后执行该函数，其参数个数一个，类型为String，值为错误信息。
#### 返回： void
#### 示例代码
```js
vdk.mobile.mediaCapture.captureVideo(
    function(videoPath){
        //do something
    },
    function(errorMsg){
        //do something
    });



```

---
### vdk.mobile.imagePicker.getPicture(Function successCallback,Function errorCallback,Object options)
从手机相册选择文件
#### 参数

| 参数            | 类型     | 默认值 | 必填 | 说明     |
| --------------- | -------- | ------ | ---- | :------- |
| successCallback | Function |        | 是   | 成功回调 |
| errorCallback   | Function |        | 是   | 失败回调 |
| options         | Object   |        | 是   | 参数选项 |
##### successCallback说明
此api调用成功后执行该函数，其参数个数一个，类型为Array对象，值依次为所选取文件的本地地址。
##### errorCallback说明
此api调用成功后执行该函数，其参数个数一个，类型为String，值为错误信息。
##### options说明
配置选项，类型为Object，属性如下：

|属性|类型|默认值|必填|说明|
|-------|--------|-------|-------|-------|
|maximumImagesCount        |int     | 20 |否 |文件选择数量，默认为20                 |
|width  |int     | 0 |否 |否图片宽度，默认为0 (原图大小)                   |
|height         |int     | 0 |否 |图片高度，默认为0 (原图大小)                 |
|quality        |int   | 100 |否 |图片质量，默认为100%   |

#### 返回： void

#### 示例代码
```js
vdk.mobile.imagePicker.getPicture(
    function(results){
        //do something  eg.
        for (var i = 0; i < results.length; i++) {
	 			alert('Image URI: ' + results[i]);
	 	}
    },
    function(errorMsg){
        //do something
    },{
        maximumImagesCount: 5
       	width:0,
      	height: 0,
        quality: 70
    });




```

---
### vdk.mobile.camera.getPicture(Function successCallback,Function errorCallback,Object options)
拍照
#### 参数

| 参数            | 类型     | 默认值 | 必填 | 说明     |
| --------------- | -------- | ------ | ---- | :------- |
| successCallback | Function |        | 是   | 成功回调 |
| errorCallback   | Function |        | 是   | 失败回调 |
| options         | Object   |        | 是   | 参数选项 |
##### successCallback说明
此api调用成功后执行该函数，其参数个数一个，类型为String，值所拍照片的本地文件地址。
##### errorCallback说明
此api调用成功后执行该函数，其参数个数一个，类型为String，值为错误信息。
##### options说明
拍照选项，类型为Object，属性如下：

|属性|类型|默认值|必填|说明|
|-------|--------|-------|-------|-------|
|quality        |int     | 50 |否 |图片压缩比例，0-100之间,默认50                 |
|targetWidth  |int     | -1 |否 |图片宽度  -1为默认不修改                   |
|targetHeight         |int     | -1 |否 |图片高度  -1为默认不修改                 |

#### 返回： void

#### 示例代码
```js
vdk.mobile.camera.getPicture(
    function(imagePath){
        //do something
    },
    function(errorMsg){
        //do something
    },{
        quality: 60,
       	targetWidth:-1,
      	targetHeight: -1
    });



```

---
### vdk.mobile.fileTransfer.filetransferUpload(String fileUrls,Function callback)
文件上传
#### 参数

| 参数      | 类型     | 默认值 | 必填 | 说明                                                    |
| --------- | -------- | ------ | ---- | :------------------------------------------------------ |
| filePaths | Array    |        | 是   | 本地文件地址，数组格式  例如：[filePath1,filePath2,...] |
| callback  | Function |        | 是   | 回调函数                                                |
|context        |Object     |   |否     |上下文（vue实例）           |

##### filePaths说明

本地文件地址，数组格式   例如：[filePath1,filePath2,...]

##### callback说明

此api调用完成后执行该函数，其参数类型为Object，包含两个属性，说明如下：
|属性|类型|说明|
|-------|--------|-------|
|result        |Object     |结果对象，说明见【callback 入参result属性说明】|
|fileInfos         |Array     | 此Array中的元素为Object类型，说明见【fileInfos 元素对象属性说明】，依次为被上传文件所保存在服务端的文件ID（mongoDB） |

##### callback 入参result属性说明

|属性|类型|说明|
|-------|--------|-------|
|success        |Boolean     |成功 true  失败false                 |
|errorCode         |int     | 0:成功 1:不合法的URL  2:未知异常   3:服务器异常或网络连接失败 |

##### fileInfos 元素对象属性说明

|属性|类型|说明|
|-------|--------|-------|
|id        |String     |保存在服务端的文件ID（mongoDB）                 |
|fileSize         |int     | 文件大小（单位b） |
|fileType         |String     | 文件类型（例如：".MP4"） |
|oldFileName         |String     | 原文件名（例如："IMG_200.MP4"） |

##### context说明

context为vue实例对象，如在vue单文件组件中使用该接口，传递this即可

#### 返回： void

#### 示例代码
```js
vdk.mobile.fileTransfer.filetransferUpload(
   fileUrls,function(result,fileInfos){
        //do something
        //eg.
        if(result.success == true){
            alert("上传成功");
             for(var i=0;i<fileInfos.length;i++){
                 var fileId = fileInfos[i].id;
                 var fileSize = fileInfos[i].fileSize;
                 var fileType = fileInfos[i].fileType;
                 var oldFileName = fileInfos[i].oldFileName;
             }
            
        }else{
            var errorCode = result.errorCode;
            switch(errorCode){
                case 1:alert("不合法的URL");break;
                case 2:alert("未知异常");break;   
                case 3:alert("服务器异常或网络连接失败");break;
            }
        }
    },
    this);
```

---
### vdk.mobile.geoLocation.getCurrentPosition(Function  successCallBack,Function errorCallBack)
#### 参数

| 参数            | 类型     | 默认值 | 必填 | 说明     |
| --------------- | -------- | ------ | ---- | :------- |
| successCallBack | Function |        | 是   | 成功回调 |
| errorCallBack   | Function |        | 是   | 失败回调 |
| config	      | Object   |        | 否   | 可选的额外信息 |

##### successCallBack说明

此api调用成功后执行该函数，其参数个数一个，类型为Object，详细定义如下：
|属性|类型|说明|
|-------|--------|-------|
|latitude        |float     |纬度                 |
|longitude         |float     | 经度 |


##### errorCallBack说明

此api调用成功后执行该函数，其参数个数一个，类型为String，值为错误信息。

##### config
config用于部分场景定位下需要的额外信息。下面是说行说明。
|属性|类型|说明|
|-------|--------|-------|
|baiduMapAK        |String     |百度地图应用AK码，用于在没有配置https的场景下使用百度地图的ip定位功能。<br/>申请地址：http://lbsyun.baidu.com/apiconsole/key#/home
#### 返回： void

#### 示例代码
```js
vdk.mobile.geoLocation.getCurrentPosition(
  function(result){
        //do something
  },function(errorMsg){
      //do something
  },{
    baiduMapAK:"Ka2Zv7RowNPQN40yAuQOvnuCIyj8IMGf"//本AK码使用次数有限制，仅供测试使用。
  });
```

---
### vdk.mobile.fileUpload.upload(String DomId, Function successCallBack,Function errorCallBack)
文件上传
#### 参数
| 参数            | 类型     | 默认值 | 必填 | 说明                            |
| --------------- | -------- | ------ | ---- | :------------------------------ |
| DomId           | String   |        | 是   | 触发文件选择对话框的DOM元素的id |
| successCallBack | Function |        | 是   | 成功回调                        |
| errorCallBack   | Function |        | 是   | 失败回调                        |
| config          | Object   |        | 否   |  可选配置                      |

##### successCallBack说明

此api调用成功后执行该函数，其参数个数一个，类型为Array，Array的元素为Object，Object的属性说明如下：
|属性|类型|说明|
|-------|--------|-------|
|id        |String     |mongoDB文件ID                 |
|fileSize         |int     | 文件大小(字节) |
|oldFileName |String | 文件名 |

##### errorCallBack说明	

此api调用成功后执行该函数，其参数个数一个，类型为String，值为错误信息。

##### config说明
```js
{
    //文件类型过滤参数
    fileType:"jpg,png,zip", //过滤文件的类型。如果用户选择了指定类型之外的文件，将不会触发上传。
    fileTypeErrorCB:function(error){}, //用于和fileType结合使用，在用户选择了指定类型之外的文件时，触发这个回调。后面有其参数的说明。
    //相机参数
    fileMimeType:"image/*" , //过滤文件的mimeType。用于和useCamera结合使用，要拍照片时将这个值设为image/*，要拍视频时将这个值设为video/*。
    useCamera:true //true代表尽量使用照相机。将这个参数指定为true后，能否直接打开照相机因不同机型不同系统不同浏览器的不同，可能会有差异。
    //另外，文件选择界面也会根据fileMimeType或fileType（优先根据fileMimeType，如果没有指定fileMimeType，则会根据fileType），过滤掉不符合条件的文件。这个功能也会因不同机型不同系统不同浏览器有所差异。
* }
```
fileTypeErrorCB参数说明：
```js
//该参数是一个Object，是plupload提供的错误对象。其属性说明如下
{
    "fileName":"03.公司制度目录.xlsx"//用户实际选择的文件名
}
```

#### 返回： void

#### 示例代码：

注意：此方法必须在【mounted】方法中调用

```js
vdk.mobile.fileUpload.upload("btn_fileupload_take_photo", function () {
    alert("上传成功");
}, function () {
    alert("上传失败1");
},{
    useCamera: true,
    fileMimeType:"video/*",//useCamera,fileMimeType指定调用摄像机拍摄视频
    fileType:"zip",//fileType指定文件类型为zip才会触发文件上传。
    fileTypeErrorCB:function(error){
        alert("文件类型错误：" + JSON.stringify(error));
    }
});
```