Сцены и проекты

Для кого: интеграторы, работающие с многостраничными документами, сохранением и программным API сцены.

Что получите: управление страницами, добавление элементов, сохранение/загрузка.

Предварительные знания: Архитектура движка, Быстрый старт.

Сцены (страницы)

Один проект содержит несколько сцен (Scene2D). У каждой сцены есть pageName.

// Новая страница (pageName — в sceneParams)
const scene = engine.addScene({ sceneParams: { pageName: "Лист 2" } })

// Текущая страница
engine.setCurrentScene(scene.pageName)

// Список имён
engine.appState.sceneNames

// Удаление
engine.removeScene("Лист 2")

После setCurrentScene движок эмитит set_current_scene с { pageName, currentScene }.

Программное добавление элемента

import { RectangleShape } from "@eulergraph/index"

const scene = engine.currentScene
if (!scene) return

const rect = new RectangleShape({
  name: "Прямоугольник",
  width: 100,
  height: 50,
})
rect.setPosition(200, 150)

scene.add(rect)
engine.render()

Для undo/redo используйте API сервиса Editor (добавление через команды), если CommandManager включён.

Проекты и ProjectsManager

engine.projectsManager управляет коллекцией проектов (AppState). Типичные операции:

// Текущее состояние приложения
engine.appState

// Открытие проекта из JSON (строка файла или распакованный объект)
engine.openProject(fileContent, fileName, extension)

Сериализация всего состояния:

const json = engine.appState.toJSON(engine.version)

SaveService

Если включён сервис SaveService:

engine.enableServices(["SaveService"])
// API сохранения/загрузки файла — через методы SaveService
// (конкретные методы см. в типах SaveService и UI host-app)

Host-приложение (renderer) связывает SaveService с UI «Сохранить / Открыть».

События сцен

Событие	Когда
`scenes_updated`	Изменился список страниц
`set_current_scene`	Сменилась текущая страница
`beforeSceneChange`	Перед сменой (payload `{ save: boolean }`)
`sceneChange` / `afterSceneChange`	Изменилось содержимое сцены

Пример подписки — src/renderer/src/hooks/useEngine.ts.

Масштаб и viewport

// Текущий zoom
engine.getZoom()

// Подгонка под ширину viewport (ms анимации; 0 — мгновенно)
engine.fitToWidth(300)

// Подписка на изменение масштаба — через canvasControls (см. useEngine.ts)
engine.canvasControls.on("zoom_update", (zoom) => {
  console.log("zoom:", zoom)
})

Частые ошибки

Проблема	Решение
`currentScene` null	`addScene` + `setCurrentScene`
Элемент не виден	Не вызван `render()`; элемент вне viewport
После `openProject` пусто	Проверить `className` в JSON и регистрацию `elementsLib`

Эталон в репозитории

EulerGraph.addScene, setCurrentScene, openProject — src/engine/EulerGraph.ts
UI страниц — src/renderer/src/ (store useMainStore, panels)