API-Referenz

Diese Referenz behandelt die API, die in diesen Anleitungen verwendet wird, so wie sie in Version 0.1.0 implementiert ist. Alles außer dem Abschnitt Lite-API gehört zu SuperScheduler Pro (super-scheduler). Standardwerte sind die Werte, die das Control verwendet, wenn Sie eine Option weglassen; „keiner“ bedeutet, dass die Option keinen Wert hat, bis Sie einen setzen. Die Anleitungen erklären, wie sich diese Bausteine kombinieren lassen; die Beispiele zeigen sie in funktionierenden Anwendungen.

Einige Konventionen gelten überall:

• DateInput ist SuperScheduler.Date | string. Strings sind ISO-8601-Werte in bürgerlicher Zeit mit Sekunden ('2026-10-01T14:00:00') oder reine Datumsangaben ('2026-10-01'). Das Ende eines Ereignisses ist exklusiv.
• IDs von Ressourcen, Ereignissen und Verknüpfungen sind string | number und werden strikt verglichen: 1 und '1' sind verschieden.
• Optionen sind Props von SuperSchedulerComponent, Schlüssel von control.update(options) und Live-Eigenschaften des Controls.
• Handler laufen mit this auf das Control gesetzt. Ihre Rückgabewerte werden ignoriert, und auf einen async-Handler wird nicht gewartet: Verwenden Sie das Protokoll aus async und loaded(), wo es existiert.

#Einstiegspunkte

Jeder Einstiegspunkt wird als ESM, als CommonJS und mit Typdeklarationen ausgeliefert. React 18.2 oder neuer, oder 19, ist eine Peer-Abhängigkeit (bei Pro auch React DOM); Laufzeitabhängigkeiten gibt es keine. Alle Module lassen sich auf einem Server ohne DOM importieren.

#Komponenten

#SuperSchedulerComponent

SuperSchedulerComponent beherbergt ein Control. Ihre Props (SchedulerProps) sind alle Optionen und Handler unten plus controlRef. Sie rendert ein ungestyltes <div>, hat keine Props className, style oder id und leitet an control.update() nur die Props weiter, deren Identität sich seit dem letzten Rendern geändert hat; eine Prop, die verschwindet, fällt auf ihren Standardwert zurück.

Die Komponente aus super-scheduler/react-render akzeptiert dieselben Props plus renderEvent, renderCell, renderRowHeader, renderTimeHeader, renderArea, renderCorner, eventHover, die Handler onBefore*DomAdd und onBefore*DomRemove sowie renderOptions (siehe react-render).

import { useEffect, useRef } from 'react'
import { SuperScheduler, SuperSchedulerComponent, useSchedulerControl } from 'super-scheduler'
import { useScheduler } from 'super-scheduler/hooks'

const CONFIG = {
  startDate: '2026-10-01',
  days: 31,
  scale: 'Day',
} satisfies SuperScheduler.SchedulerConfig

// 1. A class ref: `ref.current.control` exists after mount.
export function WithRef() {
  const ref = useRef<SuperSchedulerComponent>(null)
  useEffect(() => ref.current?.control.scrollTo('2026-10-15', true, 'middle'), [])
  return <SuperSchedulerComponent ref={ref} {...CONFIG} />
}

// 2. The control as React state: null until mount, then the live control.
export function WithHook() {
  const { controlRef, control } = useSchedulerControl()
  useEffect(() => control?.scrollTo(SuperScheduler.Date.today()), [control])
  return <SuperSchedulerComponent controlRef={controlRef} {...CONFIG} />
}

// 3. Control plus tracked state topics, published after changes settle.
export function WithState() {
  const { controlRef, state } = useScheduler({ track: ['zoom', 'viewport'] })
  return (
    <>
      <p>
        {state.viewport === undefined
          ? ''
          : `${state.viewport.start.toString('d MMM')} to ${state.viewport.end.toString('d MMM')}`}
      </p>
      <SuperSchedulerComponent controlRef={controlRef} {...CONFIG} />
    </>
  )
}

// 4. Imperative, without React: init() before use, dispose() on teardown.
export function mount(host: HTMLElement): () => void {
  const control = new SuperScheduler.Scheduler(host, CONFIG)
  control.init()
  return () => control.dispose()
}

#Typen

#Datenstrukturen

#Ereignisse

SuperScheduler.EventData<T> hat keine Indexsignatur: Deklarieren Sie zusätzliche Felder über den Typparameter, zum Beispiel EventData<{ guest: string }>.

#Ressourcen

