ErdEditorElement

Редактор — це звичайний HTMLElement.
Його визначення типу таке.

interface ErdEditorElement extends HTMLElement {
  readonly: boolean;
  systemDarkMode: boolean; // system dark/light auto
  enableThemeBuilder: boolean;
  enableLocalePicker: boolean;
  enableWelcomeScreen: boolean;
  value: string;
  readonly runtimeValue: string;
  focus: () => void;
  blur: () => void;
  clear: () => void;
  destroy: () => void;
  setInitialValue: (value: string) => void;
  setPresetTheme: (themeOptions: Partial<ThemeOptions>) => void;
  setSystemAppearance: (appearance: 'dark' | 'light' | null) => void;
  setTheme: (theme: Partial<Theme>) => void;
  setLocale: (locale: LocaleOption) => void;
  setSystemLocale: (locale: string | null) => void;
  setKeyBindingMap: (
    keyBindingMap: Partial<
      Omit<
        KeyBindingMap,
        | 'edit'
        | 'stop'
        | 'undo'
        | 'redo'
        | 'zoomIn'
        | 'zoomOut'
        | 'zoomReset'
      >
    >
  ) => void;
  setSchemaSQL: SetSchema;
  setSchemaGraphQL: SetSchema;
  setSchemaDBML: SetSchema;
  setSchemaAML: SetSchema;
  setSchemaJSON: (
    value: string,
    options?: { mode?: 'replace' | 'append' }
  ) => void;
  getSchemaSQL: (
    databaseVendor?: DatabaseVendor,
    options?: SchemaSQLOptions
  ) => string;
  getSharedStore: (
    config?: SharedStoreConfig & {
      mouseTracker?: boolean;
      focusTracker?: boolean;
    }
  ) => SharedStore;
  setDiffValue: (value: string) => void;
}

Редактор рендериться в закритий тіньовий корінь (shadow root), тому editor.shadowRoot дорівнює null, а стилі сторінки не проникають ні всередину, ні назовні.
До вмісту редактора не можна дістатися селектором — натомість задавайте стилі через setTheme і користувацькі властивості --erd-editor-*.

readonly, system-dark-mode, enable-theme-builder, enable-locale-picker і enable-welcome-screen — єдині атрибути, і всі п’ять за замовчуванням мають значення false. Останні два нові у версії 4.0.0. Кожен із них зчитує своє значення так, як описано в розділі readonly.

Починаючи з версії 4.1.0, вкладка ERD має оглядач — дерево діаграми, закріплене ліворуч від полотна, з пошуком і заміною вгорі. Жоден атрибут, властивість, метод чи подія не відкриває його, не закриває й не повідомляє про нього: він відкривається кнопкою Explorer на панелі інструментів, пунктом Toggle Explorer у швидкому пошуку чи контекстному меню полотна або прив’язкою findReplace.
Кожен елемент починає роботу із закритим оглядачем. Те, чи він відкритий, його ширина, згортання й пошук зберігаються весь час існування елемента — попри перемикання вкладок і кожне завантаження, зокрема через setInitialValue, — і ніколи не потрапляють до value, runtimeValue, історії змін або спільного сховища.

readonly

Керує можливістю редагування в редакторі.
Поки його задано, присвоєння value, clear(), setSchemaSQL(), setSchemaGraphQL(), setSchemaDBML(), setSchemaAML(), setSchemaJSON(), відміна й повторення ігноруються, а подія change ніколи не генерується. Натомість завантажуйте документ за допомогою setInitialValue.
Перегляд і далі працює: масштаб, панорамування, інструмент «Рука», режим дзен, вкладка полотна, вкладка візуалізації в обох режимах, зокрема фокусування на таблицях, вибрана СУБД, а також налаштування виводу SQL і генератора коду — усе це діє, тож у редакторі в режимі лише для читання все одно можна експортувати SQL для іншої СУБД або читати згенерований код.
Починаючи з версії 4.1.0, відкривається й оглядач, а вибір одного з його рядків веде до того, що цей рядок позначає, як і в редакторі, доступному для редагування. Панель пошуку й заміни вгорі оглядача лише шукає, без стрілки Toggle Replace і без рядка заміни, а перехід до збігу, як і раніше, показує його в області перегляду й виділяє. Панель має назву Explorer, а підказка кнопки на панелі інструментів — Explorer (Ctrl + F) (Windows/Linux) або Explorer (⌘ + F) (Mac) у будь-якому редакторі. Від 3.10.0 до 4.0.0 пошук і заміна відкривалися як плаваюча панель лише для пошуку з назвою Find.
Вікно властивостей таблиці й далі відкривається і, починаючи з версії 3.10.0, показує позначку Read only поруч із заголовком, а його вкладка Indexes не дозволяє нічого змінювати — див. властивості таблиці.
Починаючи з версії 4.0.0, редактор у режимі лише для читання не пропонує пунктів Import and Add, New Table Group, Group selected tables, Remove from group (див. групи таблиць) і Map Columns та не показує вітального екрана. Кнопки блокування на вкладці налаштувань нічого не змінюють, а скрипти Before tables і After tables на вкладці схеми SQL не можна редагувати.
Починаючи з версії 4.1.0, він також не показує кнопок New Table, New Memo і New Table Group на панелі інструментів полотна, а прив’язки addTableGroup і groupSelectedTables нічого не роблять.
Варіанти This window only на вкладці схеми SQL — Statements, Header і Tables — ніколи не зберігаються, але й далі діють; так само працюють діалогове вікно Export image, конструктор теми й панель вибору мови інтерфейсу. Вибір у конструкторі теми чи на панелі вибору мови інтерфейсу, як і раніше, генерує подію changePresetTheme або changeLocale.
Атрибут без значення, ="" і ="true" зчитуються як true. ="false" зчитується як false, як і будь-який інший рядок — зокрема типовий для HTML запис readonly="readonly".

editor.readonly = true;
// or
editor.setAttribute('readonly', 'true');

<erd-editor readonly></erd-editor>

systemDarkMode

Визначає, чи автоматично синхронізуватися з темним/світлим режимом системи.
Починаючи з версії 4.0.0, його ввімкнення встановлює для appearance теми значення 'system', як і setPresetTheme({ appearance: 'system' }). Тоді редактор показує світлий або темний вигляд, про який повідомляє операційна система, або той, що задано через setSystemAppearance, і перемикається, коли він змінюється.
Пізніший виклик setPresetTheme зі значенням 'light' або 'dark' чи вибір Light або Dark у конструкторі теми чи швидкому пошуку замінює 'system' і зберігається: наступна зміна в ОС його вже не перезаписує, хоча systemDarkMode і далі має значення true. До версії 4.0.0 наступна зміна в ОС його перезаписувала.
Вимкнення, поки вигляд має значення 'system', залишає світлий або темний вигляд, показаний у цей момент. Вимкнення після того, як вигляд змінено з 'system' на інший, залишає його без змін.
Його зміна не генерує жодної події.

editor.systemDarkMode = true;
// or
editor.setAttribute('system-dark-mode', 'true');

<erd-editor system-dark-mode></erd-editor>

enableThemeBuilder

Визначає, чи надаються засоби для зручного вибору готових тем.
Він показує на панелі інструментів кнопку Theme, яка відкриває конструктор теми з параметрами Accent color, Gray color і Appearance. Починаючи з версії 4.0.0, параметр Appearance пропонує System поряд із Light і Dark, а поки цей атрибут увімкнено, швидкий пошук показує пункт Theme з варіантами System, Light і Dark. Див. мова й тема.

editor.enableThemeBuilder = true;
// or
editor.setAttribute('enable-theme-builder', 'true');

<erd-editor enable-theme-builder></erd-editor>

Зміна готової теми на цій панелі або у швидкому пошуку генерує подію changePresetTheme.

enableLocalePicker

Починаючи з версії 4.0.0, визначає, чи надаються засоби для вибору мови інтерфейсу редактора.
Він показує на панелі інструментів кнопку Display Language — після Theme, коли показано обидві. Кнопка відкриває панель вибору мови інтерфейсу, а швидкий пошук показує пункт Display Language. І панель, і швидкий пошук пропонують System та 25 мов — див. мова й тема.
Він також визначає, що показує редактор, доки не викликано setLocale або не вибрано мову: 'system', коли його ввімкнено, і англійську, коли вимкнено, тож елемент без жодних налаштувань і далі показує англійську, як завжди. Увімкнення чи вимкнення одразу перемикає між цими двома варіантами. Щойно мову задано або вибрано, цей вибір зберігається незалежно від того, увімкнено атрибут чи вимкнено.
Задайте його до того, як елемент буде додано на сторінку, щоб уже перший кадр відповідав 'system'.
Вибір мови генерує подію changeLocale.

editor.enableLocalePicker = true;
// or
editor.setAttribute('enable-locale-picker', 'true');

<erd-editor enable-locale-picker></erd-editor>

enableWelcomeScreen

