template/README.md

# TIS 应用与组件 - 开发

## 1. 安装依赖

```
npm install
```
如果您的设备支持联网，请分别在template、\__test__、src/tis_app_frame、src/tis_component_example、src/tis_widget_frame 这几个文件夹下分别删除node_modules，并且重新执行npm install进行必要的依赖安装
## 2. 一健启动
```
npm run start
```

浏览器里打开 http://localhost:8001/TIS_PLATFORM/ ,即可预览框架中的运行效果

默认的应用地址 http://localhost:7000/, 这是应用独立启动的地址，如果您需要单独进入应用而不使用平台框架的依赖，点此进入，这也是您的应用在框架中开发的启动地址

默认的公共业务组件地址 http://localhost:7001/ ，这是公共业务组件的地址，如果您需要单独预览公共业务组件而不使用平台框架的依赖，点此进入，这也是您的组件在框架中开发的启动地址

默认的浮窗应用地址 http://localhost:7002/ ，这是浮窗应用的地址，如果您需要单独预览浮窗应用地址而不使用平台框架的依赖，点此进入，这也是您的浮窗组件在框架中开发的启动地址

__如果您在src下新复制了一份tis_app_frame(tis_component_example或tis_widget_frame)请手动修改该目录下vue.config.js中的dev port__

修改前：
```js
const port = 7001; // dev port 
```

修改后：
```js
const port = 7003; // dev port 从3开始，0,1,2均被默认的三个例子占用
```
```
npm run start:default
```
启动默认的框架依赖，包括：框架、tis-ui服务、一个默认的例子应用。使应用能够预览在框架中的运行效果，并且能够调用框架提供的各种接口，建议开发者执行此命令

```
npm run start:platform
```
单独启动框架

```
npm run start:tis-ui

```
单独启动tis-ui服务，使应用能够基于tis-ui进行开发

```
npm run start:apps_widgets 
```
启动所有的浮窗应用

```
npm run start:ws
```
启动websocket测试程序，应用可以通过此命令测试后台对前端的推送以及消息接收功能

如果您需要和后端的ws地址链接，进行调试，请修改**lib/platform/dist/TIS_PLATFORM/manifest/manifest.json** 中的wsUrl

```json
{
  "wsUrl": "ws://localhost:9999",
  "whitelist": []
}
```

```
npm run start:design
```
一站式开发平台，包含了整个开发平台的介绍、api手册、tis-ui的开发示例等，是开发者入门学习的帮助文档
## 3. 编码
### 3.1 编码前须知
开发者拿到此模板请根据需要重新命名src下的三个工程的文件夹名称，例如：指挥决策软件，请将tis_app_frame重命名为tis_app_frame_zhjc 

- tis(平台)_app(类别为app)_frame(应用框架)_xxx(唯一id简拼)
- tis(平台)_widget(类别为浮窗app)_frame(应用框架)_xxx(唯一id简拼)
- tis(平台)_component(业务组件)_xxx(唯一id简拼)
请开发者务必按照上述命名规范进行命名，否则集成阶段不会预期加载您的软件
### 3.2 编码中
修改tis_app_frame/ 和 tis_component_example/ 和 tis_widget_frame/ 里的文件

可在浏览器里查看到实时修改结果

### 3.3 配置文件

在tis_app_frame/public文件夹下您可以看到名为esplug.json的文件夹，在这里您需要填写一些简单的配置。

1. 引入第三方业务组件

您需要将第三方业务组件相关资源拷贝到sdk文件夹中，然后重新运行您的项目，否则将不会生效

2. 按照如下填写配置文件

component中的组件您可以根据自己的需要进行二次拓展
- 拓展前
```json
    {
      "name": "组件测试用例",   //必填 组件中文名称
      "component": "testApp", //必填 组件对外暴露的名称
      "icon": "icon-huojian", //选填 icon
      "segprefix": "TIS_COMPONET_EXAMPLE", //组件所在的文件夹名称，必填
      "dependencies": ["tis-component-demo-2"]//选填 外部依赖               
    },
```
- 拓展后
```json
{
      "name": "组件测试用例",   //必填 组件中文名称
      "component": "testApp", //必填 组件对外暴露的名称
      "icon": "icon-huojian", //选填 icon
      "segprefix": "TIS_COMPONET_EXAMPLE", //组件所在的文件夹名称，必填
      "dependencies": ["tis-component-demo-2"],//选填 外部依赖           
      "position":"", //拓展属性
      "width":"", //拓展属性
      "height":"" //拓展属性    
},
```

