XX市新城新区智慧城市地理信息地图接口标准规范.docx

XX市新城新区智慧城市地理信息地图接口标准规范.docx

《XX市新城新区智慧城市地理信息地图接口标准规范.docx》由会员分享，可在线阅读，更多相关《XX市新城新区智慧城市地理信息地图接口标准规范.docx（102页珍藏版）》请在冰点文库上搜索。

XX市新城新区智慧城市地理信息地图接口标准规范

XX市YY新区智慧城市建设项目

公共信息平台专项地理信息服务平台

（一期）单项工程

数据更新机制

XX有限公司

XX研究院有限公司

二〇二〇年七月

引言

文档目的

本文档为XxtMap地图框架的接口说明文档，供开发人员在使用XxtMap开发GIS业务系统时查阅及学习使用。

文档背景

XxtMap已陆陆续续被公司各个项目组所使用，在本版本（v1.4）之前一直依赖于angular框架且在未成熟的情况下大面积投入使用，前期一直缺乏一个完善全面的接口说明文档，对项目组开发人员造成了较大困扰。

本次借新版纯JS地图框架的发布，编写一份较为全面的接口说明文档。

供框架研发人员后续设计、升级、优化框架作为依据，供项目开发人员功能开发进行查阅和学习。

文档范围

本文档建议阅读群体为XxtMap框架研发人员、公司项目组前端开发人员、使用XxtMap进行GIS系统开发的第三方开发团队等。

本文档主要内容为XxtMap的公有接口说明，其次涵少部分设计说明，有关于XxtMap框架的其他详细内容包括设计说明、教程、白皮书、示例等另有独立文档进行阐述。

术语表

术语

术语说明

TBD

待定、待决定、待讨论、不确定内容的章节、待完善的章节

ToBeDiscussed

ToBeDetermined

ToBeDefined

Coordinate

点坐标，文档中如用Coordinate表示数据类型，其类型结构是一个二维数组[number,number]，表示[x,y]坐标

Extent

矩形范围，文档中如用Extet表示数据类型，其类型结构是一个四维数组[number,numer,number,number]，表示[xmin,ymin,xmax,ymax]

Size

尺寸，文档中如用Size表示数据类型，其类型结构是一个二维数组[number,number]，表示[width,height]

IF或I/F

接口简写，Interface

API设计约定

注：

该章节主要面向群体为XxtMap框架开发者以及高级研发工程师。

XxtMap的接口设计理念与Openlayers、SuperMap、Arcgis、Baidu等存在较大区别，XxtMap的设计理念并非做一个大而全的“轮子”，核心目标是为本公司项目开发团队打造一个简单、快速、高效的GIS系统开发工具。

总体原则

原则

说明

顶层接口原则

所有接口都由FUtil、FMap两个类来暴露给模块开发者；

后续升级只会新增子接口和配置项，以保证对项目代码不产生升级影响。

向下兼容原则

后续版本保留所有前一版本旧接口，如有配置项或接口需要替换原有接口，原则上要兼容，保留旧接口，只是在API注释里注明弃用建议。

公有接口原则

框架底层设计和内部实现不管如何变化，公有接口尽量保持不变，原则上后续只能新增，不能改动或废弃。

只能建议性废弃使用，不能从技术实现上废弃。

公有接口统一暴露在FUtil、FMap以及Options配置项上。

内部接口原则

框架开发人员内部设计和逻辑实现，可以使用FInject对象，该对象内部映射了大部分内部类的内部接口（逻辑上标识的内部）；

内部接口不能暴露给模块开发者，以免造成升级后与模块代码的矛盾不可控。

原生对象接口原则

SDK提供对Openlayers原生对象访问和调用的API和说明，但强调，对原生API的使用所产生的缺陷及升级矛盾，框架组只提供技术建议，不负责缺陷责任；

因此原则上不建议访问原生对象，统一使用顶层公有接口进行模块功能实现；

如遇特殊情况需要使用，项目开发经理需评估方案和影响，以及做好代码评审。

并做好代码记录，以便后续及时修复代码为顶层接口实现方式。

开发分工原则

SDK设计，需要考虑系统实现及模块开发上的分工；