Починаючи з версії 4.0.0, визначає, чи зустрічає порожня діаграма користувача вітальним екраном.
Він показується поверх вкладки ERD, поки в документі немає жодної таблиці, жодної показаної нотатки й жодної показаної групи таблиць. Він не показується, поки задано readonly, у режимі дзен або поки відкрито вікно властивостей таблиці, перегляд відмінностей, подорож у часі чи попередній перегляд автоматичного розміщення. Перша таблиця, показана нотатка чи показана група таблиць прибирає його, а відміна, що повертає діаграму до порожнього стану, знову його показує.
Його рядки New Table, New Memo і Command Palette показують перше сполучення прив’язок addTable, addMemo і search у тому вигляді, в якому їх залишив setKeyBindingMap, і жодного — для назви прив’язки, залишеної порожньою. Його стрілки вказують на кнопки Theme і Display Language лише там, де їх показують enableThemeBuilder і enableLocalePicker.
У його меню ↑, ↓, Home і End переміщують фокус між рядками, а їхня типова дія скасовується й поширення зупиняється. Для Enter і Space поширення зупиняється, але типова дія не скасовується, тож їх отримує рядок у фокусі, а Escape серед форматів Import повертає назад зі скасуванням типової дії та зупинкою поширення. Будь-яка інша клавіша, як зазвичай, доходить до редактора й сторінки.
Він нічого не змінює в документі, тож залишає value без змін і не генерує події change.
Вмикайте його після того, як setInitialValue завантажить документ, як це роблять офіційні хости, щоб екран ніколи не блимав поверх файлу, який ще завантажується.

editor.enableWelcomeScreen = true;
// or
editor.setAttribute('enable-welcome-screen', 'true');

<erd-editor enable-welcome-screen></erd-editor>

value

getter

Повертає поточний документ як рядок JSON за схемою, яку визначає редактор.
Починаючи з версії 4.0.0, це форма зберігання — документ у тому вигляді, у якому його містить файл; саме це записує експорт json і зберігають офіційні хости. Вона містить лише наявні сутності, без видалених, без порядку накладання й без того, що редактор обчислює сам, як-от виміряні ширини, позначки ключів і точки прив’язки зв’язків. Ключі її сутностей ідуть у фіксованому порядку, відступ — два пробіли, а в кінці стоїть символ нового рядка, тож той самий документ завжди дає ті самі байти.
Кожне налаштування з увімкненим блокуванням записується із заблокованим значенням, а не так, як його показує екран. Блокування Viewport утримує originX, originY і zoomLevel, а блокування Canvas Type, Language, Table Name Case, Column Name Case і Bracket Type утримують кожне власне налаштування. Кожне інше налаштування записується з поточним значенням, а lockSettings записується завжди. Про відповідні біти див. Settings.
У новому документі ввімкнено всі блокування — чи то документ, який елемент показує до отримання значення, чи то завантажений із порожнього значення. Його value зберігає початок координат 0, 0, рівень масштабу 1, вкладку ERD, а також мову генератора коду, стилі назв і тип лапок за замовчуванням, доки не буде вимкнено відповідне блокування.
До версії 4.0.0 він повертав увесь документ у тому вигляді, у якому його тримав редактор, із застосованим ignoreSaveSettings. Документ у тому вигляді, у якому його тримає редактор, тепер доступний як runtimeValue, а ignoreSaveSettings більше не зчитується й не записується.

const data = editor.value;

setter

Завантажує раніше збережений стан редактора. Він замінює весь документ — поточний спочатку очищається.
Як і clear(), setInitialValue() та методи setSchema* у типовому режимі mode: 'replace', він також скидає подання в режимі Flow на вкладці візуалізації: його розміщення, таблиці, якими його обмежено, відображення рядків, масштаб і панорамування. Додавання (mode: 'append') його не скидає.
Він записується в історію змін, що дає змогу виконувати Undo, Redo, і генерує подію change.
Він приймає форму зберігання, значення runtimeValue або файл, збережений попереднім випуском.
Порожній рядок або будь-що, що не є рядком, завантажує новий документ замість того, щоб викликати помилку, тож перевіряйте значення перед присвоєнням.
Цей новий документ — той самий, з якого починає setInitialValue(''): порожній, з налаштуваннями за замовчуванням і, починаючи з версії 4.0.0, з усіма ввімкненими блокуваннями. У 3.10.x він не зберігав ні положення прокручування, ні рівня масштабу, а до того зберігав обидва.
Спільне сховище пересилає це завантаження співавторам разом із повним JSON нового документа, тож кожен учасник, зокрема зі старішим випуском, завантажує той самий документ.
Починаючи з версії 4.0.0, блокування завантаженого документа й заблоковані значення, які потім записує value, беруться з тексту, а область перегляду опиняється там, де її розміщує текст, або на діаграмі, якщо в тому місці не видно жодної її частини. Для кожного іншого налаштування, яке блокує текст, — вкладки, мови генератора коду, стилів назв і типу лапок — редактор і далі показує те, що показував до завантаження. Налаштування, яке текст залишає незаблокованим, отримує значення з тексту. setInitialValue натомість бере всі значення, що містить текст; там же описано текст, у якому не названо жодного блокування.
Текст, що не є JSON, як-от файл із залишеними маркерами конфлікту злиття, теж не викликає помилки: документ очищається, його налаштування лишаються без змін, а помилка розбору виводиться в консоль.
Він ігнорується, поки задано readonly; щоб завантажити документ у редактор у режимі лише для читання, використовуйте setInitialValue.

editor.value = 'json...';

runtimeValue

Починаючи з версії 4.0.0, повертає документ у тому вигляді, у якому його тримає цей редактор, як рядок JSON. Сетера немає, тож присвоєння значення в коді в строгому режимі викидає виняток.
Це значення містить те, що пропускає value: видалені сутності та їхній порядок, порядок накладання, виміряні ширини, позначки ключів, точки прив’язки зв’язків і послідовності. Заблоковані налаштування тут теж записуються із заблокованими значеннями.
Використовуйте його, щоб через setInitialValue ініціалізувати інший редактор, який приєднується до вже запущеного сеансу, як-от редактор співавтора чи друге подання того самого документа. Тоді відміна видалення, яку сеанс надішле пізніше, повністю відновлює там сутність, а редактор, ініціалізований із value, не містить видаленої сутності й натомість відновлює порожню таблицю без назви. Див. спільне редагування.
Видалені сутності більше ніщо не прибирає, тож вони лишаються в ньому, доки документ наступного разу не відкриють із файлу.
Ніколи не записуйте його у файл: зберігайте value, яке приймає JSON Schema, а це значення — ні.

otherEditor.setInitialValue(editor.runtimeValue);

setInitialValue

Завантажує раніше збережений стан редактора. Саме завантаження не записується в історію змін, тож його не можна відмінити, і подія change не генерується.
Він також очищає історію змін, тож нічого, зробленого до завантаження, не можна відмінити чи повторити на завантаженому документі.
Він приймає форму зберігання, значення runtimeValue або файл, збережений попереднім випуском, і, на відміну від присвоєння value, бере всі налаштування, що містить текст, зокрема вкладку й налаштування коду.
Порожній рядок або будь-що, що не є рядком, завантажує новий документ замість того, щоб викликати помилку, тож setInitialValue('') починає порожню діаграму.
Починаючи з версії 4.0.0, у цьому новому документі, який також показує елемент до отримання будь-якого значення, ввімкнено всі блокування. Прокручування, масштабування, перемикання вкладок і зміна мови генератора коду, стилів назв чи типу лапок залишають value без змін і не генерують події change. У 3.10.x він не зберігав ні положення прокручування, ні рівня масштабу, а до того зберігав обидва.
Документ, завантажений із тексту, зберігає названі в ньому блокування. Документ, у якому їх не названо, — будь-який файл, збережений до версії 4.0.0, незалежно від його ignoreSaveSettings, і файл .vuerd формату v2 — відкривається з усіма ввімкненими блокуваннями, із Viewport, заблокованим на початку координат 0, 0 і рівні масштабу 1, на вкладці ERD, з мовою, стилями назв і типом лапок у тому вигляді, у якому їх було збережено.
В обох випадках область перегляду відкривається там, де її задає документ, — у збереженому в тексті положенні, якщо текст називає свої блокування, або на початку координат 0, 0 з рівнем масштабу 1, якщо не називає, — або на діаграмі, якщо в тому місці не видно жодної її частини. Заблокований Viewport і далі зберігає свої заблоковані значення у value.
Починаючи з версії 4.0.0, він також скидає стан спільного редагування документа, завантаженого раніше, а вже підписане спільне сховище цього редактора знову запитує в інших редакторів їхній стан, тож редактор, перезавантажений у запущеному сеансі, наздоганяє інших. Ініціалізуйте такий редактор значенням runtimeValue іншого редактора.
Текст, що не є JSON, теж не викликає помилки: документ очищається, його налаштування лишаються без змін, а помилка розбору виводиться в консоль.
На відміну від присвоєння value, його не блокує readonly, тож саме так документ завантажують у редактор у режимі лише для читання.

editor.setInitialValue('json...');

Завантажити під час запуску, зберегти під час зміни.

editor.setInitialValue(localStorage.getItem('my-diagram') ?? '');
editor.addEventListener('change', () => {
  localStorage.setItem('my-diagram', editor.value);
});

Події

change, changePresetTheme і changeLocale — єдині три публічні події; подія changeLocale нова у версії 4.0.0.
Елемент також генерує на собі внутрішні події @dineug/erd-editor/internal-* для власної внутрішньої взаємодії; вони не є частиною API.

change