3. 在esplug.json中将引入的组件配置到components数组当中，并且填写好当前开发应用的name
```json
{
  "name": "应用框架示例", //必填 应用名称
  "components": [       //选填 组件集合
    {
      "name": "组件测试用例",   //必填 组件中文名称
      "component": "testApp", //必填 组件对外暴露的名称
      "icon": "icon-huojian", //选填 icon
      "segprefix": "TIS_COMPONET_EXAMPLE", //组件所在的文件夹名称，必填
      "dependencies": ["tis-component-demo-2"]//选填 外部依赖               
    },
    {
      "name": "组件测试用例2",
      "component": "testApp2",
      "icon": "icon-huojian",
      "segprefix": "tis-component-demo-2"
    },
    {
      "name":"kt应用市场代码",
      "component":"pcmarket",
      "segprefix":"TIS_YYSC"
    }
  ]
}
```
4. 在项目中引入组件

```js
<template>
  <div id="app">
      <component :is="kt_yysc"></component>
    </div>
  </div>
</template>
export default {
  name: "App",
  data() {
    return {
      kt_yysc: "",
    };
  },
  mounted() {
    this.$tis.loadComponent("testApp")//组件的segprefix
      .then((res) => {
        console.log("load component", res);
        this.compName = "testApp";
      })
      .catch((err) => {
        this.compName = "testApp";
        console.error(err);
      });
};
```
5. CSS多端适配

本项目采取了基于__视口单位(Viewport units)__的CSS自适应布局单位，标准设计稿尺寸为 1600*1200

vw（Viewport Width）、vh(Viewport Height)是基于视图窗口的单位，是css3的一部分，基于视图窗口的单位，除了vw、vh还有vmin、vmax。

- vw:1vw 等于视口宽度的1%
- Vh:1vh 等于视口高度的1%
- vmin: 选取 vw 和 vh 中最小的那个,即在手机竖屏时，- 1vmin=1vw
- vmax:选取 vw 和 vh 中最大的那个 ,即在手机竖屏时，1vmax=1vh

我们预置了px转换vw单位的插件，您可以方便的使用设计稿中的px单位，项目会自动帮助您进行单位转换，如果您需要按需配置，请在项目目录下的 postcss.config.js中进行自定义配置

```js
module.exports = {
    parser: false,
    sourceMap: false,
    plugins: {
        'postcss-px-to-viewport': {
            // options
            unitToConvert: 'px',//(String) 需要转换的单位，默认为"px"
            viewportWidth: 1200, // (Number) 设计稿的视口宽度，一般是750
            unitPrecision: 3, //  (Number) 单位转换后保留的精度（很多时候无法整除）
            viewportUnit: 'vw', // (String) 希望使用的视口单位
            selectorBlackList: ['.ignore', '.hairlines'],
            /*(Array) 需要忽略的CSS选择器，不会转为视口单位，使用原有的px等单位
            如果传入的值为字符串的话，只要选择器中含有传入值就会被匹配
                例如 selectorBlackList 为 ['body'] 的话， 那么 .body-class 就会被忽略
            如果传入的值为正则表达式的话，那么就会依据CSS选择器是否匹配该正则
                例如 selectorBlackList 为 [/^body$/] , 那么 body 会被忽略，而 .body 不会*/
            minPixelValue: 1, // (Number) 设置最小的转换数值，如果为1的话，只有大于1的值会被转换
            mediaQuery: false, // (Boolean) 媒体查询里的单位是否需要转换单位
            exclude: [/^node_modules$/],// (Array or Regexp) 忽略某些文件夹下的文件或特定文件，例如 'node_modules' 下的文件
            //include：/\/src\/mobile\//  
            /*(Array or Regexp) 如果设置了include，那将只有匹配到的文件才会被转换，例如只转换 'src/mobile' 下的文件
            如果值是一个正则表达式，将包含匹配的文件，否则将排除该文件
            如果传入的值是一个数组，那么数组里的值必须为正则
            注意：exclude和include是可以一起设置的，将取两者规则的交集*/
            landscapeUnit: 'vw', //(String)横屏时使用的单位
            landscapeWidth: 1200 //(Number)横屏时使用的视口宽度
        }
    }
}
```
6. 静态资源的引用

