HappyKit

# 使用手册

# 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节点。

注意

v-point不是响应式的，只会在组件mounted中执行一次。

# 客户端追踪器

框架初始化的时候会强制自动初始化追踪器，设计追踪器的目的是为了更好的标识客户端的唯一性。 目前追踪器只维护了一个客户端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的面包屑，需要主动传入该参数。

注意

getBreadcrumb返回的数组不是响应式的。

# 获取单个导航项

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

注意

getNav返回的对象不是响应式的。

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

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

注意

isExistNav返回的值不是响应式的。

# 打开导航项

调用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');

# 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。

警告

token不是响应式数据。

# 用户信息刷新

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

# 用户信息获取

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

# 数据加载

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

# 数据持久化

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

# 数据清除

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

# 高阶用法

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

# 自定义菜单适配器

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

# 自定义追踪器id

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

# 自定义页面id

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

最后一次修改: 3/18/2022, 1:36:51 AM

← 接口说明 →