Связь данных и управление состоянием во Vue Gantt

Это руководство поможет вам выбрать, где ваше приложение владеет данными Gantt и как поддерживать синхронизацию правок на диаграмме. Выберите одну модель владения на каждой странице и придерживайтесь её.

Vue Gantt поддерживает две распространённые модели:

1. Vue-состояние или хранилище как источник истины (лучший выбор по умолчанию для большинства приложений)
2. Gantt как источник истины (ориентирована на производительность для страниц с большим количеством диаграмм)

Ментальная модель

Обёртка синхронизирует пропсы с активным экземпляром Gantt. Если пользователи редактируют данные на диаграмме, вы решаете, следует ли:

• обработчик обёртки обновляет состояние Vue (модель, управляемая Vue), или
• график/бэкэнд обрабатывает изменения напрямую (модель, управляемая Gantt)

Основная ловушка — смешанное владение. Если Vue и экземпляр Gantt одновременно выступают как источник правды, велика вероятность перезаписи устаревших данных.

Vue-состояние или хранилище как источник истины

В этой модели:

• Состояние Vue (или Pinia) владеет tasks и links
• обёртка получает массивы через пропсы
• правки диаграммы фиксируются через data.save или data.batchSave
• обработчики колбэков обновляют состояние
• обновлённое состояние возвращается во внешнюю обёртку

Рекомендованный тип для этой модели: используйте SerializedTask[] и SerializedLink[] для реактивных массивов состояния.

Best For

• страницы с окружающим Vue UI, которые должны отражать состояние диаграммы
• приложения, которые уже используют Pinia или централизованный слой состояния
• команды, которым нужна предсказуемая однонаправленная передача данных

Tradeoffs

• больше обновлений состояния приложения при тяжёлых операциях
• больше работы по синхронизации, когда много правок выполняется в одном действии диаграммы

Avoid These Patterns

• изменение данных задач/ссылок через instance, при этом продолжение передачи устаревших массивов из состояния Vue
• игнорирование колбэков обёртки и ожидание, что правки диаграммы автоматически сохранятся в состоянии Vue

Пример: Store/Vue- owned Flow

<script setup lang="ts">
import { ref } from "vue";
import VueGantt, {
  type SerializedLink,
  type SerializedTask,
  type VueGanttDataConfig
} from "@dhtmlx/trial-vue-gantt";

const tasks = ref<SerializedTask[]>([]);
const links = ref<SerializedLink[]>([]);

const data: VueGanttDataConfig = {
  save: (entity, action, item, id) => {
    if (entity === "task") {
      if (action === "create") tasks.value = [...tasks.value, item as SerializedTask];
      if (action === "update") tasks.value = tasks.value.map(t => String(t.id) === String(id) ? item as SerializedTask : t);
      if (action === "delete") tasks.value = tasks.value.filter(t => String(t.id) !== String(id));
    }

    if (entity === "link") {
      if (action === "create") links.value = [...links.value, item as SerializedLink];
      if (action === "update") links.value = links.value.map(l => String(l.id) === String(id) ? item as SerializedLink : l);
      if (action === "delete") links.value = links.value.filter(l => String(l.id) !== String(id));
    }
  }
};
</script>

<template>
  <VueGantt :tasks="tasks" :links="links" :data="data" />
</template>

Для операций с несколькими изменениями перейдите к data.batchSave и применяйте изменения пакетами.

Gantt как источник истины

В этой модели график и бэкенд управляют большинством жизненных циклов данных. Vue выполняет меньшее живое отражение.

Best For

• очень большие наборы данных
• интенсивное автоматическое планирование или потоки массового обновления
• страницы, ориентированные на диаграмму, где внешнее UI не требует видеть каждое живое изменение немедленно

Tradeoffs

• меньше видимости текущего состояния диаграммы в состоянии Vue/хранилища
• требуется больше дисциплины, если иногда вы возвращаете снимки пропсов во внешний обёртку

Avoid These Patterns

• частичное зеркалирование Vue без стратегии согласования
• повторная загрузка устаревших снимков сервера после редактирования диаграммы пользователями

Пример: поток владения Gantt

<script setup lang="ts">
import VueGantt from "@dhtmlx/trial-vue-gantt";

const data = {
  load: "/api/gantt/load",
  save: async (entity: string, action: string, payload: any, id: string | number) => {
    const response = await fetch(`/api/gantt/${entity}`, {
      method: action === "delete" ? "DELETE" : "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ action, payload, id })
    });

    // Созданные обработчики должны возвращать постоянный ID, если бэкенд переотмечает его.
    return await response.json();
  }
};
</script>

<template>
  <VueGantt :data="data" />
</template>

Контракты колбеков

Этот раздел охватывает формы колбеков обёртки, которые вы используете в обеих моделях владения.

data.save

save передаётся в gantt.createDataProcessor(save) и принимает одно изменение за раз.

Типичная форма функции:

(entity: string, action: string, data: any, id: string | number) => any

Используйте это, когда изменения в основном одиночные и их легко обрабатывать по одному.

data.batchSave

batchSave принимает изменения, сгруппированные в четыре корзины, по одному типу данных:

interface BatchChanges {
  tasks?: DataCallbackChange[];
  links?: DataCallbackChange[];
  resources?: DataCallbackChange[];
  resourceAssignments?: DataCallbackChange[];
}

Перебирайте те корзины, которые вам важны — обёртка заполняет их автоматически из событий изменений Gantt.

Кратко о поведении очереди:

• пакетирование на ближайшем этапе выгрузки
• create + update можно свести в один create с последней нагрузкой
• create + delete можно исключить из пакета
• внутренний !nativeeditor_status удаляется из полезной нагрузки

Используйте это, когда одно действие пользователя может привести к множеству обновлений (например, авто-планирование).

Переназначение идентификаторов и ответственность бэкенда

Действия создания часто начинаются с временных идентификаторов на стороне клиента.

• В режиме save ответы бэкенда должны возвращать постоянные идентификаторы, чтобы Gantt мог выполнить повторное отображение записей.
• В режиме batchSave пути возвращения по элементу нет. Если сервер присваивает идентификаторы, явно обрабатывайте переназначение в вашем процессе сохранения.

Ответственность бэкенда остаётся неизменной в обоих режимах:

• валидировать входящие полезные нагрузки
• приводить в исполнение разрешения
• сохранять авторитативные идентификаторы
• возвращать структуры данных, которые ожидает выбранный вами транспортный режим

Что читать дальше

• Использование Vue Gantt с Pinia
• Справка по конфигурации
• Паттерны настройки