Luck-Report 业务系统集成

本文档介绍如何将 Luck-Report 报表功能集成到现有业务系统中，分为后端和前端两个部分

报表源码

Luck-Report 体验地址：https://www.quzhe.top/luck-report/report/designer (opens new window)
Luck-Report 源码下载：https://gitee.com/LuckyPools/luck-report (opens new window)
Luck-Report 技术交流群：849697890

后端集成

1.1 安装依赖包

使用 Maven install 指令打包 luck-report-server 项目，并将jar包安装到本地 Maven 仓库。

bash

# 进入 luck-report-server 目录
cd luck-report-server

# 执行 Maven install
mvn clean install -DskipTests

1.2 引入 Maven 依赖

在业务系统项目的 pom.xml 文件中引入 Luck-Report 依赖：

xml

<!-- 报表依赖 -->
<dependency>
    <groupId>com.luck.cloud</groupId>
    <artifactId>luck-report-web</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- 根据项目实际需求添加数据库驱动，以 mysql 为例 -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.17</version>
</dependency>

1.3 配置文件

在 application.yml 配置文件中添加 Luck-Report 和数据源配置：

yaml

luck-report:
  servletPrefix: report
  # 报表文件存储目录，请根据您的实际存储路径修改，确保该目录存在且有读写权限
  fileStoreDir: E:/luckStudio/IO/report
  debug: true

spring:
  datasource:
    # 数据库用户名，根据您的数据库账号修改
    username: root
    # 数据库密码，根据您的数据库密码修改
    password: root
    # 数据库连接地址，根据您的数据库地址修改
    url: jdbc:mysql://localhost:3306/luck_report?serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=utf-8
    driver-class-name: com.mysql.cj.jdbc.Driver

配置说明：

配置项	说明
`servletPrefix`	报表接口前缀
`fileStoreDir`	报表文件存储目录，需确保有读写权限
`debug`	是否开启调试模式

1.4 添加自定义数据源

创建数据源配置类，实现 BuildinDatasource 接口，提供内部数据源。

java

package com.luck.product.boot.config;

import com.luck.report.core.definition.datasource.BuildinDatasource;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Configuration;

import javax.annotation.Resource;
import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.SQLException;

/**
 * 内置数据源配置
 */
@Configuration
public class DatasourceConfig implements BuildinDatasource {
    @Resource
    DataSource dataSource;
    private final Logger log = LoggerFactory.getLogger(getClass());

    @Override
    public String name() {
        return "myUReportDatasource";
    }

    @Override
    public Connection getConnection() {
        try {
            return dataSource.getConnection();
        } catch (SQLException e) {
            log.error("数据源获取连接失败！");
        }
        return null;
    }
}

1.5 添加自定义缓存

缓存 - 分布式缓存配置

前端集成

2.1 打包 Luck-Report-UI

打包前端项目

bash

# 进入前端项目目录
cd luck-report-ui

# 执行 lib 打包命令
npm run build:lib

打包完成后，会在前端项目目录下生成 dist 文件夹。

2.2 复制文件到业务系统

在业务系统前端项目的 public 目录下新建 libs\luck-report 文件夹：

public/
└── libs/
    └── luck-report/
        ├── luck-report-lib.umd.min.js
        └── assets/

复制 dist 目录中的以下文件到 libs\luck-report 文件夹：

luck-report-lib.umd.min.js
assets 文件夹

2.3 引入脚本文件

在业务系统前端项目 public\index.html 中引入 Luck-Report 脚本：

html

<!DOCTYPE html>
<html lang="">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    <link rel="icon" href="<%= BASE_URL %>favicon.ico">
    <title><%= htmlWebpackPlugin.options.title %></title>
      
    <!-- Luck-Report 配置开始 -->
    <script>
      window.__luck_report_public_path__ = '<%= BASE_URL %>libs/luck-report/';
    </script>
    <script src="<%= BASE_URL %>libs/luck-report/luck-report-lib.umd.min.js"></script>
    <!-- Luck-Report 配置结束 -->
      
  </head>
  <body>
    <div id="app"></div>
  </body>
</html>

2.4 创建页面组件

设计器页面 src/views/report/designer/index.vue：

vue

<template>
  <div class="report-designer-container">
    <luck-designer
      ref="designer"
      :report-path="reportPath"
      :locale="locale"
      class="designer-wrapper"
    />
  </div>
</template>

<script>
export default {
  name: 'ReportDesigner',
  computed: {
    reportPath() {
      return this.$route.query.reportPath || '';
    },
    locale() {
      return this.$route.query.locale || 'zh';
    }
  }
};
</script>

<style scoped>
.report-designer-container {
  width: 100%;
  height: 100vh;
  overflow: hidden;
}

.designer-wrapper {
  display: block;
  width: 100%;
  height: 100%;
}
</style>

预览页面 src/views/report/preview/index.vue：

vue