Коли в редакторі відбуваються зміни, він генерує подію.
Подія генерується із затримкою (debounce) 200 мс і не генерується, поки readonly має значення true.
Вона спрацьовує за будь-якої зміни документа — зміни в інтерфейсі, присвоєння value, clear(), кожного з методів setSchema*, а також, починаючи з версії 4.0.0, setSchemaJSON() і Import and Add. setInitialValue її не генерує.
Ніщо, зроблене в режимі Flow на вкладці візуалізації, її не генерує — ні масштабування, ні панорамування, ні переміщення карток, ні Tidy Up, ні відображення рядків, ні звуження подання з картки, — бо ніщо з цього не є зміною документа.
Починаючи з версії 4.0.0, її не генерує й зміна налаштування з увімкненим блокуванням, бо вона змінює лише екран і ніколи не змінює value: прокручування чи масштабування полотна ERD, поки заблоковано Viewport, перемикання вкладки, поки заблоковано Canvas Type, і зміна мови генератора коду, стилю назв таблиць, стилю назв стовпців чи типу лапок, поки ввімкнено власне блокування відповідного налаштування. Пропускаються лише ці зміни, тож пакет, який також редагує документ, усе одно її генерує. Блокування чи розблокування налаштування її генерує.
У новому документі та в будь-якому файлі, збереженому до версії 4.0.0, ввімкнено всі блокування, тож за замовчуванням прокручування, масштабування й перемикання вкладок нічого не генерують. Це стосується фокусування на таблицях із вкладки ERD, кнопки зовнішнього посилання на картці, яка повертає вас із режиму Flow на вкладку ERD, переходу до рядка оглядача чи збігу пошуку, а також відкриття оглядача чи переходу до результату швидкого пошуку з іншої вкладки. Кожна з цих дій генерує одну подію change лише тоді, коли вимкнено блокування, що її охоплює: Canvas Type — для перемикання вкладки, а Viewport — для прокручування, яке також виконують кнопка на картці, результат швидкого пошуку, рядок оглядача чи збіг пошуку. Починаючи з версії 4.1.0, усі ці прокручування підпорядковуються одному правилу — куди веде перехід, — тож результат швидкого пошуку для таблиці вже не прокручує полотно щоразу, а перехід, який правило залишає на місці, не виконує прокручування, тож і генерувати нічого. Відкриття, закриття чи зміна розміру оглядача звужує або розширює полотно, не зміщуючи його початку координат, і теж нічого не генерує. До версії 4.0.0 прокручування, масштабування й перемикання вкладок завжди її генерували, навіть коли editor.value лишалося тим самим.
Щоб пропускати записи, які нічого не змінюють, порівнюйте editor.value зі значенням, яке ви зберегли востаннє, а не із завантаженим файлом: файл, записаний попереднім випуском, файл формату v2 чи відредагований вручну може відрізнятися у value одразу після завантаження, бо value записує його у формі зберігання. Так само може відрізнятися файл, у якому блокування Viewport вимкнено, а початок координат на цьому екрані не показує жодної частини діаграми: завантаження переміщує область перегляду на діаграму, і value записує, де вона опинилася. Починаючи з версії 4.0.0, виміряні ширини більше цього не спричиняють, бо value їх не містить. Хост, який записує файли, може натомість відрізнити редагування від зміни області перегляду за допомогою changed сховища реплікації — див. on@change.
Подія не містить detail, не спливає й не перетинає межу тіньового DOM, тож слухайте її на самому елементі й читайте editor.value в обробнику.

editor.addEventListener('change', event => {
  const data = event.target.value;
});

changePresetTheme

Генерується, коли готову тему змінено у вбудованому конструкторі теми або, починаючи з версії 4.0.0, через пункт Theme у швидкому пошуку. Її генерує кожен вибір, зокрема й вибір уже чинного варіанта.
Самостійний виклик setPresetTheme чи setSystemAppearance або ввімкнення чи вимкнення systemDarkMode її не генерує.
event.detail — це повний об’єкт ThemeOptions після вибору — { appearance, grayColor, accentColor }, — а не частковий, який було запитано. Починаючи з версії 4.0.0, його appearance має значення 'system', поки вибрано System, а не світлий чи темний вигляд, який показується, тож зберігайте його як є й передавайте назад у setPresetTheme.

editor.addEventListener('changePresetTheme', event => {
  const themeOptions = event.detail;
});

changeLocale

Починаючи з версії 4.0.0, генерується, коли в редакторі вибрано мову — на панелі вибору мови інтерфейсу або через пункт Display Language у швидкому пошуку; обидва варіанти вмикає enableLocalePicker.
Вона спрацьовує після застосування мови, за кожного вибору, зокрема й вибору вже чинного варіанта. setLocale і setSystemLocale ніколи її не генерують, як і зміна мов браузера. Перемикання мови не генерує події change.
event.detail — це { locale }, значення типу LocaleOption: 'system', якщо вибрано System, інакше код мови. Елемент не запам’ятовує вибір, тож зберігайте його й передавайте в setLocale під час наступного завантаження.
Як і change, вона не спливає, тож слухайте її на самому елементі.

editor.addEventListener('changeLocale', event => {
  const { locale } = event.detail; // 'system' | 'ko-KR' | ...
});

focus

Передає фокус редактору.

editor.focus();

blur

Знімає фокус із редактора.

editor.blur();

clear

Очищає документ, видаляючи всі таблиці, стовпці, зв’язки, індекси й нотатки, а також, починаючи з версії 4.0.0, усі групи таблиць.
Усі налаштування лишаються, зокрема база даних, положення області перегляду, рівень масштабу, параметри відображення таблиць, кожне блокування з його значенням, а також скрипти Before tables і After tables на вкладці схеми SQL, тож очищений файл і далі зберігає те, що зберігав. Щоб натомість почати новий документ, присвойте '' властивості value або викличте setInitialValue('').
Він записується в історію змін, тож його можна відмінити, і генерує подію change. Відміна повертає документ у тому вигляді, у якому його тримав редактор, кожне заблоковане налаштування — із заблокованим значенням. Він ігнорується, поки задано readonly.

editor.clear();

destroy

Повністю знищує екземпляр редактора, тож його більше не можна використати повторно.
Він звільняє слухачі та підписки редактора й знищує всі спільні сховища, повернуті getSharedStore.
Потоковий пакет, який спільне сховище ще утримує, відкидається разом із ним; щоб надіслати його, спершу викличте flushStreamBuffers цього сховища.

editor.destroy();

setKeyBindingMap

Перевизначає сполучення клавіш.
edit, stop, undo, redo, zoomIn, zoomOut і zoomReset фіксовані, їх не можна перевизначити.
Записується лише двадцять одна назва з переліку нижче; усе інше в об’єкті ігнорується, зокрема фіксовані назви.
Починаючи з версії 3.10.0, прив’язку search можна перевизначити, а також з’явилася прив’язка findReplace. Раніше прив’язка search була фіксованою. Починаючи з версії 4.0.0, з’явилася прив’язка removeSelection. Починаючи з версії 4.1.0, з’явилися addTableGroup і groupSelectedTables.
Значення прив’язки має бути типу ShortcutOption[]. Простий рядок ігнорується, тож пишіть { addTable: [{ shortcut: 'Alt+KeyN' }] }, а не { addTable: 'Alt+KeyN' }.
Порожній масив приймається й нічого не прив’язує: setKeyBindingMap({ findReplace: [] }) залишає Ctrl + F (Windows/Linux) або ⌘ + F (Mac) сторінці, а { search: [] } робить те саме для Ctrl + K (Windows/Linux) або ⌘ + K (Mac). Кнопка Search на панелі інструментів і далі відкриває швидкий пошук, кнопка Explorer на панелі інструментів і далі відкриває й закриває оглядач, а пункт Toggle Explorer у швидкому пошуку та в контекстному меню полотна і далі відкриває пошук в оглядачі або закриває оглядач; жоден із них не показує сполучення клавіш для назви прив’язки, залишеної порожньою. { removeSelection: [] } залишає Delete і Backspace сторінці, і тоді пункти видалення в меню таблиці, нотатки й групи таблиць (Delete, Delete selected, Delete column, Delete columns) не показують сполучення клавіш.
Починаючи з версії 4.1.0, { addTableGroup: [] } залишає сторінці Alt + G (Windows/Linux) або ⌥ + G (Mac), а { groupSelectedTables: [] } — T, потім G. New Table Group на панелі інструментів полотна, у контекстному меню полотна та у швидкому пошуку, Group selected tables у меню таблиці та Group Selected Tables у швидкому пошуку й далі працюють, але без показу сполучення клавіш. Підказки кнопок New Table, New Memo і New Table Group на панелі інструментів полотна називають перше сполучення прив’язок addTable, addMemo і addTableGroup або лише кнопку, якщо прив’язку залишено порожньою.
Виклик виконує часткове злиття: назви, які ви не вказали, зберігають типові значення, а повторний виклик зберігає попередні зміни. Гетера для поточних прив’язок немає: createKeyBindingMap повертає типові прив’язки, а не те, що змінив setKeyBindingMap.

type ShortcutOption = {
  shortcut: string;
  preventDefault?: boolean;
  stopPropagation?: boolean;
};

const defaultKeyBindingMap: Omit<
  KeyBindingMap,
  | 'edit'
  | 'stop'
  | 'undo'
  | 'redo'
  | 'zoomIn'
  | 'zoomOut'
  | 'zoomReset'
