# 接口说明

# 工厂方法

# createHappyFramework

export declare function createHappyFramework(options?: HappyKitFrameworkOption): HappyKitFramework;

创建核心框架实例

参数
- {HappyKitFrameworkOption} options
  扩展选项，参考HappyKitFrameworkOption章节
返回
- {HappyKitFramework} 框架实例
用法
直接调用后，返回的实例利用vue的插件安装方法app.use(框架实例)装载即可

# createHappySecurity

export declare function createHappySecurity(options?: HappyKitSecurityOption): HappyKitSecurity;

创建核心安全框架实例，可以独立于HappyFramework使用

参数
- {HappyKitSecurityOption} options
  扩展选项，参考HappyKitSecurityOption章节
返回
- {HappyKitSecurity} 框架实例
用法
直接调用后，返回的实例利用vue的插件安装方法app.use(框架实例)装载即可

# createEmptyMenuItem

export declare function createEmptyMenuItem(): MenuItem;

创建一个空的菜单数据结构，用于自定义数据填充。

参数
- 无
返回
- {MenuItem} 菜单数据项实例
用法
直接调用即可

# createDefaultMenuAdapter

export declare function createDefaultMenuAdapter(): MenuAdapter<MenuItem>;

创建默认的菜单数据适配器对象

参数
- 无
返回
- {MenuAdapter<MenuItem> } 菜单数据适配器，泛型为MenuItem
用法
直接调用即可

# createDefaultPageIdFactory

export declare function createDefaultPageIdFactory(framework: HappyKitFramework): PageIdFactory;

创建默认的页面id生成工厂对象，默认是通过md5(url)实现

参数
- {HappyKitFramework} framework
  框架实例作为上下文对象
返回
- {PageIdFactory} 页面id工厂实例
用法
调用后可以得到默认的页面id生成工厂

# createDefaultTrackerIdFactory

export declare function createDefaultTrackerIdFactory(framework: HappyKitFramework): TrackerIdFactory;

创建默认的追踪Id生成工厂，默认是通过uuid实现

参数
- {HappyKitFramework} framework
  框架实例作为上下文对象
返回
- {TrackerIdFactory} 追踪id工厂实例
用法
调用后可以得到默认的追踪id生成工厂

# createDefaultRouterInterceptor

export declare function createDefaultRouterInterceptor(options: RouterInterceptorOption): RouterInterceptor;

创建默认的路由拦截器对象

参数
- {RouterInterceptorOption} options
  路由拦截器选项，详细参见RouterInterceptorOption章节
返回
- {RouterInterceptor} 路由拦截器对象
用法
在路由对象创建后，在路由router.beforeEach或者router.afterEach回调中调用即可

# injectRoutes

export declare function injectRoutes(options: RouterInjectOption):void;

路由注入函数

参数
- {RouterInjectOption} options
  路由注入选项，详细参见RouterInjectOption章节
返回
- {PageIdFactory} 页面id工厂实例
用法
在路由对象和框架创建后调用即可

# upgradeRouter

export declare function upgradeRouter(framework: HappyKitFramework, router: Router): HappyKitRouter;

路由升级函数，用于扩展vue-router

参数
- {HappyKitFramework} framework
  框架作为上下文
- {Router} router
  vue-router实例
返回
- {HappyKitRouter} 升级后的路由实例
用法
在路由对象和框架创建后调用即可，在需要调用扩展方法的情况下需要做类型断言，
比如(router as HappyKitRouter).push()

# 接口定义

# MenuType

/**
 * 菜单类型
 */
export declare enum MenuType {
    MENU = 0,           //菜单
    POINT = 1           //权限点
}

# LinkTarget

/**
 * 链接跳转类型
 */
export declare enum LinkTarget {
    SELF = 0,           //刷新掉当前页面打开
    TAB = 1,            //在内部的标签页打开
    BLANK = 2           //在新的浏览器标签页打开
}

# NavCloseType

/**
 * 导航项关闭类型
 */
export declare enum NavCloseType {
    SELF = 0,           //关闭点击
    LEFT = 1,           //关闭激活项的左侧所有标签
    RIGHT = 2,          //关闭激活项的右侧所有标签
    OTHER = 3,          //关闭除了激活项标签的所有标签
    ALL = 4             //关闭全部标签
}

