核心引擎 #

happykit不依赖任何第三方的UI库，开发者可以使用自己喜欢的UI库进行开发。happykit主要关注数据状态的维护，以及核心逻辑的实现； 通过数据适配器的思想进行数据的交互，通过提供类似工厂的方法进行实例创建。

playground #

https://playground.happykit.org

HappyKitFramework #

创建实例 #

调用createHappyFramework进行创建实例，默认可以不传任何参数。在创建时可以自定义传入对象

{
    app: App, // vue实例
    menuAdapter: MenuAdapter<MenuItem>, // 菜单数据适配器
    pageIdFactory: PageIdFactory, // 页面id工厂
    trackerIdFactory: TrackerIdFactory, // 追踪器id工厂
    permissionDirectiveName: string, // 权限点指令名称
    autoRegisterDirective: boolean // 是否自动注册权限点指令
}

vue安装方法 #

简单通过app.use方法安装即可。框架会把自己挂载到vue全局变量中： app.config.globalProperties.$happykit。

权限指令v-point #

v-point权限指令是用于控制dom节点的显示隐藏。

指令注册 #

该指令在app.use挂载的时候默认同步进行自动注册。如果需要取消自动注册指令， 或者需要对指令更名，也是很简单的。在框架初始化的时候，可以通过参数设定。

{
    permissionDirectiveName: 'point', // 权限点指令名称
    autoRegisterDirective: true // 是否自动注册权限点指令
}

指令用法 #

只需要在dom节点上使用即可，例如：

<button v-point="'submit'">保存</button>

v-point会根据当前路由所对应的菜单节点进行查找，如果找不到就删除dom节点。

客户端追踪器 #

框架初始化的时候会强制自动初始化追踪器，设计追踪器的目的是为了更好的标识客户端的唯一性。 目前追踪器只维护了一个客户端id， 该id由框架默认的trackerIdFactory生成，该id会持久化到localStroage 中，以key为clientId存储。

用处 #

调用getTracker得到追踪器实例，然后您可以把该id携带在http请求上， 还可以用在websocket上作为客户端连接的唯一id。

刷新客户端Id #

有时候可能需要强制刷新本地的追踪器id，可以调用refreshClientId，它会完成刷新并且持久化。

获取菜单树数据 #

调用getMenuTree返回响应式数组ref([])，它的类型签名为Ref<MenuItem[]>。 得到该变量后，您可以直接利用递归组件进行渲染树。

刷新菜单树数据 #

调用setMenuTree(rawData: any, dataAdapter?: MenuAdapter<MenuItem>)可以主动初始化菜单树， 并且同步会刷新框架内部维护的路由列表routeMappingList 和菜单id映射表menuIdMappingMap， 但是这不会刷新vue-router中的路由表。

获取导航列表数据 #

调用getNavList返回响应式数组ref([])，它的类型签名为Ref<NavItem[]>。 得到该变量后，您可以直接利用v-for进行渲染。

获取动态路由列表 #

调用getRouteMappingList返回响应式数组ref([])，它的类型签名为Ref<NavItem[]>。该数组是一个展平的以为数组。 您可以使用injectRoutes进行路由注入。

获取当前激活的导航项 #

调用getCurrentMenuRoute返回响应式对象Ref<NavItem | null>。

获取面包屑 #

调用getBreadcrumb默认返回当前路由的面包屑，如果需要指定pageId的面包屑，需要主动传入该参数。

获取单个导航项 #

调用getNav，传入pageId可以获取单个导航项。

检查某个导航项是否存在 #

调用isExistNav，传入pageId可以获取boolen值。

打开导航项 #

调用openNav(to: any, menuItem: MenuItem, title?: string),to参数可以是拼接好的路由地址，也可以是以对象形式传入，该参数等同于router.push方法中的to参数； menuItem是目标路由所对应的菜单项；title是可选的，默认会使用menuItem.name属性，如果自定义传入则使用自定义传入的值，该值会影响导航项中的title属性。

关闭导航项 #

调用closeNav(type: NavCloseType, pageId?: string, event?: HappyKitNavEvent)，可以通过不同方式关闭导航项。
通过NavCloseType枚举进行确定关闭的方式，当传入NavCloseType.ALL的时候，可以不传入pageId。