> = {
  search: [
    { shortcut: '$mod+KeyK', preventDefault: true, stopPropagation: true },
  ],
  findReplace: [
    { shortcut: '$mod+KeyF', preventDefault: true, stopPropagation: true },
  ],
  addTable: [{ shortcut: 'Alt+KeyN', preventDefault: true }],
  addColumn: [{ shortcut: 'Alt+Enter', preventDefault: true }],
  addMemo: [{ shortcut: 'Alt+KeyM', preventDefault: true }],
  addTableGroup: [
    { shortcut: 'Alt+KeyG', preventDefault: true, stopPropagation: true },
  ],
  groupSelectedTables: [{ shortcut: 'KeyT KeyG', preventDefault: true }],
  removeTable: [
    { shortcut: '$mod+Backspace', preventDefault: true },
    { shortcut: '$mod+Delete', preventDefault: true },
  ],
  removeColumn: [
    { shortcut: 'Alt+Backspace', preventDefault: true },
    { shortcut: 'Alt+Delete', preventDefault: true },
  ],
  removeSelection: [
    { shortcut: 'Delete', preventDefault: true },
    { shortcut: 'Backspace', preventDefault: true },
  ],
  primaryKey: [{ shortcut: 'Alt+KeyK', preventDefault: true }],
  selectAllTable: [
    { shortcut: '$mod+KeyA', preventDefault: true },
    { shortcut: '$mod+Alt+KeyA', preventDefault: true },
  ],
  selectAllColumn: [{ shortcut: 'Alt+KeyA', preventDefault: true }],
  relationshipZeroOne: [{ shortcut: '$mod+Alt+Digit1', preventDefault: true }],
  relationshipZeroN: [{ shortcut: '$mod+Alt+Digit2', preventDefault: true }],
  relationshipOneOnly: [{ shortcut: '$mod+Alt+Digit3', preventDefault: true }],
  relationshipOneN: [{ shortcut: '$mod+Alt+Digit4', preventDefault: true }],
  tableProperties: [{ shortcut: 'Alt+Space', preventDefault: true }],
  focusView: [
    { shortcut: 'Alt+KeyF', preventDefault: true, stopPropagation: true },
  ],
  handTool: [{ shortcut: 'Space', preventDefault: true }],
  zenMode: [
    { shortcut: 'Alt+KeyZ', preventDefault: true, stopPropagation: true },
  ],
};

// example
editor.setKeyBindingMap({
  addTable: [{ shortcut: '$mod+KeyN', preventDefault: true }],
});

selectAllTable, handTool, removeSelection і, починаючи з версії 4.1.0, groupSelectedTables поступаються текстовому курсору: поки фокус перебуває в полі введення, текстовій області чи елементі contenteditable, $mod + A виділяє текст, Space вводить пробіл, Delete і Backspace стирають текст, а T, потім G вводить ці дві літери, замість того щоб дійти до полотна. Для жодного з цих натискань типова дія не скасовується. Будь-яке сполучення, яке ви їм призначите, поводиться так само.

Починаючи з версії 4.0.0, removeSelection (Delete або Backspace) видаляє виділене на вкладці ERD як один крок відміни, без запиту. Коли виділено лише таблицю у фокусі, у ній виділено один або кілька стовпців, а за поточного масштабу її рядки відображаються, прив’язка видаляє ці стовпці; інакше вона видаляє всі виділені таблиці, нотатки й групи таблиць, а таблиці групи залишаються. Див. видалення таблиць і нотаток.
Утримувана клавіша видаляє один раз, і нічого не видаляється, поки відкрито редактор клітинки чи нотатки або поле назви групи таблиць. Поза текстовим полем і панелями, що затримують прив’язки (див. createKeyBindingMap), типова дія натискання скасовується на кожній вкладці, поки редактор має фокус, зокрема й на кнопці панелі інструментів у фокусі, а також у редакторі в режимі лише для читання, де воно нічого не видаляє.

Починаючи з версії 4.1.0, addTableGroup (Alt+KeyG) вмикає на вкладці ERD малювання New Table Group: наступне натискання основної кнопки миші на полотні малює групу, а повторне натискання прив’язки вимикає малювання, як і кнопка New Table Group на панелі інструментів полотна. groupSelectedTables (KeyT KeyG, T, потім G) поміщає виділені таблиці в нову групу й відкриває поле її назви, як і пункт Group selected tables у контекстному меню таблиці. Якщо не виділено жодної таблиці, вона нічого не додає; виділена нотатка чи група таблиць не враховується. Див. малювання групи і групування виділених таблиць.
Обидві прив’язки діють лише там, де меню пропонують групу: не тоді, коли задано readonly, коли параметр відображення Table Groups приховує групи або коли відкрито редактор клітинки чи нотатки або поле назви групи таблиць. Як і інші прив’язки полотна, вони діють лише на вкладці ERD і не діють, поки відкрито швидкий пошук, вікно властивостей таблиці, перегляд відмінностей, подорож у часі, попередній перегляд автоматичного розміщення, Export image чи Map Columns. Там, де вони нічого не роблять, типова дія натискання все одно скасовується, якщо тільки groupSelectedTables не поступається текстовому курсору. Для addTableGroup також зупиняється поширення, як і для focusView та zenMode, тож слухач keydown на етапі спливання на сторінці ніколи не отримує цього натискання.

Починаючи з версії 3.10.0, findReplace ($mod+KeyF) відкриває пошук і заміну. Починаючи з версії 4.1.0, ця прив’язка показує або ховає оглядач, у якому розміщено пошук і заміну, а на вкладці сполучень клавіш вона має назву Toggle Explorer.
Поки кнопка Explorer на панелі інструментів показується натиснутою (оглядач відкритий на вкладці ERD і не прихований режимом дзен), прив’язка закриває оглядач, якщо тільки не відкрито швидкий пошук, вікно властивостей таблиці, конструктор теми, панель вибору мови інтерфейсу, діалогове вікно Export image чи Map Columns. Інакше вона закриває те з них, що відкрито, переводить на вкладку ERD з будь-якої іншої вкладки й відкриває оглядач із текстовим курсором у полі Find і виділеним запитом. Редактор, надто вузький, щоб показати оглядач поруч із полотном, тримає його відкритим, але прихованим, і показує сповіщення Widen the window to show the Explorer. До версії 4.1.0 вона відкривала плаваючу панель пошуку й заміни або повертала клавіатуру її полю й ніколи її не закривала.
Вона не поступається текстовому курсору: поки редактор у фокусі, натискання перехоплюється на кожній вкладці — з полотна чи з поля введення всередині редактора. Типова дія натискання скасовується, тож браузер не відкриває панель пошуку, а поширення зупиняється, тож жоден слухач keydown на етапі спливання на сторінці його не отримує. Коли відкрито редактор клітинки чи нотатки або, починаючи з версії 4.0.0, поле назви групи таблиць, типова дія все одно скасовується й поширення зупиняється, але прив’язка нічого не робить.
Поки відкрито перегляд відмінностей, подорож у часі чи попередній перегляд автоматичного розміщення, на будь-якій вкладці, або поки IME ще складає символ, типова дія не скасовується й поширення не зупиняється, тож натискання отримує власний пошук браузера чи хоста. В оглядачі для натискання під час складання символу поширення зупиняється, хоча типова дія не скасовується. Будь-яке сполучення, яке ви призначите прив’язці findReplace, поводиться так само.

Прив’язка focusView діє лише на вкладці ERD. Якщо виділено хоча б одну таблицю, вона відкриває вкладку візуалізації в режимі Flow, обмеженому цими таблицями й усіма таблицями на відстані одного зв’язку; виділена нотатка чи група таблиць не враховується, а якщо не виділено жодної таблиці, прив’язка нічого не робить. Див. фокусування на таблицях.

Прив’язка stop (Escape) на вкладці ERD завершує роботу відкритого редактора клітинки чи нотатки або малювання зв’язку й залишає виділення без змін. Починаючи з версії 4.0.0, вона також закриває поле назви групи таблиць, не записуючи назви, і завершує малювання New Table Group. Редактор викликає preventDefault() для цього натискання.
Якщо нічого з цього не відкрито, Escape знімає виділення й фокус із клітинки, а типова дія не скасовується. Отже, щоб вийти з редагування та зняти виділення, потрібно два натискання.
Крім оглядача, форматів Import на вітальному екрані, а також панелей вибору й діалогових вікон, описаних нижче, редактор ніколи не зупиняє поширення Escape, тож сторінка, яка сама слухає цю клавішу, наприклад, щоб закрити власне діалогове вікно, отримує обидва натискання й може пропустити те, у якого defaultPrevented має значення true.
Поки відкрито швидкий пошук, вікно властивостей таблиці, перегляд відмінностей, попередній перегляд автоматичного розміщення чи подорож у часі, Escape натомість закриває відкрите й залишає виділення без змін. Типова дія цього натискання теж не скасовується.
Починаючи з версії 4.0.0, відкрите діалогове вікно Export image чи Map Columns також перехоплює Escape: воно закривається й залишає виділення без змін. Кожне з них під час відкриття забирає клавіатуру, а для цього натискання Escape і типова дія скасовується, і поширення зупиняється.
Починаючи з версії 4.1.0, натискання Escape, коли фокус усередині оглядача — у його дереві, полях чи кнопках, — повертає клавіатуру полотну, залишаючи оглядач відкритим, а виділення без змін. Редактор викликає для нього і preventDefault(), і stopPropagation(), тож воно ніколи не доходить до слухача keydown на етапі спливання на сторінці.
Натискання Escape на полотні ніколи не закриває оглядач. До версії 4.1.0 натискання Escape у панелі пошуку й заміни закривало її, а на полотні — закривало її тим самим натисканням, яке знімало виділення.
Починаючи з версії 4.0.0, панель вибору мови інтерфейсу й панель вибору кольору закриваються клавішею Escape: усередині них її типова дія скасовується й поширення зупиняється, а на полотні вона закриває їх тим самим натисканням, яке знімає виділення, без скасування типової дії та без зупинки поширення.
Натискання Escape, поки IME ще складає символ, належить складанню. Воно залишає відкритий редактор без змін, і його типова дія не скасовується, тож сторінка може пропускати й натискання, у якого isComposing має значення true або keyCode дорівнює 229. В оглядачі для такого натискання, як і для будь-якої клавіші, натиснутої там під час складання символу, також зупиняється поширення, а клавіатура залишається в полі.
До версії 3.9.2 одне натискання Escape і завершувало редагування чи малювання, і знімало виділення, а редактор ніколи не скасовував його типової дії.