# RouterInterceptorType

/**
 * 路由拦截类型
 */
export declare enum RouterInterceptorType {
    BEFORE = 0,         //前置拦截
    AFTER = 1           //后置拦截
}

# HTTPInterceptorType

/**
 * HTTP请求拦截类型
 */
export declare enum HTTPInterceptorType {
    BEFORE = 0,         //前置拦截
    AFTER = 1           //后置拦截
}

# StorageEngine

/**
 * 存储引擎类型
 */
export enum StorageEngine {
  LOCAL_STORAGE = 0,    //localStorage
  SESSION_STORAGE = 1,  //sessionStorage
}

# MenuItem

/**
 * 菜单数据结构
 */
export declare interface MenuItem {
    /**
     * 菜单id
     * 框架自动生成
     */
    menuId: string;
    /**
     * 菜单名称
     */
    name: string;
    /**
     * 图标
     */
    icon: string;
    /**
     * 相对路径
     * 生成路由路径拼接时使用
     */
    path: string;
    /**
     * 视图组件的相对路径
     */
    view: string;
    /**
     * 是否为路由节点
     */
    isRouter: boolean;
    /**
     * 是否需要开启缓存
     */
    isKeepalive: boolean;
    /**
     * 菜单类型
     */
    type: MenuType;
    /**
     * 是否为外部链接
     */
    externalLink: boolean;
    /**
     * 外部链接跳转类型
     */
    linkTarget: LinkTarget;
    /**
     * 外部链接地址
     */
    externalLinkAddress: string;
    /**
     * 是否为隐藏路由
     */
    hide: boolean;
    /**
     * 是否为首页
     */
    isHome: boolean;
    /**
     * 按钮权限控制key
     */
    permissionKey: string;
    /**
     * 子菜单数组
     */
    children: MenuItem[];
    
    /**
     * 预处理后的数据
     * 使用上面的数据经过预处理后的数据
     */

    /**
     * 路由路径
     */
    routerPath: string;
    /**
     * 菜单路径
     */
    menuPath: MenuItem[];
    /**
     * 面包屑路径
     */
    breadcrumb: MenuItem[];
    /**
     * 按钮权限列表
     */
    buttonList: MenuItem[];
    /**
     * 按钮权限map
     */
    buttonsMap: Map<string, MenuItem>;
    /**
     * 可扩展属性
     */
    [propName: string]: any;
}

# Tracker

/**
 * 追踪器数据结构
 */
export declare interface Tracker {
    /**
     * 客户端id
     */
    clientId: string;
}

# NavItem

/**
 * 导航项数据结构
 */
export declare interface NavItem {
    /**
     * 页面id
     * 由页面id工厂生成
     */
    pageId: string;
    /**
     * 导航项的标题
     */
    title: string;
    /**
     * 路由前往的目标
     * 可以是字符串路由路径，也可以是路由对象
     */
    to: any;
    /**
     * 所关联的菜单项
     */
    menuItem: MenuItem;
}

# Adapter<T>

/**
 * 通用适配器
 */
export declare interface Adapter<T> {
    /**
     * 转换方法
     * @param rawData 原始数据
     */
    convert(rawData: any): T[];
}

# MenuAdapter<T>

/**
 * 菜单数据适配器
 */
export declare interface MenuAdapter<T> {
    /**
     * 转换方法
     * @param rawData 原始数据
     */
    convert(rawData: any): {
        /**
         * 路由数组
         */
        routeMappingList: T[]; 
        /**
         * 经过适配器转换后的数组
         */
        menuTreeConverted: T[];
        /**
         * 菜单id和菜单项的map
         */
        menuIdMappingMap: Map<string, T>;
    };
}

# HappyKitNavEvent

/**
 * 导航项相关事件
 */
export declare interface HappyKitNavEvent {
    /**
     * 回调方法类型
     * @param removedNavs 移除的导航项
     * @param needNavs    需要前往的导航项
     */
    (removedNavs: NavItem[], needNavs: NavItem[]): void;
}

# HappyKitMenuEvent

/**
 * 菜单项相关事件
 */