为系统设计及模块开发提供可拆分可分工的技术指导；

尽量参考软件工程中已有的一些设计理念，如：

MVC、HTML-JS-CSS、Jquery选择器、CSS动画、twaver序列化等等；

设计约定

设计

说明

声明式编程设计模式

SDK设计的最终使用模式，应尽量贴合声明式编程的模式。

尽量让模块业务以配置形式来表达及实现。

减少过程式的对象创建和对象协助代码。

通俗点讲，即SDK的使用应尽量接近伪代码编程，业务实现应接近“表达”，而非“程序”或“逻辑”。

适配器设计模式

SDK的关键公有及私有对象应尽量抽象，代表GIS实体的对象统一保有_orgin属性,目前用于关联Openlayers实体，通过保有顶层接口不变的形式，未来可以集成其他二维地图框架以及集成3D地图框架；

GIS实体提供getOrigin（）方法获取原生地图对象的访问，用于应对极少数SDK暂无覆盖的功能需求；但原则上不建议去使用，这只是一个保险手段，以备不时之需。

命名对象设计模式

图源、图元、图层、样式都借鉴命名对象设计模式

尽量先声明、再以代号引用，尽量将业务逻辑拆分成各种静态声明+动态引用。

静态声明需要做到共性个性兼顾，还可以将静态声明设计成静态模板声明加动态渲染。

引导项目积累，所有的命名对象在产品过程中形成积累，都可以成为一种领域模型或产品模型中的“库文件”。

如图元业务库、领域业务专题库、通用样式库、领域样式库、产品样式库、厂商图源库、图源元数据库、业务卡片库等等。

注册引用设计模式

与命名对象设计相关，注册引用是主要的实现方式。

尽量将“业务逻辑->程序逻辑”传统实现模式转化成我们提倡的模式“业务逻辑->注册声明+动态引用”的模式

渲染器设计模式

借鉴Flex及其他UI编程中的渲染器设计模式；

对于与图层要素相关的所有配置项，如与业务特征有关，都可以采用渲染器，同时达到了解耦与个性化的需求；

支持渲染器的配置包括：

symbol、style、text、bubble、contextMenu等等；

举个例子，如图元渲染器

symbol:

policeSymbol

functionpoliceSymbol（feature）{

vartype=feature.getClient（）.policeType;

//type如MJ、FJ、JJ，民警、辅警、交警等等

varsymbol='police_'+type;

returnsymbol;

}

MVC设计模式

尽量将模块业务通过图层配置来实现，图层配置通过Watch框架实现伪MVC模式（只针对部分常用配置属性进行监听，并且考虑到性能问题，开放开发者可关闭监听，关闭情况下图层MVC失效），即图层配置发生变化，地图视图就会发生变化。

减少过程式的API操作调用，尽量用配置变更和数据变化去影响视图。

状态编程设计

业务与状态：

减少对对象的引用进行操纵，提供将业务特征属性作为关键特征数据，通过数据变化影响业务逻辑或业务视图的编程模式，实际就是MVC模式的一种应用场景；如警员图层配置在线警员离线警员的不同图元。

functionpoliceSymbol（feature）{

returnfeature.getClient（）.status;

}

varlayers={

policeLayer:

{name:

'policeLayer',symbol:

policeSymbol}

}

业务数据的状态值变化视图就会变化，无需进行调用操作

业务-类型-状态：

与上面例子类似，如视频图层球机枪击的展示

状态与样式、状态与皮肤、状态与特效等等类似的场景应用和设计，实际就是灵活应用接口然后调配UI人员、模块开发人员、平面设计师进行分工合作，而不是JS开发者“一脚踢”完成所有事情。

关于以上说明的详细教程，会组织主程岗位、UI岗位、高级前端岗位等人员进行专门培训。

序列化设计

借鉴设计器类在线软件的序列化设计、借鉴KML、GeoJson等序列化设计、借鉴Twaver框架，设计XxtMap的序列化与反序列化。

序列化：

即可以将一个运行时的XxtMap地图内存对象转化成一个格式及语意预先严格定义的XML字符串，序列化格式通过DTD文件定义，可被软件或IDE工具理解。