createKeyBindingMap

Починаючи з версії 3.9.2, пакет експортує createKeyBindingMap(), а разом із ним типи KeyBindingMap, KeyBindingName і ShortcutOption.
Функція повертає типові прив’язки клавіш — усі 28 назв, зокрема фіксовані, — щоразу як нову мапу, тож зміна поверненої мапи більше нічого не змінює.
Саме з цієї мапи починає кожен редактор, і виклик setKeyBindingMap у ній не відображається.
Лише createKeyBindingMap є експортом часу виконання; інші три — це типи.

type KeyBindingName =
  | 'edit'
  | 'stop'
  | 'search'
  | 'findReplace'
  | 'undo'
  | 'redo'
  | 'addTable'
  | 'addColumn'
  | 'addMemo'
  | 'addTableGroup'
  | 'groupSelectedTables'
  | 'removeTable'
  | 'removeColumn'
  | 'removeSelection'
  | 'primaryKey'
  | 'selectAllTable'
  | 'selectAllColumn'
  | 'relationshipZeroOne'
  | 'relationshipZeroN'
  | 'relationshipOneOnly'
  | 'relationshipOneN'
  | 'tableProperties'
  | 'focusView'
  | 'zoomIn'
  | 'zoomOut'
  | 'zoomReset'
  | 'handTool'
  | 'zenMode';

type KeyBindingMap = Record<KeyBindingName, ShortcutOption[]>;

declare function createKeyBindingMap(): KeyBindingMap;

// example
import { createKeyBindingMap } from '@dineug/erd-editor';

const shortcuts = Object.values(createKeyBindingMap())
  .flat()
  .map(({ shortcut }) => shortcut); // 'Enter', 'Escape', '$mod+KeyK', ...

Кожне значення shortcut — це сполучення в синтаксисі tinykeys, що називає клавішу за KeyboardEvent.code, де $mod — це ⌘ у macOS і Control на інших платформах.
Починаючи з версії 4.0.0, редактор розбирає ці сполучення сам, а не через tinykeys, у тому самому синтаксисі. Клавіша збігається за своїм code або за key у будь-якому регістрі, а натискання збігається, лише якщо утримуються саме ті клавіші-модифікатори, що їх називає сполучення. AltGraph вважається Control і Alt у Windows та Alt у macOS. Натискання, розділені пробілом, утворюють послідовність, яка починається спочатку, якщо протягом секунди не надійшло жодної події keydown.
Починаючи з версії 4.1.0, одна з типових прив’язок є послідовністю: groupSelectedTables — це KeyT KeyG, T, потім G. Послідовність спрацьовує на натисканні, яке її завершує, і лише до цього натискання застосовуються її preventDefault і stopPropagation, тож із типовими прив’язками T доходить до сторінки, а типова дія скасовується лише для G. Меню, швидкий пошук і вкладка сполучень клавіш показують послідовність як одну клавішу на кожне натискання.
Фіксовані назви прив’язано до Enter (edit), Escape (stop), $mod+KeyZ (undo), $mod+Shift+KeyZ (redo), $mod+Equal (zoomIn), $mod+Minus (zoomOut) і $mod+Digit0 (zoomReset). edit і stop не мають прапорців; інші п’ять мають preventDefault і stopPropagation. Решта — це типові прив’язки, наведені вище, серед них search і findReplace.

Редактор слухає ці сполучення на власному елементі, тож хост, який перехоплює клавіші раніше за редактор — глобальними гарячими клавішами чи слухачем keydown на етапі перехоплення, — має пропускати їх, поки редактор у фокусі.
Складайте список клавіш для пропускання з createKeyBindingMap(), замінивши типові прив’язки тими, які ви передали в setKeyBindingMap.
Починаючи з версії 3.10.0, цей список містить $mod+KeyF — власне сполучення пошуку браузера. Хост, який хоче залишити на цьому сполученні власний пошук, передає setKeyBindingMap({ findReplace: [] }).
Починаючи з версії 4.0.0, він також містить Delete і Backspace без модифікаторів. Хост, який хоче залишити ці клавіші собі, передає setKeyBindingMap({ removeSelection: [] }).
Починаючи з версії 4.1.0, він також містить Alt+KeyG і послідовність KeyT KeyG, яка надходить одним рядком: розділіть її за пробілом і пропускайте кожне натискання, зокрема T і G без модифікаторів, бо послідовність, у якій бракує натискання, ніколи не завершиться. Хост, який хоче залишити ці клавіші собі, передає setKeyBindingMap({ addTableGroup: [] }) або setKeyBindingMap({ groupSelectedTables: [] }).

Поки фокус усередині оглядача — у його дереві, полях Find і Replace чи кнопках, — findReplace, search, undo, redo, zoomIn, zoomOut і zoomReset проходять до редактора, тож findReplace діє там так само, як на полотні. Кожна інша прив’язка, як її зараз налаштовано, зупиняється в оглядачі, послідовність — на останньому натисканні (G без модифікаторів за типових прив’язок), і так само зупиняються клавіші зі стрілками, Tab, Enter, Space, Home, End і будь-яка клавіша, натиснута, поки IME ще складає символ. Крім Escape, яка повертає клавіатуру полотну, для них зупиняється поширення без скасування типової дії, тож вони діють як звичайні клавіші в полях, кнопках і дереві оглядача та не доходять ні до полотна, ні до слухача keydown на етапі спливання на сторінці: Alt + N там не додає таблиці, а Delete нічого не видаляє. Для клавіш, які переміщують між рядками дерева, згортають рядок або переходять до нього, а також для Enter у полі Find чи Replace, що переходить між збігами або виконує заміну, типова дія також скасовується.
Будь-яка інша клавіша, як-от сполучення збереження чи палітри команд хоста, як зазвичай, проходить далі до сторінки. Див. клавіші в оглядачі. До версії 4.1.0 плаваюча панель пошуку й заміни так само затримувала клавіші, крім Home, End, останнього натискання послідовності та Space, коли handTool було прив’язано до іншої клавіші.
Починаючи з версії 4.0.0, панель вибору мови інтерфейсу так само затримує клавіші: ті самі сім прив’язок проходять далі, а для кожної іншої прив’язки (починаючи з версії 4.1.0, для послідовності — на останньому натисканні), клавіш зі стрілками й Tab там зупиняється поширення без скасування типової дії, як і для будь-якої клавіші, натиснутої, поки IME ще складає символ. ↑, ↓, Home, End, Enter і Space на одному з її рядків переміщують фокус між рядками або вибирають рядок, і їхня типова дія також скасовується.

$mod

Змінює клавішу Control залежно від середовища.

• Mac: $mod = Meta (⌘)
• Windows/Linux: $mod = Control

Таблиця сполучень клавіш

Використовує властивості key, code події клавіатури.
Використовуйте code для абсолютних позицій клавіш, а key — для введених значень.

Windows	macOS	key	code
Немає	Command / ⌘	Meta	MetaLeft / MetaRight
Alt	Option / ⌥	Alt	AltLeft / AltRight
Control	Control / ^	Control	ControlLeft / ControlRight
Shift	Shift	Shift	ShiftLeft / ShiftRight
Space	Space	Немає	Space
Enter	Return	Enter	Enter
Esc	Esc	Escape	Escape
Backspace	Delete / ⌫	Backspace	Backspace
Delete	fn + Delete	Delete	Delete
1, 2 тощо	1, 2 тощо	1, 2 тощо	Digit1, Digit2 тощо
a, b тощо	a, b тощо	a, b тощо	KeyA, KeyB тощо
-	-	-	Minus
=	=	=	Equal
+	+	+	Equal

Тема

setPresetTheme

Задає готову тему.
Типові значення: appearance: 'dark', grayColor: 'slate' і accentColor: 'indigo'.
Кожне поле застосовується окремо, тож частковий виклик залишає два інші без змін. Значення, якого немає серед наведених нижче назв, ігнорується, і виклик ніколи не викидає винятку.
Починаючи з версії 4.0.0, поле appearance також приймає 'system' — варіант System конструктора теми. Він показує світлий або темний вигляд, про який повідомляє операційна система, або той, що задано через setSystemAppearance, і перемикається, коли він змінюється.

type ThemeOptions = {
  appearance: 'dark' | 'light' | 'system';
  grayColor: 'gray' | 'mauve' | 'slate' | 'sage' | 'olive' | 'sand';
  accentColor:
    | 'gray'
    | 'gold'
    | 'bronze'
    | 'brown'
    | 'yellow'
    | 'amber'
    | 'orange'
    | 'tomato'
    | 'red'
    | 'ruby'
    | 'crimson'
    | 'pink'
    | 'plum'
    | 'purple'
    | 'violet'
    | 'iris'
    | 'indigo'
    | 'blue'
    | 'cyan'
    | 'teal'
    | 'jade'
    | 'green'
    | 'grass'
    | 'lime'
    | 'mint'
    | 'sky';
};

