API 速查表

模块方法一览

模块	方法	返回类型	说明
health	check()	Promise<HealthResponse>	健康检查
benefits	check()	Promise<BenefitsResponse>	权益验证
printers	list()	Promise<PrintersResponse>	打印机列表
templates	list()	Promise<TemplatesListResponse>	模板列表
templates	schema(template)	Promise<TemplateSchemaResponse>	模板字段定义
print	execute(request)	Promise<PrintResponse>	执行打印
preflight	run(options?)	Promise<PreflightResult>	预检编排
launch	trigger()	void	触发 TopBridge App 唤起
launch	ensureRunning(fn, options?)	Promise<T>	唤起 + 重试编排

TopBridgeClientConfig

字段	类型	默认值	说明
source	string	'（内置）'	SDK 来源标识（由 SDK 内部自动设置，无需手动配置）
debug	boolean	false	启用控制台日志（前缀：[TopBridge]）
logger	Logger	静默（空操作）	自定义日志器实现
timeouts.health	number (ms)	3000	健康检查超时
timeouts.preflight	number (ms)	10000	预检 / 模板查询超时
wssEnabled	boolean	false	启用 WSS 安全连接模式
timeouts.print	number (ms)	60000	打印执行超时

import type { TopBridgeClientConfig } from '@appzgatenz/label-print-topbridge-js'

const client = new TopBridgeClient({
  debug: true,
  timeouts: { health: 5000, print: 120000 },
})

PrintExecuteRequest

interface PrintExecuteRequest {
  template: string             // 模板 ID 或 Code
  printer: string              // 打印机名称
  products: PrintProductInput[] // 产品数据数组
}

PrintProductInput

interface PrintProductInput {
  [key: string]: string | number | Record<string, string | number | undefined> | undefined
  copies?: number  // 打印份数，范围 [1, 9999]，默认 1
}

SyncedPrinter

interface SyncedPrinter {
  name: string               // 打印机名称（用作 printer 参数）
  isDefault: boolean         // 是否为默认打印机
  protocol?: 'TSPL' | 'ZPL' // 标签协议
}

响应类型一览

类型	关键字段
HealthResponse	type: 'pong', isRunning: true, data.isLoggedIn, data.version(可选), data.networkStatus(可选)
BenefitsResponse	data.isValid, data.remainingPrints, data.expiresAt, data.reason, data.hasPrintBenefit, data.hasSessionBenefit
PrintersResponse	data.count, data.defaultPrinter, data.printers[]
TemplatesListResponse	data.count, data.templates[]
TemplateSchemaResponse	data.fields[], data.code, data.name
PrintResponse	message(顶层), data.printedCopies, data.jobId, data.templateName, data.userId(可选), details(可选), warnings(可选)
PreflightResult	health, benefits, printers

SdkResponse<T>

所有 SDK 方法返回统一的响应信封：

interface SdkResponse<T> {
  status: 'ok' | 'warning'  // 请求结果状态
  requestId?: string         // 请求追踪 ID
  data: T                    // 业务数据
  message: string            // 人类可读的状态描述
  details?: unknown          // 扩展详情（可选）
  warnings?: SdkWarning[]    // 非致命格式提示（可选）
}

状态	行为
'ok'	请求成功，可直接使用 data
'warning'	请求成功但有提示，data 可正常使用，查看 message 和 warnings 了解详情
(错误)	SDK 抛出 TopBridgeError 子类异常，无返回值

导出清单

// 类
import { TopBridgeClient } from '@appzgatenz/label-print-topbridge-js'
import { LaunchModule } from '@appzgatenz/label-print-topbridge-js'

// 错误类（11 个）
import {
  TopBridgeError,
  TopBridgeConnectionError,
  TopBridgeAuthError,
  TopBridgeVersionError,
  TopBridgeQuotaError,
  TopBridgePrintError,
  TopBridgeConfigError,
  TopBridgeValidationError,
  TopBridgePrinterError,
  TopBridgeTemplateError,
  TopBridgeNetworkError,
  TopBridgeSourceError,
} from '@appzgatenz/label-print-topbridge-js'

// 类型（按需导入）
import type {
  TopBridgeClientConfig,
  TopBridgeSource,
  Logger,
  SdkWarning,
  V2WarningCode,
  HealthResponse,
  HealthData,
  BenefitsResponse,
  BenefitsData,
  PrintersResponse,
  PrintersData,
  SyncedPrinter,
  TemplatesListResponse,
  TemplatesListData,
  TemplateItem,
  TemplateSchemaResponse,
  TemplateSchema,
  TemplateFieldSchema,
  PrintResponse,
  PrintData,
  PrintExecuteRequest,
  PrintProductInput,
  PreflightResult,
  PreflightOptions,
  PreflightStep,
  EnsureRunningOptions,
} from '@appzgatenz/label-print-topbridge-js'