# 使用手册

# 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