// example
editor.setPresetTheme({ appearance: 'light' });

setSystemAppearance

Починаючи з версії 4.0.0, задає, світлим чи темним показується вигляд 'system', — для хоста з власним світлим і темним оформленням, як-от тема IDE. Поки його задано, зміни в операційній системі ігноруються.
null або будь-яке значення, крім 'dark' чи 'light', повертає до відстеження операційної системи.
Поки вигляд має значення 'light' або 'dark', метод нічого не змінює на екрані, але значення зберігається й застосовується, щойно вигляд стане 'system'. Інакше воно застосовується одразу. Метод нічого не генерує, а changePresetTheme і далі повідомляє 'system'.
Хости для VS Code, JetBrains і Obsidian викликають його зі своїм світлим чи темним оформленням і знову — щоразу, коли воно змінюється.

editor.setPresetTheme({ appearance: 'system' });
editor.setSystemAppearance('light'); // null follows the OS again

setTheme

Дає змогу налаштувати тему.
Кожен виклик замінює весь користувацький шар, тож щоб змінити один токен поверх наявного перевизначення, знову передайте повний об’єкт, а щоб повернутися до готової теми, передайте {}.
Зберігаються лише наведені нижче назви токенів із рядковими значеннями; усе інше відкидається без помилки.
Цей шар лежить поверх готової теми, тож пізніший виклик setPresetTheme замінює готову тему під ним, а ваші перевизначення лишаються.

JavaScript

type Theme = {
  grayColor1: string;
  grayColor2: string;
  grayColor3: string;
  grayColor4: string;
  grayColor5: string;
  grayColor6: string;
  grayColor7: string;
  grayColor8: string;
  grayColor9: string;
  grayColor10: string;
  grayColor11: string;
  grayColor12: string;

  accentColor1: string;
  accentColor2: string;
  accentColor3: string;
  accentColor4: string;
  accentColor5: string;
  accentColor6: string;
  accentColor7: string;
  accentColor8: string;
  accentColor9: string;
  accentColor10: string;
  accentColor11: string;
  accentColor12: string;

  canvasBackground: string;
  canvasBoundaryBackground: string;

  tableBackground: string;
  tableHeaderBackground: string;
  tableSelect: string;
  tableBorder: string;
  tableShadow: string;

  tableGroupHeaderBackground: string;
  tableGroupBackground: string;
  tableGroupBorder: string;

  memoBackground: string;
  memoSelect: string;
  memoBorder: string;
  memoShadow: string;

  columnSelect: string;
  columnSelectHover: string;
  columnHover: string;

  relationshipHover: string;

  visualizationLink: string;
  visualizationColumn: string;
  visualizationRelationship: string;

  toolbarBackground: string;

  contextMenuBackground: string;
  contextMenuSelect: string;
  contextMenuHover: string;
  contextMenuBorder: string;

  minimapBorder: string;
  minimapShadow: string;
  minimapViewportBorder: string;
  minimapViewportBorderHover: string;

  toastBackground: string;
  toastBorder: string;
  toastSuccess: string;
  toastError: string;

  findReplaceError: string;

  mapColumnsError: string;

  schemaSqlWarningBackground: string;
  schemaSqlWarningForeground: string;

  dragSelectBackground: string;
  dragSelectBorder: string;

  scrollbarTrack: string;
  scrollbarThumb: string;
  scrollbarThumbHover: string;

  foreground: string;
  active: string;
  placeholder: string;

  focus: string;
  inputActive: string;

  keyPK: string;
  keyFK: string;
  keyPFK: string;

  treeBackground: string;
  treeRowHover: string;
  treeRowCurrent: string;
  treeMuted: string;
  treeMatch: string;

  explorerBackground: string;
  explorerBorder: string;

  diffInsertForeground: string;
  diffDeleteForeground: string;
  diffModifyForeground: string;
  diffRenameForeground: string;
};

// example
editor.setTheme({
  canvasBackground: '#1b1b1f',
  tableBackground: '#242429',
  keyPK: '#ffc53d',
});

tableShadow і memoShadow — це колір тіні, яку таблиці й нотатки відкидають на полотно ERD. Темна готова тема задає для них transparent, тож тінь не відкидається, як і в разі передавання none чи порожнього рядка в setTheme; світла готова тема використовує rgba(0, 0, 0, 0.18).

Починаючи з версії 4.0.0, є ще дев’ять токенів:

• tableGroupHeaderBackground, tableGroupBackground і tableGroupBorder задають колір смуги заголовка, тіла й контуру групи таблиць, яка не має власного кольору.
• toastSuccess і toastError задають колір позначки сповіщення, яке повідомляє, чим щось завершилося.
• findReplaceError і mapColumnsError задають колір помилок, які показують пошук і заміна та вікно зіставлення стовпців. Раніше пошук і заміна використовували diffDeleteForeground, тож його перевизначення більше не змінює їхнього кольору.
• schemaSqlWarningBackground і schemaSqlWarningForeground задають колір попереджень у параметрах вкладки схеми SQL.

Починаючи з версії 4.1.0, є ще дев’ять токенів:

• treeBackground, treeRowHover, treeRowCurrent, treeMuted і treeMatch задають кольори дерева, спільного для оглядача й перегляду відмінностей: його фону, яким також заливаються поля Find і Replace оглядача; рядка під вказівником, рядка клавіатурного фокусу, поки дерево у фокусі, і кнопки під вказівником у заголовку й пошуку оглядача; рядка поточного збігу пошуку; приглушеного тексту, як-от лічильників, типів даних і стрілок згортання; і позначки під текстом, знайденим пошуком.
• explorerBackground і explorerBorder задають колір панелі оглядача та її ліній: краю поруч із полотном, лінії під пошуком і рамок полів та кнопок, які розгортає Search In. explorerBorder також малює край дерева перегляду відмінностей, лінію під його полем Filter by name і рамку цього поля. Значки ключів в оглядачі беруть кольори keyPK, keyFK і keyPFK.
• diffModifyForeground і diffRenameForeground задають колір того, що перегляд відмінностей позначає як змінене й перейменоване, у його дереві та на обох документах. diffModifyForeground також обводить таблицю, нотатку чи групу таблиць, яку перемістили, змінили її розмір, колір або групу, незалежно від інших змін у ній, і малює лінію зв’язку зміненого зовнішнього ключа.

diffInsertForeground і diffDeleteForeground тепер задають колір того, що перегляд відмінностей позначає як додане й видалене, у його дереві та в тому документі, де воно є, — однаково в тексті, контурах і лініях зв’язку. diffInsertBackground, diffDeleteBackground, diffCrossBackground і diffCrossForeground вилучено у версії 4.1.0, оскільки перегляд відмінностей більше не заливає клітинки. setTheme відкидає їх, як і будь-яку іншу назву, якої немає в Theme, а їхні хуки --erd-editor-diff-insert-background, --erd-editor-diff-delete-background, --erd-editor-diff-cross-background і --erd-editor-diff-cross-foreground більше не зчитуються.

Змінні CSS

Кожен токен у Theme має відповідний CSS-хук із назвою --erd-editor- плюс ключ у kebab-case: grayColor10 — це --erd-editor-gray-color-10, keyPK — --erd-editor-key-pk, а keyPFK — --erd-editor-key-pfk.
Хуки успадковуються в редактор, тож задавайте їх там, де вони мають діяти. На :root вони оформлюють кожен редактор на сторінці; на самому елементі — лише цей редактор.

erd-editor {
  --erd-editor-canvas-background: #1b1b1f;
}

Починаючи з версії 3.4.0, токени з помилкою в назві dargSelect пишуться як dragSelect, а їхні хуки змінилися з --erd-editor-darg-select-background і --erd-editor-darg-select-border на --erd-editor-drag-select-background і --erd-editor-drag-select-border. Таблиця стилів, яка й далі використовує старі назви, ігнорується.

Типові значення теми