序列化后的文件可存储、可传输、可还原为运行时内存对象。

反序列化：

即通过反序列化接口FUtil.deserialize（…）可以将一个序列化XML文件或XML内容还原成一个内存FMap对象。

即您可以理解成类似PowerPoint软件打开一个ppt文档。

XML序列化图源只序列化参数，不存储瓦片。

序列化要素既提供序列化要素的数据接口也提供序列化要素数据内容两种方式。

后续可提供二进制序列化。

序列化反序列化是框架未来提供更多高级特性、高级服务的最重要最核心基础。

也是软件设计中的高阶应用。

OPSC设计

Object-Property-Style-Client对象-属性-样式-业务

模仿电信领域Twaver框架序列化设计。

拿一个地图要素来举例：

Object就是这个要素的内存对象，fc.map.Feature，这个对象实例有哪些公有属性和接口是固定的；

Property就是开发者可以根据实际业务、环境、场景等，为这个要素注入的数据上下文或叫动态属性；

Style可以理解为半固定半开放的专门用于表达样式的动态property,你可以理解为dom编程中的setStyle（proName,proValue）;

Client是一种特殊的动态Property,他是在批量数据上图时自动记录的要素对应的原始业务对象。

内联外链设计

气泡提供内联气泡外链气泡；

内联气泡：

引用系统内的代码块、相对URI地址展示气泡内容

外链气泡：

引用系统外的URI链接展示气泡内容

dataprovider数据源接口设计

所有含数据源对接的组件（包括图层）都设计dataprovider参数，参数数据类型可以对接三种

StringdataUrl模式，一般多用于对接远程服务，尤其是标准服务和异步组件（如异步树、异步多级选择器）

ObjectdataObj模式，一般用于一次性注入完整数据源的组件，尤其是经过远程服务的数据注入组件前要经过加工、格式化等的场景

FunctiondataIF模式，终极模式，开发者可利用他按任何业务逻辑给组件注入数据源，适应场景广泛，但要求为保证统一性，必须返回含done操作的Promise对象，promise释放对象即为数据源或异步子级数据

详细规范

约定

说明

框架命名规范

地图框架命名XxtMap

打包输出:

XxtMap-vX.X.X.rar，x.x.x为版本号，语义为大版本号-功能版本号-构建版本号或缺陷修复版本号

XxtMap发布的版本均为压缩混淆版，不再提供开源版。

编程命名规范见章节【1.4命名规范】

类设计规范

所有GIS业务实体均设计为内部类，不暴露，内部类内部协作完成功能，对外暴露顶层接口及配置项。

接口提供规范

只暴露顶层接口及配置项接口，即FUtil、FMap、Options

配置优先级设计规范

地图配置<图层配置<上图配置<要素配置<状态配置

命名规范

约定

说明

属性命名

同行业JS前端代码规范

布尔属性命名

xxxable或isXxx

配置参数命名

xxxOpts

获取属性值属性对象方法命名

getXXX

多单词属性采用波浪标识：

如getMapType

设置属性值属性对象方法命名

setXXX

多单词属性采用波浪标识：

如setMaxZoom

注册方法命名

registXXX

多单词属性采用波浪标识：

如registProjAlias

交互模式启停方法命名

开启交互命名：

activateXXX

关闭交互命名：

deactivateXXX

图源方法命名

FXM

X地图英文简写首字母大写（部分避免冲突用双字母），F前缀标识精一。

如：

XX地图FBM、高德地图FGM、谷歌地图FGGM

布尔判断方法命名

isXXX

如：

isCoordinateInCircle

添加对象方法命名

addXXX

移除对象方法命名

removeXXX

清空对象方法命名

clearXXX

索引方法、查找方法命名

getXXXByXXX

事件类型命名

**

事件类型命名：

变化事件

**:

xxx

任意属性值变化

**:

property,如：

fmap.layer.change:

property

特定属性值变化

**:

xxx,如：

fmap.view.change:

zoom

FUtil接口

Map相关

getMap

getMap根据地图ID获取地图实例对象

getMap（mapId）»»{FMap} 

参数

类型

说明

mapId

String

地图ID,也是DOM元素ID

Returns:

fmap地图实例

Example：