EZUIKit JavaScript SDK

EZUIKitNative is a local plugin player module within the EZUIKit SDK. It uses WebSocket communication to talk to a local CEF (Chromium Embedded Framework) desktop plugin process. This allows the browser to overlay an independent local window to host multiple video streams, supporting up to 25 simultaneous views (a 5×5 grid).

Architecture

The system consists of three layers:

1. Controller (User Page): Runs in your web application. It sends control commands, handles window positioning, and listens for events.
2. CEF Plugin: A local desktop process that provides the WebSocket server, manages windows, and acts as a message relay.
3. Player (Embedded Page): Runs inside the CEF-embedded page. It receives commands, manages EZUIKitPlayer instances, and reports events back to the Controller.

Communication Flow

User Page (Controller) <-> WebSocket (ws://localhost:18082) <-> CEF Plugin <-> WebSocket (ws://localhost:18082) <-> Embedded Player Page

Actions are defined in the render.cellTemplate.action object using the syntax [actionName]:[eventSuffix].

Event Suffixes:

• :click: Responds only to single clicks.
• :dblclick: Responds only to double clicks.
• (No suffix): Responds to both (note: a double click will trigger click twice and then dblclick).

Action Context (ctx): When an action is triggered, the handler receives a context object. Note: This is not a native MouseEvent; it is a serialized object from the plugin process. It does not contain target, clientX, or offsetX.

Context Object Structure:

{
  index: number;        // Cell index
  id: string;           // Cell deviceId
  data: Record<string, string>; // data-* attributes from the element (excluding data-action)
  event: {
    type: 'click' | 'dblclick';
    ctrlKey: boolean;
    shiftKey: boolean;
    altKey: boolean;
    metaKey: boolean;
  };
  cell: CellHandle;     // Equivalent to native.cell(index)
  native: EZUIKitNative; // The SDK instance
}

Starting from v9.0.10, you can use HTML templates and CSS injection to overlay custom DOM elements (like menu buttons, playback controls, or headers) on top of existing EZUIKit video cells without modifying the SDK source code.

Core Concepts

• cellTemplate: An HTML template shared by all cells (as an object) or unique to each cell (as a function).
• [data-ezuikit-video]: The mandatory "video slot" in your template where the SDK embeds the video canvas.
• {index} and {id}: Placeholders in the template that are automatically HTML-escaped.
• [data-action="<name>"]: Elements that trigger action handlers when clicked or double-clicked.
• CellHandle / ElementHandle / NodeListHandle: Chainable APIs used to dynamically modify cell states at runtime.

Layout Constraints

• Template Root: The root element of your cellTemplate must be a positioning container that fills the cell. It should have at least: position: relative; width: 100%; height: 100%; box-sizing: border-box;.
• containerStyle: Only use properties that do not affect the layout size of the #player-container grid (e.g., background, border-radius, box-shadow).
• Warning: Do not use padding, gap, border, or margin in containerStyle. Doing so can cause the canvas buffer to mismatch the display area, resulting in black screens. For visual separation (borders/spacing), apply styles to the .cell class within your cellTemplate.css instead.

const native = new EZUIKit.EZUIKitNative({
  container: 'players-container',
  render: {
    containerStyle: 'background: #1e3a8a;', // Only non-layout properties
    cellTemplate: {
      template: `<div class="cell"><div data-ezuikit-video></div></div>`,
      css: `.cell { position: relative; width: 100%; height: 100%; }`,
    },
  },
});

The connection lifecycle follows this state machine: idle → connecting → connected → closed (with a retrying state between connecting and closed).

Connection Flow

1. Initialization: Connection is attempted immediately upon construction.
2. Protocol Wake-up: If the connection fails, the SDK attempts to wake the plugin via a custom protocol (may trigger a browser 'Open external app' prompt).
3. Retries: The SDK retries up to 3 times. The first two failures are handled internally and do not emit errors. Only the 3rd failure emits launchFailed.

Key Events

Critical Timing Note

websocket code: 0 is the signal that you can start sending commands. connect code: 0 only means the plugin process is connected. Do not attempt to set text, overlays, or initial playback commands until the websocket event confirms readiness.

Starting from v9.0.10, you can use cellTemplate to customize the UI of each video cell. Follow these critical requirements to avoid rendering issues:

1. Video Slot: The template MUST include an element with the attribute [data-ezuikit-video].
2. Container Sizing: The root element of the template must fill the grid cell and establish a positioning context. Use position: relative; width: 100%; height: 100%; box-sizing: border-box;.
3. Avoid Layout Interference: Do not use flex: 1, standard document flow, or height: calc(...) to control the video slot size. The SDK uses absolute positioning for the video slot. Use absolute positioning and z-index > 0 for overlays like titles or buttons.
4. containerStyle Restrictions: Only use properties that do not affect grid layout dimensions (e.g., background, border-radius, box-shadow, filter). Do not use padding, gap, border, or margin in containerStyle, as these can cause the video to be clipped or appear as a black screen.
5. Action Handlers: To distinguish between single and double clicks, use the :click and :dblclick suffixes in your action keys.
6. API Behavior: Read APIs (hasClass, getAttr, getText) are asynchronous and return Promises. Write APIs are synchronous (aggregated via microtasks).