如果您在开发过程中在css文件中需要引入一些图片、文字等静态资源文件，请您使用内联style，否则将不会有预期效果

例如：
```css
{
  background:url('/assets/temp.png')
  
}
```
上述的url会由于公共路径的变化而不会生效，您可以使用内联style来实现背景图的引用
```html
<template>
  <div :style="{background:`url(${require(`./assets/bg2.png`)})`}">
  </div>
</template>
<script>
export default {
  name: "tisc-aim-list"
};
</script>
<style lang="scss" scoped>
div {
  /* background-image: url("/TIS_APP_FRAME/bg2.png"); */
  background-size: cover;
  background-repeat: no-repeat;
  width: 100%;
  height: 220px;
}
</style>
```

7. 在项目中引入地图

如果您希望在组件中引入地图组件，那么请按照如下方式引入，具体的地图接口、API等请参见《地图程序员手册》
```html
<template>
  <div style=" width:100%; height:100%;position:absolute;
    top:0;
    bottom: 0;
    left: 0;
    right: 0;">
    <div name="outerDiv" id="outerDiv"></div>
  </div>
</template>
<script>
  //import $bus15 from "../assets/util/bus";
  import { setInterval } from "timers";
  export default {
    //组件名称必须填写，并且必须和注册名称、打包名称(异步引入时需要)保持一致
    name: "mapMGIS15",
    data() {
      return {
        statusClock: null,
        timeStamp: 2 * 60 * 1000,
        // timeStamp:20*1000,
        workspaceName: "workspace"
      };
    },
    components: {
    },
    mounted() {
      window.Mgs.GDataManager.newFile();
      window.Mgs.GDataManager._eventSourceInitialize();

      var map2DManager = window.esapp.ShareMap.Map2DManager;

      var self = this;
      var map = map2DManager.loadMap("outerDiv", {
        alias: "100w21",
        version: 1000,
        url: window.MGS_IP_URL,
        centerPoint: [35.24277, 113.54164, 7],
        panelControl: []
      });
      window.esMap = window.emap2d = map;
      var layer = map.Layer2DManager.addLayer(
        window.esapp.ShareMap.EsMapConstants.LAYER_TYPE_2D.PLOTTING,
        {
          layerName: "默认图层",
          needToBeShared: true
        },
        {
          needAddToTree: true
        }
      );
      layer.setLayerAutoSave(true);
      map.DrawControl.setDrawingLayer(layer);
      self.bindMapStatusSave();

      setTimeout(function () {
        self.loadAfter();
      }, 3000);
    },
    methods: {
      bindMapStatusSave() {
        var self = this;
        var options = {
          fileName: self.workspaceName + ".sml",
          userName: self.workspaceName,
          success: function () {
          },
          fail: function () {
          }
        };
        this.statusClock = setInterval(function () {
          window.Mgs.GFileManager.saveWorkSpace(options);
        }, this.timeStamp);
      },
      loadAfter() {
        var self = this;
        var options = {
          fileName: self.workspaceName + ".sml",
          userName: this.workspaceName,
          isOverlay: true,
          success() {
            // self.$message({
            //   type: "success",
            //   message: "打开工作区文件成功"
            // });
          }
        };
        window.Mgs.GFileManager.openFile(options);
      }
    }
  };
</script>

<style>
  #outerDiv {
    margin: 0;
    padding: 0;
    width: 100%;
    height: 100%;
    overflow: hidden;
    z-index: 10;
    position: absolute;
    background: url(/TIS_DLBHZJQD/gridres/images/nomap256x256.png) repeat;
  }

  .mgstag {
    border: 2px solid #09f;
    position: absolute;
    background-color: transparent;
    background-color: rgba(255, 255, 255, 0.6);
    z-index: 999;
    min-width: 150px;
    min-height: 100px;
    max-width: 200px;
  }

  .mgstag:after,
  .mgstag:before {
    content: "";
    display: block;
    position: absolute;
    bottom: -40px;
    left: 50px;
    border: 17px dashed transparent;
    border-top: 21px solid #09f;
    font-size: 0;
    line-height: 0;
  }

  .mgstag:after {
    bottom: -38px;
    border-color: rgba(255, 255, 255, 0.9) transparent transparent;
  }

  .mgstag .mgstag-head {
    text-align: center;
    background-color: #09f;
    font-weight: bold;
    font-size: 12px;
  }

  .mgstag .mgstag-content {
    overflow-x: hidden;
    overflow-y: auto;
    font-size: 12px;
  }

  .emp-icon-path {
    background-repeat: no-repeat;
    background-size: 100% 100%;
  }

  /* 气泡弹框 */
  .tooltip-pane:before {
    left: calc(50% - 6px);
    position: absolute;
    pointer-events: none;
    border: 6px solid transparent;
    background: transparent;
    content: "";
    border-top-color: #fff;
    bottom: -12px;
  }

  #magnifyWin {
    display: auto;
    position: absolute;
    overflow: hidden;
    bottom: 50px;
    z-index: 9999;
    width: 360px;
    height: 360px;
    padding: 1px;
    background-color: #9fa29d;
    border-radius: 8px;
    box-shadow: 0 0 7px #bcb4ac;
    cursor: pointer;
    background-color: rgba(200, 200, 250, 0.2);
  }
</style>
```

