Interface: ZoomApi

API для управления масштабом (zoom) отображения документа в редакторе.

Позволяет получать и устанавливать уровень масштаба документа, увеличивать и уменьшать масштаб.

Remarks

Поддерживаемые стандартные масштабы:

• 50%, 60%, 70%, ..., 400%
• Также поддерживаются пользовательские значения (50-400%)

Типичные сценарии использования:

• Оптимизация просмотра для разных размеров экрана
• Создание кастомных кнопок увеличения/уменьшения масштаба
• Сохранение предпочтений масштаба пользователя
• Автоматическое масштабирование при загрузке документа
• Презентационный режим с увеличенным масштабом

Example

Получение текущего масштаба

const currentScale = await editorApi.document.zoom.getZoomLevel();
console.log('Текущий масштаб:', currentScale + '%');

Установка конкретного масштаба

// Установить 150% масштаб
editorApi.document.zoom.setZoomLevel(150);

// Установить пользовательский масштаб
editorApi.document.zoom.setZoomLevel(123);

Увеличение и уменьшение масштаба

// Увеличить масштаб на один уровень
editorApi.document.zoom.zoomIn();

// Уменьшить масштаб на один уровень
editorApi.document.zoom.zoomOut();

Создание кнопок масштабирования в UI

export default {
  onInit: (editorApi) => {
    editorApi.ui.ribbon.registerButton({
      id: 'zoomInBtn',
      title: 'Увеличить',
      icon: 'zoom-in',
      onClick: () => editorApi.document.zoom.zoomIn()
    });

    editorApi.ui.ribbon.registerButton({
      id: 'zoomOutBtn',
      title: 'Уменьшить',
      icon: 'zoom-out',
      onClick: () => editorApi.document.zoom.zoomOut()
    });

    editorApi.ui.ribbon.registerButton({
      id: 'zoom100Btn',
      title: '100%',
      onClick: () => editorApi.document.zoom.setZoomLevel(100)
    });
  }
}

Сохранение и восстановление масштаба

// Сохранить текущий масштаб
const currentScale = await editorApi.document.zoom.getZoomLevel();
localStorage.setItem('documentScale', currentScale?.toString() || '100');

// Восстановить масштаб при загрузке
const savedScale = parseInt(localStorage.getItem('documentScale') || '100');
editorApi.document.zoom.setZoomLevel(savedScale);

Оптимизация под размер экрана

async function optimizeScaleForScreen() {
  const zoom = await editorApi.document.zoom.getZoomLevel();

  // Если экран узкий, уменьшить масштаб
  if (window.innerWidth < 1024) {
    editorApi.document.zoom.setZoomLevel(75);
  }
  // Если экран большой, можно увеличить
  else if (window.innerWidth > 1600) {
    editorApi.document.zoom.setZoomLevel(125);
  }
}

See

DocumentApi.zoom — доступ к ZoomApi

Methods

getZoomLevel()

getZoomLevel(): Promise<null | number>

Получает текущий масштаб документа в процентах.

Returns

Promise<null | number>

Promise с текущим масштабом (например, 100, 150, 75) или null, если масштаб не установлен

Remarks

Возвращаемые значения:

• процент масштаба: число от 50 до 400, например: 100 при масштабе 100%, 75 при 75% и так далее
• null — масштаб не определён (редко)

Асинхронность:

• Метод асинхронный, использует Promise
• Операция быстрая (обычно < 1мс)
• Всегда резолвится успешно (не выбрасывает ошибок)

Example

const zoom = await editorApi.document.zoom.getZoomLevel();

if (zoom) {
  console.log(`Текущий масштаб: ${zoom}%`);
} else {
  console.log('Масштаб не установлен');
}

Проверка масштаба и реакция на него

const currentZoom = await editorApi.document.zoom.getZoomLevel();

if (currentZoom && currentZoom < 100) {
  console.log('Документ отображается меньше стандартного размера');
} else if (currentZoom && currentZoom > 100) {
  console.log('Документ увеличен');
}

See

ZoomApi.setZoomLevel — для установки масштаба

---

setZoomLevel()

setZoomLevel(percentageZoom): void

Устанавливает произвольный масштаб документа в процентах.

Parameters

percentageZoom

number

Число, обозначающее новый масштаб в процентах

Returns

void

Remarks

Допустимые значения:

• От 50 до 400 (процентов)
• Рекомендуемый диапазон: 50-300
• Вне диапазона 50-400 значение будет автоматически приведено к границам

Примеры допустимых значений:

• 50 — половина обычного размера
• 75 — три четверти размера
• 100 — стандартный размер
• 123 — нестандартный масштаб (123%)
• 200 — двойной размер
• 400 — максимальный масштаб

Поведение:

• изменение масштаба видно пользователю без задержки
• Изменение не блокирует редактирование документа
• Масштаб не влияет на размер при печати или экспорте

Примечание:

