zvos-print-sdk v1.2.4

打印中心 - 前端 sdk 接入文档

最新 sdk 版本：v1.2.4

sdk 和该文档更新时间：2024.2.4

1. 安装

npm install zvos-print-sdk

2. 引入

import sdk from "zvos-print-sdk";

3. 配置

① baseUrl

【注意】原 sdk 调用接口时默认使用的 baseUrl 是项目本身的 baseUrl（window[process.env.VUE_APP_PAGE_CONFIG].baseUrl），现已移除。

sdk 调用接口时默认使用的 baseUrl 是麓谷生产地址，如果要设置其他 baseUrl，可以在 main.js 中导入包后调用 setBaseUrl 方法。

/**
 * 设置 BaseUrl
 * @param {String} url url
 */
function setBaseUrl(url)

例如：

// main.js
import sdk from "zvos-print-sdk";
sdk.setBaseUrl("http://paas-portal.test.zoomlion.com/api"); // 麓谷测试

从 v1.1.1 开始还可以使用 setEnv 方法通过环境编码来设置 baseUrl。

/**
 * 根据环境编码设置 BaseUrl
 * @param {String} env 环境编码
 */
function setEnv(env)

例如：

sdk.setEnv("LUGU_TEST"); // 麓谷测试
// 其效果和 sdk.setBaseUrl("http://paas-portal.test.zoomlion.com/api"); 相同

常用的环境编码及其对应 baseUrl 如下：

• 麓谷生产（LUGU_PRD）：http://paas-portal.zvos.zoomlion.com/api

• 麓谷测试（LUGU_TEST）：http://paas-portal.test.zoomlion.com/api

• 麓谷开发（LUGU_DEV）：http://saas-portal.develop.zoomlion.com/api

• 商砼生产（ST_PRD）：https://z-api.zoomlion.com/zhjcapi

② 用户信息

现在商砼、制造业务侧都提出了打印模板需要支持“租户+应用”内对应模板编码唯一的需求，所以 sdk 在请求接口的过程中，需要获取当前用户的应用和租户信息。

在 src/store/modules/user.js 中引入，并修改 mutations 中的 SET_USER 方法：

// src/store/modules/user.js
import sdk from "zvos-print-sdk";

const mutations = {
  ...
  SET_USER: (state, user) => {
    state.user = user;
    // 调用 setUser 方法
    sdk.setUser(user);
  },
  ...
}

③ 文档名称

在打印机的打印队列中会显示文档的文档名，默认为“Document Name”。

若要更改文档的文档名，可以在打印文档前调用 setDocName 方法。

/**
 * 设置文档名
 * @param {String} name 文档名
 */
function setDocName(name)

例如：

import sdk from "zvos-print-sdk";
sdk.setDocName("发货单");

④ 签名（已废弃）

对于开启了签名验证的多租户系统，需要调用 setSign 方法配置签名。

在 src/store/modules/app.js 中引入，并修改 mutations 中的 SET_WEB_CONFIG 方法：

// src/store/modules/app.js
import sdk from "zvos-print-sdk";

const mutations = {
  ...
  SET_WEB_CONFIG: (state, webConfig) => {
    state.webConfig = webConfig;
    // 添加 if 条件调用 setSign 方法
    if (webConfig && webConfig.signSalt) {
      sdk.setSign(webConfig.signSalt);
    }
  },
  ...
}

4. 打印方式

① 浏览器打印

大部分情况下，调用浏览器自带的打印方法进行打印。

② Lodop 打印

使用 Lodop 插件打印可以无需预览进行静默打印。Lodop 官网

使用 Lodop 打印，需要下载插件，Lodop 下载地址： https://data-api.zvalley.com/v1/openapi/download/5656e3f6a71e4a8caf2eb74431bf8922

使用 Lodop 打印时，若内容包含 二维码 或 条形码，可能打印失败，需要高版本的 IE，IE 11 下载地址： https://data-api.zvalley.com/v1/openapi/download/7c23487cb55043a4b2c04dd3eb3b8853

5. 方法调用和捕获错误

import sdk from "zvos-print-sdk"; 

// 异步方法
sdk
  .getHtmlByTemplateCode("templateCode", { no: "1" })
  .then((_) => {})
  .catch((error) => {});

// 同步方法
try {
  sdk.getHtmlByLayout(
    {
      panels: [
        {
          index: 0,
          height: 60,
          width: 90,
          paperHeader: 6,
          paperFooter: 157.5,
          printElements: […]
        }
      ]
    },
    { data: "123" }
  );
} catch (error) {}

6. 方法

① 模板

获取模板列表

/**
 * 获取模板列表
 * @param {Object} params 参数 { systemCode, type }
 * @returns 模板列表
 */
function getTemplateList(params)

根据模板编码获取模板 json

/**
 * 根据模板编码获取模板
 * @param {String} templateCode 模板编码
 * @returns 模板编码对应的模板
 */
function getTemplateByTemplateCode(templateCode)

② 获取 HTML 字符串

根据布局 JSON 和 data 获取 HTML

/**
 * 根据布局 JSON 和 data 获取 HTML
 * @param {String | Object} layout 布局对象 / JSON 字符串
 * @param {String | Object} data 数据对象 / JSON 字符串
 * @returns HTML 字符串
 */