• SELF 关闭指定的导航项
• LEFT 关闭当前导航项左侧的所有导航项（不包含当前）
• RIGHT 关闭当前导航项右侧侧的所有导航项（不包含当前）
• OTHER 关闭当前导航项除外的所有导航项
• ALL 关闭全部导航项

一般在关闭导航项后需要做路由的跳转，因此框架提供一个回调事件来处理。该事件会返回需要跳转的导航项列表，和已经关闭的导航项列表。

切换导航项 #

调用setCurrentMenuRoute(currentMenuRoute: NavItem | null)，传入导航项即可。 该调用不会触发路由的切换，需要手动调用router.push进行同步。

菜单项点击事件代理方法 #

调用clickMenuItem(menuId: string, event?: HappyKitMenuEvent)，可以减少对框架数据状态的关注。 在event中实现自定义逻辑。事件详见HappyKitMenuEvent。

导航项点击事件代理方法 #

调用clickNavItem(pageId: string, event?: HappyKitNavEvent)，可以减少对框架数据状态的关注。 在event中实现自定义逻辑。事件详见HappyKitNavEvent。

HappyKitRouter #

HappyKitRouter集成了vue的Router，目前扩展了push的重载方法和集成了框架实例。

创建实例 #

HappyKitRouter没有主动实例化方法，需要使用upgradeRouter,把Router升级为HappyKitRouter，保留了全部原始特性。 这个路由升级不是必须的。

页面跳转 #

升级路由后，现在支持2种路由跳转方法。

push(to: RouteLocationRaw): Promise<NavigationFailure | void | undefined>
// 扩展的可选的title参数是作为导航项的标题
push(to: RouteLocationRaw, title?: string): Promise<NavigationFailure | void | undefined>

重载方法的调用需要做类型断言：

// 像这样
(router as HappyKitRouter).push('/path');
(router as HappyKitRouter).push({path:'/path'});
(router as HappyKitRouter).push({path:'/path',query:{},params:{}},'title');

RouteAlive #

调用该方法可以注册并且获取路由缓存组件RouteAlive，该组件可以内嵌到RouterView中替代KeepAlive，同时提供了API方法操作缓存。

function useRouteAlive(options: HappyKitRouteCacheOption):{
    RouteAlive,
    removeComponentCache,
    getCached,
    getIncludes
}

本质上RouteAlive是对KeepAlive的二次封装。

HappyKitSecurity #

安全框架，独立于核心框架，可以单独使用。

实例化 #

调用createHappySecurity进行创建实例，默认可以不传任何参数。在创建时可以自定义传入对象

{
  /**
   * 存储引擎
   */
  storageEngine: StorageEngine
}

默认使用localStorage。

vue安装方法 #

简单通过app.use方法安装即可。框架会把自己挂载到vue全局变量中： app.config.globalProperties.$security。

登录 #

调用signIn(token: string, user: User): void，把数据写入框架中。

注销 #

调用signOut(): void，把数据从框架中清除。

Token刷新 #

调用refreshToken(token: string): void，把token刷新进框架，并且根据引擎类型持久化。

Token获取 #

调用getToken(): string，返回token。

用户信息刷新 #

调用refreshUser(user: User): void，把用户信息对象刷新进框架，并且根据引擎类型持久化。

用户信息获取 #

调用getUser(): Ref<User | null>，返回响应式用户信息对象。可以用来直接渲染。

数据加载 #

调用loadFromStorage(): void，从存储中读取全部数据到内存中。

数据持久化 #

调用saveIntoStorage(): void，把内存中的数据全部持久化到存储中。

数据清除 #

调用flushStorage(): void，清空存储中框架的全部数据。

高阶用法 #

高阶用法可以更加灵活的更改一些配置和策略。

自定义菜单适配器 #

由于服务端返回的菜单数据结构和框架中的数据结构不一样，因此我们需要自定义适配器。
实现MenuAdapter<MenuItem>这个接口即可。然后在框架实例化的时候作为参数传入，覆盖掉默认的参数数据适配器即可。

自定义追踪器id #

实现TrackerIdFactory这个接口即可。然后在框架实例化的时候作为参数传入，覆盖掉默认的参数数据适配器即可。

自定义页面id #

实现PageIdFactory这个接口即可。然后在框架实例化的时候作为参数传入，覆盖掉默认的参数数据适配器即可。