在lib/platform/dist/TIS_PLATFORM/map15/TerraGlobe/config.js修改地图后端的接口基地址serverIp、MGS_IP
```js
function isPc(){
    var agents = ["android","windows phone","iphone","ipad","ipod","symbianos","syberos"];
    for(var i = 0;i < agents.length;i ++){
        if(new RegExp(agents[i],"i").test(window.navigator.userAgent.toLowerCase())){
            return true
        }
    }
    return false
}
if(window.IS_MOBILE){
	if (isOnLine) {    
	} else {
		// serverIp = "130.30.1.16";
        // serverIp = "192.168.11.146";
      serverIp = "10.10.10.89",//地图服务基地址
    	MGS_IP_URL = 'http://' + serverIp + ":3886/";
    	MGS_SERVER_URL = MGS_IP_URL + "api/services";
    	MGS_TILE_URL = MGS_IP_URL + "gis3globle"; //瓦片 
    	MGS_TILE_URL_OFFLINE = MGS_IP_URL + "api/services/get_tile/get_tile/";
    	MGS_2D_TILE = MGS_IP_URL + "gis3globle/maps/services"; //二维瓦片
	}
}
var isOnLine = false;
window.isOnLine = false
window.IS_MOBILE = isPc();
window.MGS_PATH_NAME = "./map15";
if (isOnLine) {
    MGS_IP_URL = "http://192.168.56.162:9999/";
    MGS_SERVER_URL = MGS_IP_URL + "MGSServer";
    MGS_TILE_URL = MGS_IP_URL + "gis3globle"; //瓦片
    MGS_TILE_URL_OFFLINE = MGS_IP_URL + "api/services/get_tile/get_tile/";
    MGS_2D_TILE = MGS_IP_URL + "gis3globle/maps/services" //二维瓦片
} else {
    MGS_IP_URL = "http://10.10.10.89:3806/";
    MGS_SERVER_URL = MGS_IP_URL + "api/services";
    MGS_TILE_URL = MGS_IP_URL + "gis3globle"; //瓦片 
    MGS_TILE_URL_OFFLINE = MGS_IP_URL + "api/services/get_tile/get_tile/";
    MGS_2D_TILE = MGS_IP_URL + "gis3globle/maps/services" //二维瓦片
}
MGS_IP = "http://10.10.10.89";//地图服务基地址
// debugger
// MGIS.Terramap.serviceIp="130.30.1.16";

```
### 3.4 在框架中预览

当前开发框架已为您默认配置好了应用的入口，如果您有需要自定义配置，默认的配置路径在

**lib/platform/manifest/apps_widgets.json**

entry:""//您项目的运行地址

id:""//一般默认为您的工程项目名