:root {
  --erd-editor-gray-color-1: #111113;
  --erd-editor-gray-color-2: #18191b;
  --erd-editor-gray-color-3: #212225;
  --erd-editor-gray-color-4: #272a2d;
  --erd-editor-gray-color-5: #2e3135;
  --erd-editor-gray-color-6: #363a3f;
  --erd-editor-gray-color-7: #43484e;
  --erd-editor-gray-color-8: #5a6169;
  --erd-editor-gray-color-9: #696e77;
  --erd-editor-gray-color-10: #777b84;
  --erd-editor-gray-color-11: #b0b4ba;
  --erd-editor-gray-color-12: #edeef0;
  --erd-editor-accent-color-1: #11131f;
  --erd-editor-accent-color-2: #141726;
  --erd-editor-accent-color-3: #182449;
  --erd-editor-accent-color-4: #1d2e62;
  --erd-editor-accent-color-5: #253974;
  --erd-editor-accent-color-6: #304384;
  --erd-editor-accent-color-7: #3a4f97;
  --erd-editor-accent-color-8: #435db1;
  --erd-editor-accent-color-9: #3e63dd;
  --erd-editor-accent-color-10: #5472e4;
  --erd-editor-accent-color-11: #9eb1ff;
  --erd-editor-accent-color-12: #d6e1ff;
  --erd-editor-canvas-background: #212225;
  --erd-editor-canvas-boundary-background: #111113;
  --erd-editor-table-background: #18191b;
  --erd-editor-table-header-background: #2e3135;
  --erd-editor-table-select: #435db1;
  --erd-editor-table-border: #363a3f;
  --erd-editor-table-shadow: transparent;
  --erd-editor-table-group-header-background: #43484e;
  --erd-editor-table-group-background: #d3edf81d;
  --erd-editor-table-group-border: #43484e;
  --erd-editor-memo-background: #18191b;
  --erd-editor-memo-select: #435db1;
  --erd-editor-memo-border: #363a3f;
  --erd-editor-memo-shadow: transparent;
  --erd-editor-column-select: #182449;
  --erd-editor-column-select-hover: #1d2e62;
  --erd-editor-column-hover: #272a2d;
  --erd-editor-relationship-hover: #435db1;
  --erd-editor-visualization-link: #43484e;
  --erd-editor-visualization-column: #5a6169;
  --erd-editor-visualization-relationship: #5a6169;
  --erd-editor-toolbar-background: #111113;
  --erd-editor-context-menu-background: #18191b;
  --erd-editor-context-menu-select: #272a2d;
  --erd-editor-context-menu-hover: #3a4f97;
  --erd-editor-context-menu-border: #363a3f;
  --erd-editor-minimap-border: black;
  --erd-editor-minimap-shadow: black;
  --erd-editor-minimap-viewport-border: #3a4f97;
  --erd-editor-minimap-viewport-border-hover: #435db1;
  --erd-editor-toast-background: #18191b;
  --erd-editor-toast-border: #363a3f;
  --erd-editor-toast-success: #3dd68c;
  --erd-editor-toast-error: #ff9592;
  --erd-editor-find-replace-error: #ff9592;
  --erd-editor-map-columns-error: #ff9592;
  --erd-editor-schema-sql-warning-background: #500f1c;
  --erd-editor-schema-sql-warning-foreground: #ff9592;
  --erd-editor-drag-select-background: #253974;
  --erd-editor-drag-select-border: #435db1;
  --erd-editor-scrollbar-track: #ddeaf814;
  --erd-editor-scrollbar-thumb: #696e77;
  --erd-editor-scrollbar-thumb-hover: #777b84;
  --erd-editor-foreground: #b0b4ba;
  --erd-editor-active: #edeef0;
  --erd-editor-placeholder: #e5edfd7b;
  --erd-editor-focus: #435db1;
  --erd-editor-input-active: #5472e4;
  --erd-editor-key-pk: #ffc53d;
  --erd-editor-key-fk: #e54666;
  --erd-editor-key-pfk: #00a2c7;
  --erd-editor-tree-background: #111113;
  --erd-editor-tree-row-hover: #212225;
  --erd-editor-tree-row-current: #1d2e62;
  --erd-editor-tree-muted: #b0b4ba;
  --erd-editor-tree-match: #253974;
  --erd-editor-explorer-background: #111113;
  --erd-editor-explorer-border: #363a3f;
  --erd-editor-diff-insert-foreground: #3dd68c;
  --erd-editor-diff-delete-foreground: #ff9592;
  --erd-editor-diff-modify-foreground: #ffca16;
  --erd-editor-diff-rename-foreground: #70b8ff;
}

Мова інтерфейсу

Починаючи з версії 4.0.0, власний текст редактора — його меню, панелі, діалогові вікна, швидкий пошук, сповіщення й слова, які він малює на діаграмі, як-от unnamed, зокрема в експортованих зображеннях, — доступний 25 мовами. Назви таблиць і стовпців, SQL, типи даних і згенерований код ніколи не перекладаються. Див. мова й тема.
Доки не викликано setLocale або не вибрано мову, редактор показує англійську або, поки ввімкнено enableLocalePicker, дотримується 'system'.
Редактор задає lang і dir на власному корені всередині закритого тіньового кореня, а ніколи не на хост-елементі чи сторінці, тож сторінка з письмом справа наліво не віддзеркалює редактор, а мова з письмом справа наліво не віддзеркалює сторінку. Іврит, арабська й перська розміщують інтерфейс редактора справа наліво; сама діаграма ніколи не віддзеркалюється. Починаючи з версії 4.1.0, оглядач за будь-якої мови лишається ліворуч від полотна, а його рядки в цих трьох мовах читаються справа наліво.
Пакет експортує типи LocaleCode (один із наведених нижче кодів) і LocaleOption.

type LocaleOption = LocaleCode | 'system';

Код	Відображається як	Мова
id-ID	Bahasa Indonesia	Індонезійська
de-DE	Deutsch	Німецька
en	English	Англійська
es-ES	Español	Іспанська
eu-ES	Euskara	Баскська
fr-FR	Français	Французька
it-IT	Italiano	Італійська
nl-NL	Nederlands	Нідерландська
pl-PL	Polski	Польська
pt-PT	Português	Португальська
pt-BR	Português Brasileiro	Бразильська португальська
ro-RO	Română	Румунська
sk-SK	Slovenčina	Словацька
sl-SI	Slovenščina	Словенська
sv-SE	Svenska	Шведська
tr-TR	Türkçe	Турецька
ru-RU	Русский	Російська
uk-UA	Українська	Українська
he-IL	עברית	Іврит
ar-SA	العربية	Арабська
fa-IR	فارسی	Перська
ja-JP	日本語	Японська
zh-CN	简体中文	Спрощена китайська
zh-TW	繁體中文	Традиційна китайська
ko-KR	한국어	Корейська

setLocale

Задає мову інтерфейсу: 'system' або один із наведених вище кодів. Усе інше, як-от просто 'ko', невідомий код чи значення, що не є рядком, ігнорується без помилки.
Мова застосовується ще до повернення з методу, тож мова, задана до додавання елемента на сторінку, діє вже в його першому кадрі.
Метод нічого не генерує — ні changeLocale, ні change — і не зачіпає ні value, ні історії змін, ні спільного сховища.
Вибір зберігається незалежно від того, увімкнено enableLocalePicker чи вимкнено, а setLocale('system') відстежує систему й тоді, коли панель вибору вимкнено.
Редактор нічого не зберігає. Щоб зберегти вибір користувача, слухайте changeLocale і передавайте його назад під час наступного завантаження.

editor.enableLocalePicker = true;
editor.setLocale(localStorage.getItem('locale') ?? 'system');
editor.addEventListener('changeLocale', event => {
  localStorage.setItem('locale', event.detail.locale);
});

setSystemLocale

Задає у вигляді тегу BCP 47 мову, яку означає 'system', — для хоста з власною мовою інтерфейсу. Хости для VS Code, JetBrains і Obsidian викликають його зі своєю мовою інтерфейсу.
Пробіли на краях тегу обрізаються. null, порожній рядок або значення, що не є рядком, повертає до navigator.languages браузера, за змінами якого стежить редактор.
Метод має значення лише тоді, коли чинний варіант — 'system', і застосовується одразу. Рядок System на панелі вибору показує мову, якій він відповідає.
Тег або кожна з мов браузера по черзі зводиться до першої мови, яка є в редакторі, за мовним субтегом, без урахування регістру й підкреслень: de-AT дає de-DE, а en-GB — en. Китайська визначається за писемністю: Hant дає zh-TW, а Hans — zh-CN, а без неї — за регіоном: TW, HK і MO дають zh-TW, а будь-який інший — zh-CN. pt дає pt-BR, якщо не вказано регіон, відмінний від BR. Якщо нічого не збігається, редактор показує англійську.

editor.setLocale('system');
editor.setSystemLocale('pt-PT'); // null follows the browser again

setSchemaSQL

Завантажує файл схеми SQL.
За замовчуванням він замінює поточний документ, а не об’єднує файл із ним; див. mode нижче. Наявні налаштування зберігаються, зокрема кожне блокування з його заблокованим значенням, крім положення області перегляду й рівня масштабу, а таблиці розміщуються після прочитання файлу — рядами, якщо placement нижче не вимагає іншого. Якщо Viewport заблоковано, value потім записує область перегляду, з якої починається імпорт: початок координат 0, 0 з рівнем масштабу 1. Тому в документі, імпортованому в елемент, який ще не отримував значення, ввімкнено всі блокування, як і в новому документі.
Він записується в історію змін, що дає змогу виконувати Undo, Redo, і генерує подію change. Порожній рядок ігнорується, а поки задано readonly, виклик нічого не робить.
setSchemaGraphQL, setSchemaDBML і setSchemaAML поводяться так само, а їхні парсери ніколи не завершуються помилкою: текст, який вони не можуть прочитати, завантажує порожній документ замість того, щоб викликати помилку.
Починаючи з версії 4.0.0, усі чотири приймають необов’язковий другий аргумент { placement, mode }:

• placement: 'grid', типове значення, одразу розміщує таблиці рядами, як і раніше, і виклик нічого не повертає.
• placement: 'auto' спершу розміщує таблиці за їхніми зв’язками, як і Import у редакторі, і повертає Promise, який виконується, щойно імпорт завершиться як один крок відміни. Менше ніж дві таблиці, відсутність зв’язків, невдале розміщення, сторінка без SharedWorker або Cancel у сповіщенні Placing tables натомість розміщують їх рядами. Завантаження тим часом — інший імпорт із заміною, присвоєння value, setInitialValue(), clear(), завантаження співавтора або відміна чи повторення завантаження або clear() — витісняє його, і Promise виконується, нічого не завантаживши. Імпорти, розміщені в такий спосіб, завершуються в тому порядку, в якому почалися.
• mode: 'replace', типове значення, замінює документ. mode: 'append' додає файл під діаграмою, як і імпорт із додаванням, залишаючи без змін усі наявні таблиці та всі налаштування, крім вкладки й положення області перегляду. Якщо відкрито іншу вкладку, спершу відкривається вкладка ERD. Нові таблиці, а також групи таблиць, які приносить DBML-файл, поки групи таблиць показано, виділяються, а область перегляду прокручується до них, хіба що їх уже добре видно, за правилом, якому, починаючи з версії 4.1.0, підпорядковується кожен перехід, — див. куди веде перехід. Одна відміна прибирає все додане. Текст, який не вдається прочитати, нічого не додає й залишає документ без змін.

