云打印服务 plugin-cloud
约 1671 字大约 6 分钟
...
2026-10-11
插件说明
@sv-print/plugin-cloud 给设计器接入 sv-print-cloud 云端能力,一个插件覆盖四件事:
- 可插拔登录:内置
oauth(授权码)/token(访问令牌)/host(宿主托管)/local(本地账号)四种登录方式,可同时配置多个,用户在设置面板「账户」中切换;autoLogin: true启动未登录时自动发起登录 - 服务端渲染:把当前模板/数据提交到服务端渲染,产出 PDF / 图片 / HTML
- 云打印 + 中转打印:设备查询、任务下发/重试/取消、任务与日志查询;或通过 Socket.IO
/transit命名空间直发本地中转客户端 - 模板中心:设计器内浏览模板(行业/分类筛选 + 名称检索 + 大图预览 + 一键使用),浏览无需登录,使用需登录
样式文件
插件包含 UI 组件(模板中心弹窗、设置面板 tab),必须引入样式文件。
npm install @sv-print/plugin-cloud示例代码
import '@sv-print/plugin-cloud/dist/style.css'; // 必须引样式
import pluginCloud from '@sv-print/plugin-cloud';
const plugins = [
pluginCloud({
// host 缺省时走当前站点 /api 代理
auth: {
type: 'oauth',
authorizeOrigin: 'https://www.example.com',
clientId: 'svprint-demo',
clientSecret: '匿名接入方公共密钥', // 前端直连,仅用于开发联调
scope: 'print:template:read,member:cloud:job:write',
},
}),
];
await hiprint.register({ plugins });登录后即可使用运行时 API:
const cloud = designerUtils.cloud;
// 模板中心
cloud.templateCenter.show();
const page = await cloud.templateCenter.list({ keyword: '发票', page: 1 });
// 登录态
if (!cloud.auth.isLoggedIn()) await cloud.auth.login();
await cloud.auth.logout();
// 云打印 / 中转打印
const devices = await cloud.getDevices();
await cloud.cloudPrint({ device_id: devices[0].device_id });
const clients = await cloud.getTransitClients(); // 仅 clientType=electron 可作目标
await cloud.transitPrint({ clientId: clients[0].clientId, printer: 'HP-LaserJet' });模板实例扩展(newPrintTemplate hook 挂载,默认带上当前模板与打印数据):
const tpl = designerUtils.printTemplate;
// 服务端渲染:sync 直接返回产物;异步返回 task_id 再轮询
const result = await tpl.serverRender({ sync: true, type: 'pdf' });
console.log(result.file_url);
// 云打印下发 / 中转直发
await tpl.cloudPrint({ device_id: 'dev-xxx' });
await tpl.transitPrint({ clientId: 'machine-001', printer: 'HP-LaserJet' });
// 清理扩展
tpl.restoreCloud();高级用法
四种登录方式
// oauth:授权码模式;autoLogin 未登录时自动弹出授权页
pluginCloud({ autoLogin: true, auth: { type: 'oauth', authorizeOrigin, clientId, clientSecret } });
// token:直接给访问令牌,启动即登录;不传则设置面板粘贴
pluginCloud({ auth: { type: 'token', token: 'eyJhbGciOi...' } });
// host:token 由宿主持有,插件不参与认证
pluginCloud({ auth: { type: 'host', getToken: () => hostSdk.getAccessToken() } });
// local:设置面板账号密码表单 → 宿主校验
pluginCloud({
auth: {
type: 'local',
title: '企业账号登录',
login: async (username, password) => {
const res = await fetch('/my-backend/login', {
method: 'POST',
body: JSON.stringify({ username, password }),
});
return (await res.json()).data;
},
},
});
// 多方式并存:设置面板「账户」出现切换标签
pluginCloud({
auth: [{ type: 'oauth', authorizeOrigin, clientId }, { type: 'token' }],
defaultAuth: 'oauth',
});- 多方式并存时初始生效顺序:用户上次选择 >
defaultAuth> 已有凭据的方式 > 数组首项 - 各方式凭据独立存储(
sv_print_cloud_auth_{type}),切换只换 token 来源 - 生产安全推荐:oauth 配置
exchangeToken(code, state)回调,由宿主后端持client_secret换取 token;前端直连clientSecret仅用于联调 - 统一 401 兜底:任意业务请求返回 401 → 清空 token 并广播未登录
PluginConfig 配置表
| 配置 | 默认 | 说明 |
|---|---|---|
| host | ''(走当前站点 /api 代理) | 云服务后端地址(不含 /api),填写则跨域直连 |
| auth | - | 登录方式,单对象或数组 |
| defaultAuth | - | 多方式时的默认方式 id |
| autoLogin | false | 启动未登录时自动登录(local 不参与) |
| storage / storageKey | preferences store | 自定义 token 存储 / 覆盖存储 key |
| enableSettingsTab | true | 设置弹窗「云打印」tab 开关 |
| templateCenter | {enable:true, menuOrder:0} | 模板中心菜单(显隐、位置、标题、图标) |
| templateCenterPageSize | 12 | 模板中心每页数量 |
| requestAdapter | - | 自定义请求适配器(覆盖默认 fetch) |
后端接口对照
| 能力 | 方法 + 路径 | 登录 |
|---|---|---|
| 服务端渲染(同步/异步) | POST /api/print/render[/sync] | 是 |
| 云设备列表 | GET /api/member/cloud/device | 是 |
| 云打印下发 | POST /api/member/cloud/print/submit | 是 |
| 中转连接凭证 | POST /api/member/transit/ticket | 是 |
| 模板中心列表 | GET /api/print/template | 否 |
| 模板 JSON / 使用计数 | GET /api/print/template/:id/data / POST .../use/:id | 是 |
| 授权码换 token | POST /api/auth/member/oauth/token | 否 |
| 会员信息 | GET /api/auth/member/profile | 是 |
统一响应体 { code, msg, data },code = 1 成功;插件自动解包并抛出失败 msg。
注意事项
host不带/api,插件自动补前缀;缺省时宿主需自行配置前端代理(Viteserver.proxy等)- 中转打印复用页面全局
window.io(与 sv-print 打印客户端连接方式一致),宿主页面需提供 socket.io 并代理/api/socket.io(ws: true+ 剥掉/api前缀) - 模板中心使用、云打印、渲染、中转等接口均需登录;模板列表、分类、行业无需登录
- 未配置
auth时仅匿名只读可用(模板中心浏览正常,写操作提示登录)
常见问题
云打印插件的登录方式有哪些?怎么选?
四种:oauth 授权码(正式应用,支持 iframe/popup/page/custom 四种授权页展示)、token 访问令牌(直给或面板粘贴)、host 宿主托管(token 由宿主系统持有,插件不参与认证)、local 本地账号(面板表单交宿主校验)。可同时配置多个并在设置面板切换,生产环境推荐 oauth + exchangeToken 让密钥留在服务端。
中转打印和云打印有什么区别?
云打印走云端任务表:POST /api/member/cloud/print/submit 下发,支持任务查询、取消、重试。中转打印通过 Socket.IO /transit 命名空间直连本地 electron 客户端,不落云任务表,结果由客户端 success/error 事件回执;
模板中心需要登录才能用吗?
浏览不需要:模板列表、分类、行业接口均为公开接口,未配置登录方式时也可正常浏览与检索。使用模板(拉取模板 JSON 覆盖当前设计)、云打印、渲染、中转等写操作需要登录,未登录会先触发登录流程。
授权回调报"回调地址未在接入方白名单内"怎么办?
redirect_uri(默认 location.origin)与申请接入时登记的地址不一致,联系 sv-print 云平台方补登记即可。授权码 code 一次性且 60 秒有效,过期或重复使用需重新发起授权。
版权所有
版权归属:sv-print