export declare interface HappyKitMenuEvent {
    /**
     * 回调方法类型
     * @param menuItems   返回的菜单项
     */
    (menuItems: MenuItem[]): void;
}

# CurrentMenuRoute

/**
 * 当前菜单路由
 * 响应式结构
 */
export declare type CurrentMenuRoute = Ref<NavItem | null>

# PageIdFactory

/**
 * 页面id工厂结构
 */
export declare interface PageIdFactory {
    /**
     * 框架上下文
     */
    framework: HappyKitFramework;
    /**
     * id生成方法
     * @param uniqueString 唯一字符串
     */
    generate(uniqueString: string): string;
    /**
     * 获取将要前往的id
     * @param uniqueString to 前往的目的
     */
    getNextPageId(to: any): string;
}

# TrackerIdFactory

/**
 * 追踪id工厂结构
 */
export declare interface TrackerIdFactory {
  /**
   * 框架上下文
   */
  framework: HappyKitFramework
  /**
   * id获取方法
   * 如果需要从服务端获取的话，请使用同步请求async/await
   */
  getId(): string
}

# HappyKitFrameworkOption

/**
 * 核心框架选项数据结构
 */
export declare interface HappyKitFrameworkOption {
    /**
     * vue3的实例
     */
    app?: App;
    /**
     * 可选的菜单数据适配器实例
     */
    menuAdapter?: MenuAdapter<MenuItem>;
    /**
     * 可选的菜单id工厂实例
     */
    pageIdFactory?: PageIdFactory;

  /**
   * 可选的追踪id工厂实例
   */
    trackerIdFactory?: TrackerIdFactory
    /**
     * 可扩展属性
     */
    [propName: string]: any;
}

# HappyKitFramework

/**
 * 框架
 */
export declare interface HappyKitFramework {
  /**
   * 初始化属性
   */
  options: HappyKitFrameworkOption
  /**
   * 菜单树
   */
  menuTree: Ref<MenuItem[]>
  /**
   * 导航列表
   */
  navigatorList: Ref<NavItem[]>
  /**
   * 路由列表
   */
  routeMappingList: Ref<MenuItem[]>
  /**
   * 菜单id映射表
   * 提高查找速度
   */
  menuIdMappingMap: Ref<Map<string, MenuItem>>
  /**
   * 当前路由
   */
  currentMenuRoute: CurrentMenuRoute
  /**
   * 路由初始化完成标记
   */
  routerInitiated: boolean
  /**
   * 客户端追踪器
   */
  tracker: Tracker

  /**
   * 初始化器
   * @param options
   */
  init(options?: HappyKitFrameworkOption): void

  /**
   * 设置菜单树
   * @param rawData 原始数据
   * @param dataAdapter 数据适配器，提供默认的数据适配器
   */
  setMenuTree(rawData: any, dataAdapter?: MenuAdapter<MenuItem>): void

  /**
   * 设置当前的菜单路由
   * @param currentMenuRoute
   */
  setCurrentMenuRoute(currentMenuRoute: NavItem | null): void

  /**
   * 获取菜单树
   */
  getMenuTree(): Ref<MenuItem[]>

  /**
   * 获取路由列表
   */
  getRouteMappingList(): Ref<MenuItem[]>

  /**
   * 获取当前菜单路由
   */
  getCurrentMenuRoute(): CurrentMenuRoute

  /**
   * 获取面包屑
   * @param pageId 如果不传，默认获取当前激活的
   */
  getBreadcrumb(pageId?: string): MenuItem[]

  /**
   * 获取追踪器实例
   */
  getTracker(): Tracker

  /**
   * 初始化追踪器
   */
  initTracker(): void

  /**
   * 刷新客户端id
   */
  refreshClientId(): string

  /**
   * 获取导航列表
   */
  getNavList(): Ref<NavItem[]>

  getNav(pageId: string): NavItem | null

  /**
   * 是否存在该导航项
   * @param pageId
   */
  isExistNav(pageId: string): boolean

  /**
   * 打开新的导航项
   *
   * #case1:
   * 同一个路由，只能打开一个页面
   * #case2:
   * 同一个路由，打开多个页面，不同参数
   *
   * @param to 前往目标
   * @param menuItem
   * @param title 可选的标题
   */
  openNav(to: any, menuItem: MenuItem, title?: string): NavItem | null