Поки задано readonly, заміна ігнорується, додавання нічого не додає, а Promise виклику з placement: 'auto' виконується одразу.
Починаючи з версії 3.10.0, setSchemaSQL читає файл відповідно до поточної бази даних документа: якщо вибрано Databricks, рядки в одинарних лапках підпорядковуються правилам екранування зворотною скісною рискою, як у Spark. Див. коментарі.
Починаючи з версії 3.10.0, setSchemaSQL читає UNIQUE для двох або більше стовпців як один унікальний індекс, а не як прапорець унікальності на кожному стовпці. Див. унікальні ключі та індекси.
Починаючи з версії 3.10.0, імпорт SQL, DBML і AML зберігає дії ON DELETE і ON UPDATE зовнішніх ключів, які він читає.
Починаючи з версії 4.0.0, setSchemaSQL зберігає весь вираз DEFAULT стовпця, читає ADD DEFAULT … FOR і коментарі MS_Description із SQL Server, перетворює стовпці serial та identity в PostgreSQL на автоінкремент, зберігає UNSIGNED і ZEROFILL у типі даних і читає первинний ключ, який ALTER TABLE … ADD PRIMARY KEY позначає як CLUSTERED, NONCLUSTERED чи USING BTREE. Див. схема SQL.
Про синтаксис, який приймає кожен парсер, див. імпорт і експорт файлів.

type SetSchema = {
  (
    value: string,
    options: { placement: 'auto'; mode?: 'replace' | 'append' }
  ): Promise<void>;
  (
    value: string,
    options?: { placement?: 'grid'; mode?: 'replace' | 'append' }
  ): void;
};

// example
editor.setSchemaSQL('Schema SQL...');
// or
await editor.setSchemaSQL('Schema SQL...', { placement: 'auto' });
// or
editor.setSchemaSQL('Schema SQL...', { mode: 'append' });

setSchemaGraphQL

Завантажує документ GraphQL SDL.
Визначення об’єктних типів стають таблицями, а поле, тип якого — інша таблиця, стає зв’язком.

editor.setSchemaGraphQL('GraphQL SDL...');

setSchemaDBML

Завантажує DBML-файл — формат, який використовують dbdiagram.io і dbdocs.
Починаючи з версії 4.0.0, кожен TableGroup стає групою таблиць, а headercolor таблиці стає її кольором. Див. DBML.

editor.setSchemaDBML('DBML...');

setSchemaAML

Завантажує файл AML (Azimutt Markup Language). Приймається як поточний варіант запису, так і застарілий варіант v1.
Починаючи з версії 4.0.0, колір сутності — одна з назв кольорів Azimutt або шістнадцяткове значення в лапках — стає кольором її таблиці. Див. AML.

editor.setSchemaAML('AML...');

setSchemaJSON

Починаючи з версії 4.0.0, завантажує документ .erd.json, як-от текст, який повертає value.
У типовому режимі mode: 'replace' він завантажує документ так само, як присвоєння value: записується в історію змін, генерує подію change і так само бере блокування документа. На відміну від value, порожній рядок або значення, що не є рядком, ігнорується, а не починає новий документ. Текст, що не є JSON, очищає документ, як і у випадку з value.
mode: 'append' додає таблиці, зв’язки, індекси, нотатки й групи таблиць документа під діаграмою з новими ідентифікаторами, зберігаючи їхнє взаємне розташування й пропускаючи налаштування документа, як і імпорт із додаванням для файлу json. Текст, який не вдається прочитати, або документ без жодної таблиці й нотатки нічого не додає. Інакше він розміщується так само, як під час додавання через setSchemaSQL: його нові нотатки та групи таблиць виділяються разом із таблицями — кожен вид, поки його показано.
Метод повертає керування, щойно документ розміщено, і ігнорується, поки задано readonly.

editor.setSchemaJSON('json...');
// or
editor.setSchemaJSON('json...', { mode: 'append' });

getSchemaSQL

Експортує поточний стан редактора як схему SQL.
Якщо databaseVendor не вказано, метод працює з поточною вибраною СУБД. Назва, якої немає в списку нижче, обробляється так само, без помилки.
Назви беруться в лапки того типу, який показує редактор. Поки Bracket Type заблоковано, він може відрізнятися від того, що зберігає value, — саме тим типом лапок користується erd_read агента для програмування.
Починаючи з версії 4.0.0, необов’язковий аргумент options вибирає оператори й заголовок, як і параметри вкладки схеми SQL. SchemaSQLOptions експортується як тип.

• statements: 'create', типове значення; 'ifNotExists', яке записує IF NOT EXISTS для MySQL, MariaDB, PostgreSQL, SQLite і Databricks, а для інших СУБД повертається до 'create'; або 'recreate', яке видаляє таблиці перед створенням, а для Snowflake натомість записує CREATE OR REPLACE TABLE.
• header: 'none', типове значення; 'use', яке перемикає на базу даних або схему документа; або 'createAndUse', яке спершу створює її, якщо вона не існує, а потім перемикає на неї. Для бази даних, яка не підтримує запитаного варіанта, використовується запасний варіант, як і на вкладці: Oracle записує 'use' замість 'createAndUse', PostgreSQL не записує заголовка для 'use', а SQLite не записує жодного. Заголовок записується лише тоді, коли назва бази даних документа є простим ідентифікатором — літери ASCII, цифри та _, без цифри на початку.

Пропущений параметр або параметр із невідомим значенням зчитується як типовий, тож виклик без параметрів записує прості оператори CREATE без заголовка, як і раніше.
Починаючи з версії 4.0.0, вивід завжди містить скрипти документа Before tables і After tables у такому порядку: заголовок, скрипт перед таблицями, оператори DROP, таблиці, скрипт після таблиць. Власні варіанти Statements, Header і Tables на вкладці схеми SQL ніколи не впливають на цей виклик, який завжди записує весь документ.
Починаючи з версії 3.10.0, кожен зовнішній ключ містить конструкції ON DELETE і ON UPDATE зв’язку. Конструкція записується лише тоді, коли її дію задано й СУБД її приймає, тож дія, яку ця СУБД не підтримує, пропускається, і застосовується типова. Починаючи з версії 4.0.0, Snowflake приймає лише NO ACTION. Про те, що записує кожна база даних, див. ON DELETE і ON UPDATE.
Починаючи з версії 3.10.0, одинарна лапка в коментарі таблиці чи стовпця екранується, тож коментар на кшталт it's більше не ламає оператор. Кожна СУБД, яка записує коментарі як рядкові літерали, подвоює її, крім Databricks, яка ставить зворотну скісну риску перед кожною лапкою й кожною зворотною скісною рискою. SQLite і далі записує коментарі як рядки --.
Починаючи з версії 4.0.0, кілька баз даних також по-іншому записують назви ключів, типові значення й автоінкремент. Див. що записує DDL.

type DatabaseVendor =
  | 'Databricks'
  | 'MariaDB'
  | 'MSSQL'
  | 'MySQL'
  | 'Oracle'
  | 'PostgreSQL'
  | 'Snowflake'
  | 'SQLite';

type SchemaSQLOptions = {
  statements?: 'create' | 'ifNotExists' | 'recreate';
  header?: 'none' | 'use' | 'createAndUse';
};

const schemaSQL = editor.getSchemaSQL();
// or
const postgresSQL = editor.getSchemaSQL('PostgreSQL');
// or
const mysqlSQL = editor.getSchemaSQL('MySQL', {
  statements: 'ifNotExists',
  header: 'createAndUse',
});

getSharedStore

Повертає сховище для спільного редагування в реальному часі.
config — це { getNickname?, mouseTracker?, focusTracker? }. Обидва трекери за замовчуванням мають значення true: mouseTracker транслює іншим курсор цього редактора, а focusTracker — його клітинку у фокусі, виділення й рамку виділення.
Див. спільне редагування.

const sharedStore = editor.getSharedStore({
  mouseTracker: false,
  focusTracker: false,
});

setDiffValue

Відкриває перегляд відмінностей, порівнюючи поточний відкритий документ із тим, який ви передаєте.
Метод нічого не повертає й не змінює документ, тож після закриття перегляду редактор залишається точно таким, як був.
Порожнє значення або будь-що, що не є рядком, порівнюється з порожнім документом.
Це те саме накладне вікно, що й перегляд відмінностей у контекстному меню полотна.
Починаючи з версії 4.1.0, він зіставляє вміст двох документів спершу за ідентифікатором і лише потім за тим, що містить кожен об’єкт, як-от назва таблиці чи текст нотатки, — див. що порівнюється. Тому порівняно з попередньою версією того самого документа, як-от ревізією його файлу в Git, перейменування показується як один перейменований об’єкт; порівняно з документом, ідентифікатори якого відрізняються, — як видалення й додавання. Перегляд показує перелік змін у дереві поруч із двома документами й позначає зміни кольором замість заливання клітинок.

editor.setDiffValue('prev json...');