icon:""//您的app应用图标
```json
{
  "apps": [
    {
      "name": "应用框架示例",
      "components": [
        {
          "name": "组件测试用例",
          "component": "testApp",
          "icon": "icon-huojian",
          "segprefix": "TIS_COMPONET_EXAMPLE",
          "dependencies": [
            "tis-component-demo-2"
          ]
        },
        {
          "name": "组件测试用例2",
          "component": "testApp2",
          "icon": "icon-huojian",
          "segprefix": "tis-component-demo-2"
        },
        {
          "name": "kt应用市场代码",
          "component": "pcmarket",
          "segprefix": "TIS_YYSC"
        },
        ...
      ],
      "id": "tis_app_frame",  //应用唯一id
      "entry": "http://localhost:7000", //端口
      "icon": "http://localhost:7000/icon.png"
    },
    ...
  },
  "widgets":[]
}
```
### 3.5 工程整理

在开发模板中我们预设了一些例子,例如sdk文件夹中的组件，大多数情况下，您需要自行引入您需要的组件，而不是使用这些示例，所以当您完全了解开发工程的结构后请务必及时删除这些不必要的示例。

例如：tis_app_frame/sdk 下的TIS_YYSC和tis-component-demo-2就是您需要删除的不必要文件

## 4. 构建打包
```
npm run build
```

- tis_app_frame 的构建产物在 tis_app_frame/dist
- tis_component_example 的构建产物在 tis_component_example/dist
- tis_widget_frame 的构建产物在 tis_widget_frame/dist

如果您有多个项目，那么打包构建后的产物会生成在当前项目工程的dist文件夹中

__请注意,dist目录中是src文件夹下所有工程的打包集合，您需要按需使用，例如您只基于tis_app_frame工程开发了您的应用，那么tis_widget_frame与tis_component_example便不是您需要的文件，请您在提取构建产物时务必检查__

## 5. 其他
### 5.1 目录结构说明

```
.
├── __test__                //测试文件夹
│   └── websocket //websocket测试
├── dist                    //打包构建产物
│   ├── TIS_APP_FRAME
│   │   ├── css
│   │   └── js
│   ├── TIS_COMPONET_EXAMPLE
│   │   ├── css
│   │   └── js
│   └── TIS_WIDGET_FRAME
│       ├── css
│       └── js
├── lib //外部依赖
│   ├── default_app           //默认的app模板依赖
│   │   └── dist 
│   ├── platform              //平台框架依赖
│   │   └── dist
│   ├── tis_design            //一站式开发平台帮助文档
│   │   └── examples
│   └── ui                    //ui外部依赖
│       ├── tis-ui            
│       └── vue
└── src  //源码存放文件夹
    ├── tis_app_frame          //默认的app模板
    │   ├── dist               //打包构建产物
    │   ├── public             //静态资源存放目录
    │   ├── sdk                //第三方组件存放目录
    │   ├── src                //源码存放文件夹
    │   └── webpack_plugins    //webpack插件
    ├── tis_componet_example   //默认的component模板
    │   ├── dist
    │   ├── public
    │   ├── sdk
    │   ├── src
    │   └── webpack_plugins
    └── tis_widget_frame        //默认的widget模板
        ├── dist
        ├── public
        ├── sdk
        ├── src
        └── webpack_plugins

```
### 5.2 更换必要的lib库
框架(TIS_PLATFORM)、界面UI库(tis-ui、tis-m)进行更新变更，如您想体验到新版的框架和界面UI库，请将lib/platform/dist/TIS_PLATFORM 或者 ui/tis-ui 下的文件删除，并替换成同名的最新文件即可

### 5.3 配置代理

当您在sdk文件夹中引入一些组件依赖，而这些组件依赖是异步构建的，例如您试图兼容一些kt已开发好的组件，那么您必须在config.js中配置您当前运行环境的域名才能保证组件所有异步资源的正常加载，例如：在tis_app_frame工程中您引入了一个名为TIS_YYSC的异步构建的kt组件，那么您需要在config.js中作如下配置,确保在开发环境中资源可以被正常加载。

```
    '/TIS_YYSC':{
        target:'http://localhost:7000',
        changeOrigin:true
    }
```