  /**
   * 关闭导航项
   * @param type
   * @param pageId
   * @param event
   */
  closeNav(
    type: NavCloseType,
    pageId?: string,
    event?: HappyKitNavEvent,
  ): void

  /**
   * 点击导航项
   * @param pageId
   * @param event
   */
  clickNavItem(pageId: string, event?: HappyKitNavEvent): void

  /**
   * 点击菜单项
   * @param menuId
   * @param event
   */
  clickMenuItem(menuId: string, event?: HappyKitMenuEvent): void

  /**
   * vue插件方法
   * @param app
   */
  install(app: App): void

}

# RouterInjectOption

/**
 * 路由注入选项
 */
export declare interface RouterInjectOption {
    /**
     * 父级路由
     * 子路由全部注入在该路由下
     */
    parentRoute: RouteRecordRaw;
    /**
     * 待注入的路由实例
     */
    router?: Router;
    /**
     * 待注入的路由数组
     */
    routes: MenuItem[];
    /**
     * 视图组件加载器
     * @param view 视图组件路径
     */
    viewLoader(view: string): any;
}

# RouterInterceptorOption

/**
 * 路由拦截器选项
 */
export declare interface RouterInterceptorOption {
    /**
     * 框架实例
     * 作为上下文
     */
    framework: HappyKitFramework;
    /**
     * 路由拦截类型
     */
    interceptorType: RouterInterceptorType;
    /**
     * 数据加载器
     */
    dataLoader?(): any;
    /**
     * 数据加载失败回调
     */
    dataLoadFailureHandler?(): void;
    /**
     * 路由注入参数
     * 用于拦截时需要注入的情况
     */
    routerInjectOption?: RouterInjectOption;
}

# RouterInterceptor

/**
 * 路由拦截器
 */
export declare interface RouterInterceptor {
    /**
     * 路由拦截参数
     */
    options: RouterInterceptorOption;
    /**
     * 拦截方法
     * @param to
     * @param from
     * @param next
     */
    filter(to: RouteLocationNormalized, from: RouteLocationNormalized, next?: NavigationGuardNext): void;
}

# HappyKitRouter

/**
 * vue-router路由子类
 * HappyKitRouter继承Router
 */
export declare interface HappyKitRouter extends Router {
    framework: HappyKitFramework;

  /**
   * 重载Router中的push
   * @param to 
   * @param title 导航项中自定义的标题
   */
    push(to: RouteLocationRaw, title?: string): Promise<NavigationFailure | void | undefined>;
}

# User

/**
 * 用户对象
 */
export declare type User = any

# HappyKitSecurityOption

/**
 * 安全框架选项
 */
export declare interface HappyKitSecurityOption {
  /**
   * 存储引擎
   */
  storageEngine?: StorageEngine
}

# HappyKitSecurity

/**
 * 框架安全接口
 */
export declare interface HappyKitSecurity {
  /**
   * 配置参数
   */
  options: HappyKitSecurityOption
  /**
   * 用户对象
   */
  user: Ref<User | null>
  /**
   * token
   */
  token: string

  /**
   * 初始化方法
   * @param options
   */
  init(options?: HappyKitSecurityOption): void

  /**
   * 获取存储器
   */
  getStorage(): Storage

  /**
   * 刷新用户数据
   * @param user
   */
  refreshUser(user: User): void

  /**
   * 刷新用户token
   * @param token
   */
  refreshToken(token: string): void

  /**
   * 获取用户对象
   */
  getUser(): Ref<User | null>

  /**
   * 获取用户token
   */
  getToken(): string

  /**
   * 登录
   * @param token
   * @param user
   */
  signIn(token: string, user: User): void

  /**
   * 登出
   */
  signOut(): void

  /**
   * 冷数据加载
   */
  loadFromStorage(): void
  /**
   * 热数据写入
   */
  saveIntoStorage(): void

  /**
   * 清除存储
   */
  flushStorage(): void
  /**
   * vue插件
   * @param app
   */
  install(app: App): void
}

← 使用手册常见问题 →