webprint打印 · WebPrint JS 打印接口
SDK 版本：0.6.0

一、接入名称
对外统一使用 WebPrint JS SDK，打印实例类型为 WebPrint.Printer。
WebPrint.autoConnect()：发现本机打印端并匹配已保存打印机，返回已就绪实例。
WebPrint.configure(config)：配置手动接入，返回实例，需等待 printer.ready。
WebPrint.create(config)：创建独立实例，不改变当前实例。
WebPrint.getPrinter(container?)：取得当前实例；可选参数指定预览或设计器的嵌入容器。
新命名由 SDK 实现；安装该 SDK 不会自动扩充打印端的设备或设计器能力。

二、部署
将 ZIP 内的 webprint 目录整体放到业务网站，保留所有相对路径。
入口脚本为 /webprint/sdk.js；不能只部署这一个文件。
HTTPS 本机自动连接的来源授权、浏览器权限与 CSP 见 HTTPS自动打印接入说明.txt。
SDK 0.6.0 可连接桌面打印端 0.5.0 及后续兼容版本；当前测试软件为 0.5.3。
下载新 SDK 并替换业务网站资源即可；现有 0.5.3 安装包中的内置旧 SDK 不会自动更新。

三、本机自动连接示例
<script src="/webprint/sdk.js"></script>
<script>
async function printLabel() {
  const printer = await WebPrint.autoConnect();
  printer.init('商品标签');
  printer.setPageSize(1, '60mm', '40mm', '');
  printer.addText('2mm', '2mm', '56mm', '8mm', '商品标签 · 中文测试');
  printer.setItemStyle(0, 'FontSize', 14);
  printer.addBarcode('14mm', '2mm', '52mm', '18mm', '128Auto', 'WP10001');
  const jobId = await printer.print();
  console.log('任务已处理', jobId);
  return jobId;
}
// 请在用户点击打印按钮时调用：printLabel().catch(error => alert(error.message));
</script>

四、手动连接局域网或服务器
const printer = WebPrint.configure({
  baseURL: 'https://print.example.com',
  token: '由服务端签发的业务接入凭据',
  agentId: 'store-01' // 可选，仅加载指定打印端的设备
});
await printer.ready;
// 后续排版、选择设备和打印使用相同的 printer 方法。

HTTPS 业务网页连接任意局域网地址时须遵守浏览器策略；本机自动连接专用回环通道的允许条件不能直接套用到其他 HTTP 地址。现有服务的管理令牌模型与权限范围仍需按部署文档设置。

五、常用方法
同步排版（参数顺序延续现有布局引擎）：
- init(name)：开始新文档并重置当前排版设置。
- setPageSize(orientation, width, height, name?)：方向 1 纵向／2 横向；宽高建议传 '60mm' 等带单位字符串。数字宽高使用 0.1mm，与已有方法一致。
- addText / addHtml / addTable / addImage / addPdf：top, left, width, height, content。
- addBarcode(top, left, width, height, type, content)：添加条码或二维码。
- addTextNamed(name, ...args) 等 Named 方法：为元素指定名称。
- addRect / addEllipse / addLine / addShape：图形元素；参数见现有能力清单。
- setStyle(key, value)：后续元素的默认样式。
- setItemStyle(indexOrName, key, value)：指定元素样式；0 表示最后元素。
- setCopies(count)：1–100 份；newPage()：新增一页。
- setMode(key, value)：设置已支持的打印模式。
- getPrinterCount() / getPrinterName(index) / setPrinter(indexOrIdOrName)。
- getTemplate()：取得独立 JSON 副本；loadTemplate(document)：加载 WebPrint JSON 模板。
- getTemplateCode(variableName?)：输出 printer.loadTemplate(...) 形式的代码，默认实例变量名 printer。

异步方法（返回 Promise，可 await，失败时 reject）：
- print()：提交当前文档并等待任务到达已提交、模拟完成或系统队列结束状态，返回任务 UUID。
- getJob(jobId)：查询任务对象，state 为本服务任务状态。
- preview()：打开预览，完成或关闭后返回本窗口提交次数。
- printWithDialog() / setup() / selectPrinter()：打印确认、设置或选择设备。
- design()：打开设计器，返回 WebPrint 模板加载代码。
- getValue(type, value?)：查询已有布局、模板或任务字段；ProgramCodes 使用 WebPrint 命名。
- saveToFile(filename)：导出 PDF、XLS、XLSX 或 CSV。
- readFile / writeFile / getFileTime / fileExists / getSystemInfo / getDialogValue。
- writePort / readPort / sendRawData / showChart / doAction。
- format(type, value) 保留同步格式转换；文件或语音等任务型格式操作请使用 await formatAsync(type, value)。

预览、选择和设计窗口应在用户点击时调用，并允许浏览器弹出窗口。嵌入显示时通过 WebPrint.getPrinter(container) 指定容器，再用 setDisplayMode 设置已有显示选项。
扩展能力仍由打印端配置与接入权限控制；自动连接的临时打印凭据不能用于文件、端口或管理操作。
任务回执不能代替实际出纸确认。超时后任务可能继续执行，应先查询原任务，避免重复提交。

六、已有项目迁移
默认示例、文档与对外类名使用 WebPrint。为保护已有业务，以下兼容入口继续保留：
- WebPrint.Lodop 是 WebPrint.Printer 的兼容别名。
- getLodop()、getCLodop()、CLODOP 和已有大写方法继续可用。
- 旧 PRINT() 等任务型方法仍立即返回 JS 请求编号，通过 On_Return / On_Error 获取回执。
- 新 print() 等 Promise 方法通过 await 获取结果，不调用或覆盖上述旧回调。
- 同一个实例可调用两类方法；迁移时每一次打印只选择一种调用方式，不要新旧各调用一次。
- 原服务的 CLodopfuncs.js / LodopFuncs.js 地址别名保留；新项目统一引入 sdk.js。
- 新 design() / getTemplateCode() 使用 WebPrint 代码；旧 GET_VALUE('ProgramCodes') 保留旧代码格式，便于已有项目回退。

商业授权暂未开放，SDK 不执行付款或激活；新名称不代表完整兼容其他软件的所有功能。