function getHtmlByLayout(layout, data)

根据模板编码和 data 获取 HTML

/**
 * 根据模板编码和 data 获取 HTML
 * @param {String} templateCode 模板编码
 * @param {String | Object} data 数据对象 / JSON 字符串
 * @returnsHTML 字符串
 */
async function getHtmlByTemplateCode(templateCode, data)

③ 浏览器打印

根据布局 JSON 和 data 进行浏览器打印

/**
 * 根据布局 JSON 和 data 浏览器打印
 * @param {String | Object} layout 布局对象 / JSON 字符串
 * @param {String | Object} data 数据对象 / JSON 字符串
 * @returns HTML 字符串
 */
function printByLayout(layout, data)

根据模板编码和 data 进行浏览器打印

/**
 * 根据模板编码和 data 浏览器打印
 * @param {String} templateCode 模板编码
 * @param {String | Object} data 数据对象 / JSON 字符串
 */
async function printByTemplateCode(templateCode, data)

④ Lodop 打印

根据布局进行 Lodop 打印

/**
 * 根据布局进行 Lodop 打印
 * @param {String | Object} layout 布局对象 / JSON 字符串
 * @param {String | Object} data 数据对象 / JSON 字符串
 * @param {Boolean} needPreview 是否需要预览，默认为 false
 * @param {String} mode 打印缩放控制，默认为 null，详见 http://www.c-lodop.com/demolist/PrintSample42.html
 */
function lodopPrintByLayout(layout, data, needPreview = false, mode = null)

根据模板编码进行 Lodop 打印

/**
 * 根据模板编码进行 Lodop 打印
 * @param {String} templateCode 模板编码
 * @param {String | Object} data 数据对象 / JSON 字符串
 * @param {Boolean} needPreview 是否需要预览，默认为 false
 * @param {String} mode 打印缩放控制，默认为 null
 */
async function lodopPrintByTemplateCode(templateCode, data, needPreview = false, mode = null)

⑤ 获取 Lodop 实例

该方法返回了 Lodop 实例，获取之后可以直接调用 Lodop 的内置方法，详见 Lodop 官网或其它参考网址。

/**
 * 获取 Lodop 实例
 */
function getLodopInstance()

例如：

let lodop = sdk.getLodopInstance();
console.log(lodop.GET_PRINTER_COUNT()); // 获取打印机个数

⑥ 获取 hiprintTemplate 实例

该方法返回了 hiprintTemplate 实例，获取之后可以直接调用 hiprintTemplate 的内置方法，详见 Hiprint 官网。

/**
 * 根据布局 JSON 获取 hiprintTemplate 实例
 * @param {String | Object} layout 布局对象 / JSON 字符串
 * @returns hiprintTemplate 实例
 */
function getHiprintTemplate(layout)

例如：

let hiprintTemplate = getHiprintTemplate(layoutJson);
console.log(hiprintTemplate.getHtml({})); // 根据用户数据获取打印 html

更新日志

v1.2.4 (2024.2.4)

【修复】表格 border 在 Lodop 下的显示问题

v1.2.1 ~ v1.2.3 (2024.1.17)

【升级】插件升级

【移除】baseUrl 默认取当前项目的 baseUrl

v1.1.3 (2023.8.8)

【优化】移除 sass-loader

v1.1.2 (2023.8.7)

【优化】baseUrl 默认取当前项目的 baseUrl

【优化】更新了各个环境的 baseUrl

v1.1.1 (2023.5.6)

【新增】设置用户的方法 setUser

【优化】设置 BaseUrl 时可以通过环境编码设置

v1.0.18 (2023.3.2)

【优化】优化 script 注入逻辑

v1.0.17 (2023.2.1)

【修复】修复当字段为空时显示 undefined 的问题

v1.0.16 (2023.2.1)

【优化】接口新增 mode 参数，控制打印缩放

v1.0.15 (2023.1.9)

【修复】修复 Lodop 打印不出线条的问题

v1.0.14 (2022.12.28)

【新增】获取模板 json 的方法 getTemplateByTemplateCode

【新增】获取 hiprintTemplate 实例方法 getHiprintTemplate

v1.0.13 (2022.12.6)

【新增】设置文档名称方法 setDocName

【新增】获取 Lodop 实例方法 getLodopInstance

v1.0.12 (2022.10.24)

【优化】移除 css-loader

v.1.0.11 (2022.10.10)

【优化】优化 Lodop 启动时的提示

v1.0.10 (2022.10.10)

【优化】打印效果优化

v1.0.8 / v1.0.9 (2022.7.22)

【优化】baseUrl 配置

v1.0.6 / v1.0.7 (2022.6.28)

【修复】修复打印样式问题，css 新增 media="print"

v1.0.5 (2022.6.22)

【新增】模板调用地址配置

【优化】核心代码优化

v1.0.4 (2022.6.16)

【优化】方法调用异常处理优化

v1.0.3 (2022.6.15)

【新增】新增多个打印相关方法

v1.0.2 (2022.6.14)

【新增】新增多个模板相关方法

v1.0.1 (2022.6.13)

【新增】初始化