• setZoom() синхронный метод (не возвращает Promise)
• Изменение масштаба сохраняется в сессии, но не в документе (при перезагрузке страницы масштаб будет 100%)

Example

// Установить 100% (стандартный размер)
editorApi.document.zoom.setZoomLevel(100);

// Установить 50% (половина размера)
editorApi.document.zoom.setZoomLevel(50);

// Установить 200% (двойной размер)
editorApi.document.zoom.setZoomLevel(200);

Установка пользовательского масштаба

// Установить нестандартный масштаб 123%
editorApi.document.zoom.setZoomLevel(123);

// Установить 87% для специфичного представления
editorApi.document.zoom.setZoomLevel(87);

Масштабирование для разных типов документа

async function setOptimalScale() {
  // Получить текущий масштаб
  const current = await editorApi.document.zoom.getZoomLevel();

  // Установить масштаб в зависимости от типа документа
  if (editorApi.document.type === 'presentation') {
    editorApi.document.zoom.setZoomLevel(75); // Презентации часто нужно уменьшать
  } else if (editorApi.document.type === 'spreadsheet') {
    editorApi.document.zoom.setZoomLevel(80); // Таблицы часто узкие
  }
}

Валидация и установка масштаба

function setSafeScale(scale: number) {
  // Убедиться, что масштаб в допустимом диапазоне от 100 до 250
  const validScale = Math.max(100, Math.min(250, scale));
  editorApi.document.zoom.setZoomLevel(validScale);
}

See

• ZoomApi.getZoomLevel — для получения текущего масштаба
• ZoomApi.zoomIn — для увеличения масштаба
• ZoomApi.zoomOut — для уменьшения масштаба

---

zoomIn()

zoomIn(): void

Увеличивает масштаб до ближайшего предзаданного значения

Returns

void

Remarks

Предзаданные масштабы:

• 50% → 60% → 70% → 80% → 90% → 100% → 110% → 120% → 130% → ...

Поведение:

• Если текущий масштаб 100%, увеличится до 110%
• Если текущий масштаб 150%, увеличится до 160%
• На максимальном масштабе (400%) дальше не увеличивается
• Если текущий масштаб не предзаданный (123%), перейдёт на ближайший больший предзаданный (130%)

В сочетании с decreaseScale() позволяет реализовать кнопки +/– для масштабирования

Example

// Увеличить масштаб на один уровень
editorApi.document.zoom.zoomIn();

Увеличение с уведомлением

async function zoomIn() {
  editorApi.document.zoom.zoomIn();

  // Показать текущий масштаб в уведомлении
  const newScale = await editorApi.document.zoom.getZoomLevel();
  editorApi.ui.toasts.showToast({ id, content: `Масштаб: ${newScale}%` });
}

See

• ZoomApi.zoomOut — противоположная операция
• ZoomApi.setZoomLevel — для установки конкретного масштаба
• ZoomApi.getZoomLevel — для получения текущего масштаба

---

zoomOut()

zoomOut(): void

Уменьшает масштаб до ближайшего предзаданного значения

Returns

void

Remarks

Предзаданные масштабы:

• ... → 130% → 120% → 110% → 100% → 90% → 80% → 70% → 60% → 50%

Поведение:

• Если текущий масштаб 100%, уменьшится до 90%
• Если текущий масштаб 150%, уменьшится до 140%
• На минимальном масштабе (50%) дальше не уменьшается
• Если текущий масштаб не предзаданный (123%), перейдёт на ближайший меньший предзаданный (120%)

В сочетании с increaseScale() позволяет реализовать кнопки +/– для масштабирования

Когда использовать:

• Для обзора всего документа
• Адаптация под маленькие экраны
• Сделать снимок страницы целиком

Example

// Уменьшить масштаб на один уровень
editorApi.document.zoom.zoomOut();

Создание кнопки уменьшения в UI

editorApi.ui.ribbon.registerButton({
  id: 'zoomOutBtn',
  title: 'Уменьшить (Ctrl+-)',
  icon: 'zoom-out',
  onClick: () => editorApi.document.zoom.zoomOut()
});

Уменьшение с уведомлением

async function zoomOut() {
  editorApi.document.zoom.zoomOut();

  // Показать текущий масштаб в уведомлении
  const newZoom = await editorApi.document.zoom.getZoomLevel();
  editorApi.ui.toasts.showToast({ id, content: `Масштаб: ${newZoom}%` });
}

Логирование изменений масштаба

async function logZoomChange(direction: 'in' | 'out') {
  if (direction === 'in') {
    editorApi.document.zoom.zoomIn();
  } else {
    editorApi.document.zoom.zoomOut();
  }

  const newZoom = await editorApi.document.zoom.getZoomLevel();
  console.log(`Установлен масштаб ${newZoom}%`);
}

See

• ZoomApi.zoomIn — противоположная операция
• ZoomApi.setZoomLevel — для установки конкретного масштаба
• ZoomApi.getZoomLevel — для получения текущего масштаба