mars3d在vue3.0生态上开发了两个gis相关开源项目 mars3d-vue-example 和 mars3d-vue-project，在这两个项目中widget都是非常重要的一个模块。通过widget可以在复杂的场景下非常清晰的管理功能模块之间的互斥关系，管理内存，完成不同的功能模块之间的解耦，并且可以实现功能模块之间的交互。下面就来介绍一下，widget模块的使用。

    前置依赖：使用widget模块，则必须依赖vuex，通过vuex实现widget管理、交互等。

    widget相关的代码一般会被放置在src/widgets目录下，按照功能或者业务来新建子目录管理widget代码，一般每个目录下的 index.vue 就是此widget的入口，通常也会包括一个map.ts文件用于编写地图相关代码。在某些特殊的场景下，也会将多个vue文件放置在同一个widget目录下，方便共享map.ts的命名空间，后面会针对这些特殊场景具体介绍。下面是一个标准的widget目录位置和结构
    截屏2022-02-25 下午9.53.12.png
    创建好widget之后，下面就应该来配置widget，标准写法是在入口main.ts 同级新建widget-store.ts 文件，下面这个示例演示了这个文件的基本结构和一个widget的配置

    1. import { defineAsyncComponent, markRaw } from "vue"
    2. import { WidgetState } from "@mars/common/store/widget"
    3. import { StoreOptions } from "vuex"
    5. const store: StoreOptions<WidgetState> = {
    6.   state: {
    7.     // 自定义widget的默认值
    8.     defaultOption: {},
    9.     // widgets 配置列表
    10.     widgets: [
    11.       {
    12.         // required widget使用的异步组件
    13.         component: markRaw(defineAsyncComponent(() => import("@mars/widgets/demo/menu/index.vue"))),
    14.         // required widget的唯一标识
    15.         name: "menu",
    16.         // 是否可以被自动关闭 default true
    17.         autoDisable: false,
    18.         // 此widget打开时，是否自动关闭其他可关闭的widget default true
    19.         disableOther: false,
    20.         /*
    21.          * widget分组, widget打开时会强制关闭所有同组的其他widget
    22.          * 优先级高于 disableOther autoDisable
    23.         */ 
    24.         group: "demo"
    25.       }
    26.     ],
    27.     // 默认打开的widget
    28.     openAtStart: ["menu"]
    29.   }
    30. }
    32. export default store

    WidgetState接口定义如下

    2. // 为 store state 声明类型
    3. export interface DefaultOption {
    4.   autoDisable?: boolean
    5.   disableOther?: boolean | string[]
    6.   group?: string // group相同的widget一定是互斥的
    7.   meta?: any // 额外参数 不会在每次关闭后清除
    8. }
    10. export interface Widget {
    11.   name: string // 唯一标识
    12.   key?: string // 作为vue diff 环节的key，用于控制组件重载
    13.   component?: any // widget关联的异步组件
    14.   autoDisable?: boolean // 是否能够被自动关闭
    15.   disableOther?: boolean | string[] // 是否自动关闭其他widget,或通过数组指定需要被关闭的widget
    16.   group?: string // group相同的widget一定是互斥的
    17.   visible?: boolean // 显示隐藏
    18.   data?: any // 额外传参 会在每次关闭后清除
    19.   meta?: any // 额外参数 不会在每次关闭后清除
    20. }
    22. export interface WidgetState {
    23.   widgets: Widget[] // widget具体配置
    24.   openAtStart: string[] // 默认加载的widget
    25.   defaultOption?: DefaultOption // 支持配置默认参数
    26. }

    还需要在main.ts中初始化配置

    1. import { createApp } from "vue"
    2. import Application from "./App.vue"
    3. import { injectState, key } from "@mars/common/store/widget"
    4. import { store as testStore, key as testKey } from "@mars/common/store/test"
    5. import store from "./widget-store"
    7. const app = createApp(Application)
    9. // 此处传入key是为了让widget的store有自己的独立命名空间，不影响项目中的其他store
    10. app.use(injectState(store), key)
    11. // 项目中的其他store
    12. app.use(testStore, testKey)
    14. app.mount("#app")

    完成上述配置工作之后，就可以编写具体的widget代码了，widget本身其实就是一个vue组件，原则上只负责ui相关的展示和逻辑，地图相关的代码新建map.ts文件进行逻辑上的解耦，widget提供了api来完成组件和map的交互。下面是一个标准的 widget组件的基本结构。

    1. <template>
    2.  <mars-button class="small-btn" @click="onDraw">绘制</mars-button>
    3. </template>
    5. <script setup lang="ts">
    6. import { onUnmounted, ref } from "vue"
    7. import useLifecycle from "@mars/common/uses/use-lifecycle"
    8. import * as mapWork from "./map"
    10. // 激活map.ts生命周期
    11. useLifecycle(mapWork)
    13. const onClick = () => {
    14.   // 调用 map.ts 中的方法
    15.   mapWork.onDraw()
    16. }
    17. // 监听 map.ts 中抛出的事件，基于 mars3d.BaseClass 类实现
    18. mapWork.eventTarget.on("drawExtent", function (event: any) {
    19.   // 此处用于处理事件
    20.   console.log(event)
    21. })
    23. onUnmounted(() => {
    24.   // 销毁操作
    25. })
    26. </script>
    27. <style lang="less"></style>

    上面代码中的 useLifecycle 是一个比较重要的api，他接受map.ts 的导出模块作为参数，建立了vue和map.ts生命周期的关联。可用的map.ts 可用的生命周期为 onMounted 和 onUnmounted，map.ts 标准结构如下。

    1. import * as mars3d from "mars3d"
    3. let map: mars3d.Map // 地图对象
    5. // 事件对象，用于抛出事件给vue
    6. export const eventTarget = new mars3d.BaseClass()
    8. // 初始化当前业务
    9. export function onMounted(mapInstance: mars3d.Map): void {
    10.   map = mapInstance // 记录map
    11. }
    13. // 释放当前业务
    14. export function onUnmounted(): void {
    15.   map.graphicLayer.clear()
    16.   eventTarget = null
    17.   map = null
    18. }
    20. // 绘制矩形（演示map.js与index.vue的交互）
    21. export function onDraw(): void {
    22.   map.graphicLayer.clear()
    23.   // 绘制矩形
    24.   map.graphicLayer.startDraw({
    25.     type: "rectangle",
    26.     style: {
    27.       fill: true,
    28.       color: "rgba(255,255,0,0.2)",
    29.       outline: true,
    30.       outlineWidth: 2,
    31.       outlineColor: "rgba(255,255,0,1)"
    32.     },
    33.     success: function (graphic: mars3d.graphic.RectangleEntity) {
    34.       const rectangle = graphic.getRectangle({ isFormat: true })
    35.       // 抛出事件可以在vue中进行监听
    36.       eventTarget.fire("drawExtent", { extent: JSON.stringify(rectangle) })
    37.     }
    38.   })
    39. }

    到此我们就初步了解了widget的使用，后续将会介绍，widget如何结合 mar-ui的 dialog 和 pannel 一起使用，以及一些特殊场景的处理。