SuperScheduler.ResourceData<T> akzeptiert zusätzliche Felder.

#Verknüpfungen, Köpfe, Zoomstufen und Trennlinien

#Optionen

#Zeitachse

#Zeilen

#Ereignisse und Bearbeitung

#Auswahl

#Zoom und Detailstufe

#Größe und Layout

#Erscheinungsbild

#Verknüpfungen

#Tastatur

#Menüs und Bubbles

#Daten, Laden und Erweiterungen

#React-Inhalte

Nur mit SuperSchedulerComponent aus super-scheduler/react-render:

#Callbacks

#Konventionen

• Davor und danach. onEventMove läuft vor einer Änderung und kann sie abbrechen; onEventMoved läuft danach. Die meisten Paare folgen diesem Muster.
• Abbrechen. Handler, deren Argumente preventDefault() haben, können abbrechen: die Klick-Familie, onEventSelect, onEventDelete, onEventMove, onEventResize, onTimeRangeSelect, onTimeRangeClick und seine Varianten für Doppel- und Rechtsklick, onRectangleSelect, onRowClick und Varianten, onRowSelect, onResourceExpand, onResourceCollapse, onTimeHeaderClick, onTimeHeaderRightClick, onGridMouseDown, onKeyDown, onKeyboardFocusChange und onLinkClick. Wer einen Klick abbricht, überspringt auch den zugehörigen „-ed“-Handler und die Folgeaktion.
• Asynchrone Bestätigung. onEventMove und onEventResize unterstützen args.async = true und ein späteres args.loaded(); preventDefault() vor loaded() bricht ab, und newStart, newEnd und newResource, die vor loaded() gesetzt werden, werden angewendet.
• Steuern. onEventMoving, onEventResizing, onTimeRangeSelecting und onRectangleSelecting laufen bei jeder Änderung des Schattens; weisen Sie args.allowed, args.start, args.end, args.cssClass oder args.html zu.

#Ereignisse

e ist ein SuperScheduler.Event: e.data ist das Datenobjekt, und e.id(), e.start(), e.end(), e.text(), e.resource() und e.duration() lesen es.

#Ziehen und Dauer ändern

#Zeiträume und Rechtecke

#Zeilen und Köpfe

#Render-Hooks

#Weitere Handler

#Control-API

Das Control ist ref.current.control, der Wert von controlRef, args.control in den meisten Handlern oder new SuperScheduler.Scheduler(element, options), gefolgt von init().

#Lebenszyklus und Anzeige

#Scrollen und sichtbarer Bereich

#Ereignisse

#Zeilen

#Auswahl

#Zoom, Verknüpfungen, Zellen und Tastatur

#Statische Mitglieder

#Der Namespace SuperScheduler

#Subpath-Module

#history

createHistory(options?) gibt einen Verlauf zurück, den Sie als history={history} oder in extensions übergeben. Optionen: limit (50), record (['move', 'resize']), keys ('root', 'document' oder false; Standard 'root'), equals, fields, apply ('control' oder eine Funktion für kontrollierte Ereignisse) und labels. Methoden: undo(), redo(), clear(), push({ label, undo, redo }), record({ ops, control }), batch(label, run), revert(eventId), subscribe(listener); Eigenschaften canUndo, canRedo, undoLabel, redoLabel. Ladevorgänge und abgelehnte Änderungen werden nicht aufgezeichnet.

#minimap

createMinimap(control, container, options?) und die React-Komponente <SchedulerMinimap control={control} />. Optionen: series (Standard eventDensity(control)), height (28), peak ('relative' oder 'absolute' mit max), tone, marks (today, months, past, alle true), range und labels. Das Widget hat update(), refresh() und dispose().

#panes

<SchedulerPanes> nimmt die Props des Planers plus panes ({ id, resources or rowFilter, size, minSize (48), hidden, props }), eine erforderliche numerische height, timeHeader ('first'), scrollbar ('last'), splitter (true), crossPaneMove (true), component, onPaneResize und panesRef. linkPanes(controls, { zoom, rowHeaderWidth }) koppelt vorhandene Controls und gibt { dispose() } zurück.

#zoom-ui

createZoomHud(control, { format, apiMs (700) }), createZoomSlider(control, container, { min, max, detents, scale ('log'), label }) und createLodBadge(control, container, labels?). Jede Funktion gibt { element, dispose() } zurück.

#views

