初始化 SDK

Booking Renderer SDK（@seatmap.pro/renderer）是在售票页面运行的可嵌入选座组件。它连接 Booking API，通过 WebGL 渲染场地布局，并在顾客选中或取消选择座位时触发回调。

前提条件

Node.js 18+，推荐 LTS 版本。
npm、yarn 或 pnpm 包管理器。
按快速入门指南创建活动并发布座位图。
从 Editor 管理面板的 Organization Settings 获取 Public API Key。

第 1 步：安装包

npm install @seatmap.pro/renderer

yarn add @seatmap.pro/renderer

pnpm add @seatmap.pro/renderer

包详情：npm 上的 @seatmap.pro/renderer

第 2 步：添加容器元素

渲染器挂载到页面 DOM 元素中，请明确设置其尺寸：

<div id="seatmap-root" style="width: 100%; height: 600px;"></div>

渲染器会填满容器。通过 CSS 控制座位图在页面布局中的大小。

第 3 步：初始化渲染器

import { SeatmapBookingRenderer } from '@seatmap.pro/renderer';

const container = document.getElementById('seatmap-root')!;

const renderer = new SeatmapBookingRenderer(container, {
  publicKey: 'YOUR_PUBLIC_API_KEY',
  onSeatSelect: (seat) => {
    console.log('selected', seat);
  },
  onSeatDeselect: (seat) => {
    console.log('deselected', seat);
  },
});

await renderer.loadEvent('YOUR_EVENT_ID');

必需值：

publicKey：来自 Editor 管理面板的组织设置。
eventId：通过 Booking API v2 或活动中心界面创建活动后返回。

第 4 步：处理选座

每当顾客点击可用座位，onSeatSelect 回调就会触发。用它将选择同步到购物车或后端。

生产票务系统推荐逐次点击锁定：选中时立即在后端锁定座位，取消选择时解锁。

const renderer = new SeatmapBookingRenderer(container, {
  publicKey: 'YOUR_PUBLIC_API_KEY',
  onSeatSelect: async (seat) => {
    await fetch('/api/cart/lock', {
      method: 'POST',
      body: JSON.stringify({ seatId: seat.id }),
    });
  },
  onSeatDeselect: async (seat) => {
    await fetch('/api/cart/unlock', {
      method: 'POST',
      body: JSON.stringify({ seatId: seat.id }),
    });
  },
});

完整回调和设置参考见 Renderer 规范。

在线体验

打开 Renderer Playground，无需配置即可交互体验 SDK。

CodePen 也提供完整可运行示例。

故障排查

容器不可见：渲染器需要宽高均非零的容器。若无任何内容，检查是否明确设置了 CSS 尺寸。

CORS 错误：渲染器从 booking.seatmap.pro 获取数据。使用代理或自定义域名时，确保服务器向 Booking API 转发请求时携带正确的 Origin 头。

未显示座位：检查活动是否已为座位分配价格。渲染器仅显示至少有一个价格分配的座位。

深入了解

座位图渲染：SVG、Canvas 和 WebGL 渲染流程。
2D 与 3D 座位图的实践演进：选择 2D 或 3D 渲染模式。
快速入门指南：从创建座位图到结算的完整集成流程。