快速开始

本页将介绍如何在实际项目中集成 HFLVEditor3 与 HFLVLoader，并通过自定义的 customApi 将你的请求封装无缝接入低代码渲染链路。

安装

npm install hflveditor3 hflvloader

TIP

推荐在已有 Vue 3 项目中接入 HFLVEditor3，而不是单独新建工程。这样可以 直接复用你项目里已经配置好的请求拦截器、鉴权逻辑和错误处理。

在 main.js 中注册插件

以典型的 Vue 3 SPA 为例，你需要在入口文件（如 src/main.js）中注册两个插件：

import { createApp } from 'vue'
import App from './App.vue'

import HflvEditor3 from 'hflveditor3'
import HflvLoader from 'hflvloader'
import { createCustomApi } from './customApi'

const app = createApp(App)

// 创建 customApi 实例
const customApi = createCustomApi()

// 注册编辑器插件
app.use(HflvEditor3)

// 注册加载器插件，第二个参数传入 customApi
app.use(HflvLoader, customApi)

app.mount('#app')

重要

• 必须先创建 customApi 并作为第二个参数传给 app.use(HflvLoader, customApi)，否则 HFLVLoader 在运行时无法正确执行配置的数据请求。

HFLVLoader 的核心职责是：根据页面JSON配置渲染为真实的 Vue 组件页面，执行配置事件。

为什么需要 customApi？

在事件处理中配置数据请求，在执行这个请求过程中，HFLVLoader 内部并不直接「发 HTTP 请求」，而是把「如何请求」这个能力交给你项目自己的封装。

这样做有几个好处：

• 避免重复配置拦截器：无需在 HFLVLoader 内部重新封装 axios / fetch，只要使用你项目现有的 request 实例。
• 复用已有权限与错误处理：401 / 403、业务错误码、重定向登录页等逻辑，仍然由你项目的 request 拦截器统一处理。
• 可控的缓存与存储策略：qryPageConfigData 可以按你自己的策略做本地缓存、版本控制或持久化。

因此，HFLVLoader 只负责：

「我需要获取页面配置」 → 「渲染成VUE页面」

「我需要获取数据」 → 「调用你提供的 customApi」 → 「拿到 数据并完成渲染展示」

customApi 完整示例

建议在项目中新建 src/customApi.js，集中维护与 HFLVEditor3 / HFLVLoader 相关的接口封装。

// src/customApi.js

// 假设项目已有一个封装好的 request 实例
// 例如基于 axios 封装：已统一处理 baseURL、401/403 拦截、错误提示等
import request from '@/utils/request'

// 可选：原始的 HTTP 客户端（例如 axios.create 出来的实例）
// import rawRequest from '@/utils/rawRequest'

// 简单的内存缓存示例，你也可以替换为 localStorage / IndexedDB 等
const pageConfigCache = new Map()

export function createCustomApi() {
  return {
    /**
     * 根据 pageId 查询页面 JSON 配置
     * 建议带缓存，减少重复请求
     */
    async qryPageConfigData(pageId) {
      if (!pageId) {
        throw new Error('pageId is required')
      }

      // 命中缓存直接返回
      if (pageConfigCache.has(pageId)) {
        return pageConfigCache.get(pageId)
      }

      // 使用项目自己的 request 发起请求
      // 假设后端提供 /api/page-config 接口
      const res = await request({
        url: '/api/page-config',
        method: 'get',
        params: { pageId },
      })

      // 根据你后端的返回结构调整此处
      const config = res?.data?.config || res?.data

      // 写入缓存
      pageConfigCache.set(pageId, config)

      return config
    },

    /**
     * 项目封装好的 request 实例
     * 已经在其他业务模块被广泛使用
     */
    request,

    /**
     * 原始请求实例（可选）
     * 若 HFLVLoader 或未来插件需要更底层能力，可通过此属性访问
     */
    // rawRequest,

    /**
     * 获取 JSON 文件
     * 可用于加载离线模板、示例页面等
     */
    async getJsonFile(path) {
      // 根据需要选择使用 request 还是原始 fetch
      return request({
        url: path,
        method: 'get',
      })
    },

    /**
     * 获取通用文件（如图片、资源文件等）
     */
    async getFile(path, options = {}) {
      // 这里示例使用浏览器原生 fetch，你也可以换成项目封装的 request
      const res = await fetch(path, options)
      if (!res.ok) {
        throw new Error(`Failed to fetch file: ${path}`)
      }
      return res
    },
  }
}

customApi 能力说明

下面是 HFLVLoader 期望从 customApi 中获取的核心能力说明（可根据实际实现细化）：

字段名	类型	是否必需	说明
qryPageConfigData	Function	是	根据 pageId 查询页面 JSON 配置，建议带缓存，返回标准化的页面描述对象。项目引用 HFLVComp 组件库时，子页面容器组件会调用该方法；若不引用，可不提供或提供空函数
request	Object/Function	是	你项目已经封装好的请求实例（如 axios 实例），已内置拦截器、权限校验和错误处理。
rawRequest	Object/Function	否	原始请求实例，用于某些需要绕过全局封装的高级场景。
getJsonFile	Function	否	用于加载本地或远程 JSON 文件（如示例页面、模板库）。
getFile	Function	否	通用文件获取方法，可用于图片、静态资源等加载。

TIP

qryPageConfigData 的返回结构建议与编辑器生成的 JSON Schema 对齐，这样可以做到「所见即所得」：
在 HFLVEditor3 里配置好的页面结构，加载到运行时后无需再做二次转换。 建议查询使用本地高效的缓存(localStorage / IndexedDB等)，减少交互次数和访问速度。尤其在通过子页面容器实现构建自定义复合组件时，JSON配置通常小，但访问频率高。

关于拦截器与错误处理

HFLVLoader 在设计上不会强绑任何请求库，也不会在内部添加额外的 401 / 403 或业务错误拦截逻辑。
所有这些行为都应当在你项目自己的 request 封装中完成。

为什么要传递 customApi？

通过传入 customApi：

• 不需要在 HFLVLoader 里重复配置 axios / fetch / token 等细节；
• 401 / 403、登录态失效、全局错误提示等都沿用你项目现有的统一方案；
• 未来如需切换请求实现（例如从 axios 改为 fetch），只需调整 customApi 内部，不影响 HFLVEditor3 / HFLVLoader 的调用方式。

完成以上步骤后，你就可以在业务页面中通过 HFLVLoader 提供的组件（例如运行时容器组件）加载页面JSON配置，实现 「编辑器设计 → JSON 配置 → 运行时渲染」 的完整闭环。