getViewState(control, include?) gibt einen JSON-tauglichen Zustand zurück (zoom, scroll, density, collapsed, columns); applyViewState(control, state, { animate, when, timeout }) (when ist 'now' oder 'rows') gibt ein Promise auf einen boolean zurück.

#ranges

createRangeLoader({ load, chunkDays (7), prefetch (1), cacheChunks (26), skeleton (true), onError }) gibt einen Loader mit reload(range?), clear() und loading zurück. load({ start, end, signal }) gibt die Ereignisse zurück, die sich mit [start, end) überschneiden.

#hooks

useScheduler({ track }) gibt { controlRef, control, state } für die Themen 'events', 'selection', 'zoom', 'viewport' und 'history' zurück. useSchedulerState(control, topic), subscribeScheduler(control, topic, listener) (gibt eine Funktion zum Abmelden zurück) und getSchedulerSnapshot(control, topic) liefern denselben Zustand außerhalb des Hooks. Der Zustand des sichtbaren Bereichs wird veröffentlicht, nachdem sich das Scrollen gesetzt hat.

#react-render

SuperSchedulerComponent mit den Props für React-Inhalte. Der HTML- oder Text-Fallback wird zuerst gezeichnet; React-Inhalte ersetzen ihn nach dem Ende der Interaktion. renderOptions.retain ist standardmäßig der kleinere Wert von 2.000 oder dem Doppelten der gemounteten Elemente; sliceMs ist standardmäßig 8.

#tailwind

Ein Preset für Tailwind CSS v3: presets: [require('super-scheduler/tailwind')]. Es ergänzt super-scheduler-Farben, -Radien, -Schatten und -Übergänge, die auf die CSS-Tokens abgebildet sind.

#datasets

generateDataset(options) und generateScenario(id, overrides?) erzeugen deterministische Daten im Hotelstil (rows und days erforderlich, seed, start in Ticks, density, events, times). toSuperSchedulerData(dataset) gibt { resources, events } zurück. Szenarien: S1 (120 Zeilen, 730 Tage), S2 (1.000 Zeilen, 730 Tage), S3 (5.000 Zeilen, 1.500 Tage) und ihre dichten Varianten. Die Daten beginnen standardmäßig am 2026-01-01.

#core

DOM-freie Hilfsfunktionen, die die Engine nutzt: SchedulerDate, Duration, registerLocale, resolveLocale, formatTicks, parseTicks, ticksFromParts(year, month, day, ...), partsOf, formatIso, parseIso, todayTicks, nowTicks, die Konstanten MS_PER_* sowie Hilfsmittel für Zeitleisten, Indizes und Layout. Verwenden Sie sie für Diagramme und Werkzeuge neben dem Planer.

#Lite-API

super-scheduler-lite ist eine schreibgeschützte Tageszeitleiste. Optionen, die es nicht implementiert, werfen SuperScheduler Lite: unsupported option "...", in jedem Build.

Das Control (ref.current.control) hat init(), update(options), dispose(), disposed(), scrollTo(date), scrollToResource(id), visibleStart() und visibleEnd(). Der Namespace hat SuperScheduler.Date und SuperScheduler.Scheduler. Die Ressourcenfelder children, frozen, split und columns werden abgelehnt. Theme-Tokens auf .super-scheduler-lite: --super-scheduler-background, -text, -border, -header, -event und -focus. Siehe Von Lite zu Pro migrieren.

#Reservierte APIs

Diese Mitglieder sind typisiert, damit bestehender Code kompiliert, aber sie sind in 0.1.0 nicht implementiert. Sie bewirken nichts, geben leere Werte zurück und geben in Entwicklungs-Builds einmal super-scheduler: <feature> is not supported yet aus.

Teilweise implementiert:

• treeAnimation wird akzeptiert, aber die Aufklapp-Animation wird nie abgespielt.
• eventClusters und onClusterClick werden akzeptiert und haben noch keine sichtbare Wirkung.
• Die Handler onBefore*DomAdd und onBefore*DomRemove, die render*-Props und eventHover funktionieren nur mit der Komponente aus super-scheduler/react-render; die Wurzelkomponente warnt und ignoriert sie.

Akzeptierte Tuning-Hinweise, die ignoriert werden, weil die Virtualisierung immer aktiv ist und sich selbst abstimmt: beforeCellRenderCaching, cellSweeping, cellSweepingCacheSize, drawBlankCells, dynamicEventRendering mit seinen Rand- und Cache-Optionen, eventUpdateInplaceOptimization, progressiveRowRendering, progressiveRowRenderingPreload und die Optionen scrollDelay* außer scrollDelayDynamic.