<template>
  <div class="report-preview-container">
    <luck-preview
      ref="preview"
      :locale="locale"
      class="preview-wrapper"
    />
  </div>
</template>

<script>
export default {
  name: 'ReportPreview',
  computed: {
    locale() {
      return this.$route.query.locale || 'zh';
    }
  }
};
</script>

<style scoped>
.report-preview-container {
  width: 100%;
  height: 100vh;
  overflow: hidden;
}

.preview-wrapper {
  display: block;
  width: 100%;
  height: 100%;
}
</style>

2.5 添加路由配置

在路由配置文件中添加设计器和预览页的路由，例如：

javascript

import ReportDesigner from '@/views/report/designer/index.vue'
import ReportPreview from '@/views/report/preview/index.vue'

const routes = [
  {
    path: '/report/designer',
    name: 'ReportDesigner',
    component: ReportDesigner
  },
  {
    path: '/report/preview',
    name: 'ReportPreview',
    component: ReportPreview
  }
]

2.6 配置 LuckReportLib

创建配置文件 src/luckReport.js：

javascript

import router from './router';

function configureLuckReport() {
    const LuckReportLib = window['luck-report-lib'];
    
    // 必须先设置 lib 模式
    LuckReportLib.setLibMode(true);

    // 配置请求 baseURL，按业务系统接口地址调整
    // 注意需要适配 luck-report.servletPrefix 请求前缀
    LuckReportLib.requestAdapter.setBaseURL('/api/report');

    // 配置请求拦截器
    // 按业务系统认证逻辑调整
    LuckReportLib.requestAdapter.addRequestInterceptor(
        (config) => {
            const token = "认证信息";
            if (token) {
                config.headers['Authorization'] = 'Bearer ' + token;
            }
            return config;
        },
        (error) => {
            return Promise.reject(error);
        }
    );

    // 配置 Vue Router（导航适配器需要）
    LuckReportLib.navigationAdapter.setVueRouter(router);

    // 配置路由映射，按业务系统路由名称调整
    LuckReportLib.navigationAdapter.setRouteMapping({
        Preview: 'ReportPreview',
        Designer: 'ReportDesigner'
    });

    window.LuckReportLib = LuckReportLib;
}

export { configureLuckReport };

在 main.js 中引入并执行配置：

javascript

import Vue from 'vue';
import App from './App.vue';
import router from './router';
import store from './store';
import {configureLuckReport} from './luckReport';

// 配置 luck-report-lib
configureLuckReport();

new Vue({
    el: '#app',
    router,
    store,
    render: h => h(App)
});

配置说明：

配置项	说明
`setLibMode(true)`	设置为 lib 模式，必须首先调用
`setBaseURL`	配置后端接口地址前缀
`addRequestInterceptor`	配置请求拦截器，用于添加认证信息等
`setVueRouter`	配置 Vue Router 实例，用于导航
`setRouteMapping`	配置路由映射，将内部导航目标映射到业务系统路由

验证集成

完成以上配置后，启动后端服务和前端项目，根据您配置的路由地址访问验证集成是否成功：

设计器页面：访问 http://localhost:端口/report/designer
预览页面：访问 http://localhost:端口/report/preview?reportPath=报表路径

若能正确展示报表设计器和预览界面，则表明集成成功。

常见问题

文件写入权限问题：如果提示当前权限不足，无法写入文件，请检查配置文件中的 fileStoreDir 路径是否有可读可写权限。
前端打包依赖问题：前端打包时如果遇到依赖问题，可以尝试删除 node_modules 文件夹和 package-lock.json 文件，重新运行 npm i。
路由跳转问题：确保 setRouteMapping 中配置的路由名称与实际路由定义的 name 一致。
接口请求问题：检查 setBaseURL 配置的接口地址是否正确，以及请求拦截器中的认证信息是否正确添加。

如遇到无法解决的问题，请到项目仓库 Issues 或群聊中反馈，会不定时进行解答。

Luck-Report 业务系统集成 ​

报表源码 ​

后端集成 ​

1.1 安装依赖包 ​

1.2 引入 Maven 依赖 ​

1.3 配置文件 ​

1.4 添加自定义数据源 ​

1.5 添加自定义缓存 ​

前端集成 ​

2.1 打包 Luck-Report-UI ​

2.2 复制文件到业务系统 ​

2.3 引入脚本文件 ​

2.4 创建页面组件 ​

2.5 添加路由配置 ​

2.6 配置 LuckReportLib ​

验证集成 ​

常见问题 ​

Luck-Report 业务系统集成

报表源码

后端集成

1.1 安装依赖包

1.2 引入 Maven 依赖

1.3 配置文件

1.4 添加自定义数据源

1.5 添加自定义缓存

前端集成

2.1 打包 Luck-Report-UI

2.2 复制文件到业务系统

2.3 引入脚本文件

2.4 创建页面组件

2.5 添加路由配置

2.6 配置 LuckReportLib

验证集成

常见问题