@tmsfe/tms-runtime

@tencent/tms-runtime

一、tms-runtime提供的API列表

getEnvInfo()

获取当前运行小程序的环境信息。

参数说明

* @param {void}
* @returns {object} env 环境信息
* @returns {string} env.appId 小程序的appId
* @returns {string} env.appVersion 小程序的版本号
* @returns {string} env.appEnv 运行环境 test - 测试、production - 正式、predist - 灰度
* @returns {string} env.client 项目名，sinan - 腾讯出行服务； mycar - 腾讯我的车

使用示例

Page({
  onLoad() {
    const app = getApp({ allowDefault: true }); // 获取全局APP实例
    const { client } = app.tms.getEnvInfo();
    if (client === 'sinan') {
      // xxx
    }
  },
});

getLoginInfo()

获取当前运行小程序的登录态信息

参数说明

* @param {void}
* @returns {promise} loginInfo 登录态信息promise
* @returns {string} loginInfo.userId 用户在腾讯车联账号体系下的userId
* @returns {string} loginInfo.token 用户登录态token（注意用户每次登录会刷新token）
* @returns {number} loginInfo.firstLogin 用户是否首次登录小程序 0 -否，1 - 是

使用示例

Page({
  onLoad() {
    const app = getApp({ allowDefault: true }); // 获取全局APP实例
    const { userId } = app.tms.getLoginInfo();
    this.setData({ userId });
  },
});

getUserLocation(showModalWhenCloseAuth)

获取用户选择的城市位置信息或者用户真实的位置信息

参数说明

* @param {boolean} showModalWhenCloseAuth 没有授权时是否展示授权弹窗
* @returns {promise} 用户位置信息promise
* 返回数据示意
* {
*   province: '北京市',
*   cityName: '北京市',
*   cityCode: '100100',
*   latitude: 325.255333,
*   longitude: 116.2545454,
*   adCode: 1212144,
*   poi: {
*     id: '1114545554511',
*     title: '腾讯北京总部大厦',
*     address : '北京市海淀区东北旺西路',
*   }
* }

使用示例

Page({
  async onLoad() {
    const app = getApp({ allowDefault: true }); // 获取全局APP实例
    const locInfo = await app.tms.getUserLocation();
    this.setData({ locInfo });
  },
});

setUserLocation(locInfo)

设置用户位置（小程序生命周期内有效）

参数说明

* @param {object} locInfo 用户手动选择的位置
* locInfo参数示例：
* {
*   province: '北京市',
*   cityName: '北京市',
*   cityCode: '100100',
*   latitude: 325.255333,
*   longitude: 116.2545454,
*   adCode: 1212144,
* }
* @returns {void}

使用示例

Page({
  async onLoad() {
    const app = getApp({ allowDefault: true }); // 获取全局APP实例
    const locationManager = app.tms.getLocationManager();
    const locInfo = {
      province: '北京市',
      cityName: '北京市',
      cityCode: '100100',
      latitude: 325.255333,
      longitude: 116.2545454,
      adCode: 1212144,
  }
    locationManager.setUserLocation(locInfo);
  },
});

二、runtime初始化方式

import runtime from '@tencent/tms-runtime';
import core from '@tencent/tms-core';

const config = {
  appEnv: 'test', // 运行环境 test/production
  appVersion: '2021.04.0', // 版本号
  autoLogin: true, // 运行时初始化时是否自动登录车联账号
};

runtime
  .init(config); // 初始化运行时框架
  .then(initConf => {
    core.init(initConf); // 初始化 tms-core
  });

@tencent/tms-runtime 是出行服务小程序/H5运行时框架，init方法用于初始化运行时，方法会返回初始化后的环境信息。运行时会适配各种不同的运行环境，目前支持出行服务小程序，我们正在对基于车联账号体系的兄弟小程序进行适配(我的车)，后续还会适配H5的开发场景。

注意： runtime.init() 方法应在全局只调用一次，在小程序的开发场景下，即在 app.js 中调用；在H5的开发场景下，即在 window.onload 中调用。

三、背景

随着九宫格出行服务小程序业务的快速发展，小程序接入的公司内外部模块日渐繁多，不同模块的技术架构不尽相同。有的模块基于小程序原生开发，有的则基于一些同构框架(如kbone)开发，在将不同架构下开发的子模块集成到出行服务小程序中时，遇到的问题各种各样，五花八门。为了减小各模块集成中的阻力，提升集成效率，我们封装tms-runtime，将出行服务小程序运行时的公共能力进行抽象，并输出简单的api接口，子业务模块无需关注tms-runtime内部逻辑。

四、质量规范

Stylelint & ESlint编码规范问题全部清零

ESlint编码规范采用腾讯通用JS编码规范。

五、开发规范

Commit Log Message规范

腾讯Javascript编码规范

六、一些启发与思考

1. 接口暴露形式

在将tms-runtime中提供的接口暴露给外部时，我们考虑了几种形式：

a. 子模块直接引用 @tencent/tms-core，调用其中接口

这种形式最直观，依赖关系也最清晰。但在实际使用场景中，集成一些基于同构框架开发的子模块时，子模块中若直接引用@tencent/tms-core，经过编译，tms-core的代码会直接包含在生成的子模块代码中，这并不符合我们的预期。我们要求tms-core,tms-runtime,tms-ui作为框架公共封装，只能在小程序主包存在，子模块使用时，从主包根目录的构建目录(miniprogram_npm)中引用即可。

另外，子模块在开发过程中，其实并没有主包下的miniprogram_npm目录，要求子模块在同构项目的开发场景下，来适配我们特殊的开发流程，成本较高，且并不友好。

b. 小程序主包提供公共导出，子模块引用主包导出文件，做依赖注入

这种方式，在我们做整洁架构探索时有过尝试，目前已不推荐使用。

c. 将接口挂载到全局变量，子模块直接从全局变量获取

这种方式看起来是最简单，最能兼容不同开发模式和架构的形式。

参考小程序框架提供的接口能力,都会挂载在全局变量 wx 上,框架并不关心开发者使用何种架构,做何种封装,在需要框架能力的地方,直接调用 wx 即可。

我们将出行服务小程序运行时提供的能力也挂载到全局变量，具体来说，是挂载到全局的app变量上，子模块使用时，只需要通过 getApp() 从app上获取即可，不必做额外的包引入。如此，我们可以保证所有子模块用到的框架能力在全局维护一份。

注意：我们允许将运行时提供的接口挂载到全局app变量上，也仅限于运行时的接口，我们在 tms-runtime 中完成挂在后，会冻结 app.runtime 对象(Object.freeze())，不允许外部代码再对 app.runtime 做修改。