Storage

Хранилища «ключ-значение» (KV) и база данных (DB), автосохранение состояния и компонент таблицы.

Интерфейс предлагает несколько способов хранить данные:

InterfaceRuntime.KV — простое асинхронное хранилище «ключ‑значение» для любых данных вашего интерфейса.
InterfaceRuntime.DB — прямой доступ к SQL‑базе для сложных случаев (только в настольном приложении).
Состояние интерфейса — автоматическое сохранение и восстановление введённых значений.
Engine.api.database — программное управление компонентом «таблица», размещённым на интерфейсе.

⚠️ Важное отличие контракта. KV и DB возвращают «чистый» Promise: он разрешается прямо значением и отклоняется при ошибке (обрабатывайте через try/catch). Это не тот объект { success, data }, что у остальных методов Engine.api.

Ключ‑значение (KV)

InterfaceRuntime.KV — самый простой способ что‑то запомнить между запусками: настройки, последний выбор пользователя, черновики. Значением может быть любая структура, которую можно представить в JSON.

Основные операции

// Записать
await InterfaceRuntime.KV.set('user.theme', 'dark');

// Прочитать (со значением по умолчанию)
const theme = await InterfaceRuntime.KV.get('user.theme', 'light');

// Проверить наличие
const exists = await InterfaceRuntime.KV.has('user.theme');

// Удалить
await InterfaceRuntime.KV.delete('user.theme');

Прочитать значение

InterfaceRuntime.KV.get(ключ, поУмолчанию?) — возвращает сохранённое значение. Если ключа нет — поУмолчанию (или undefined).

Сохранить значение

InterfaceRuntime.KV.set(ключ, значение) — сохраняет значение. Запись undefined равнозначна удалению ключа.

Проверить наличие ключа

InterfaceRuntime.KV.has(ключ) — проверяет, существует ли ключ. Возвращает boolean.

Удалить ключ

InterfaceRuntime.KV.delete(ключ) — удаляет ключ.

Список всех ключей

InterfaceRuntime.KV.keys() — возвращает массив всех ключей текущего пространства.

Все пары «ключ — значение»

InterfaceRuntime.KV.entries() — возвращает массив пар [ключ, значение].

Очистить пространство

InterfaceRuntime.KV.clear() — удаляет все ключи текущего пространства.

Прочитать несколько ключей сразу

InterfaceRuntime.KV.getMany(ключи) — читает несколько ключей за раз. Возвращает объект найденных пар.

const cfg = await InterfaceRuntime.KV.getMany(['host', 'port', 'token']);

Записать несколько пар сразу

InterfaceRuntime.KV.setMany(объект) — записывает несколько пар за раз. Ключи со значением undefined удаляются.

await InterfaceRuntime.KV.setMany({ host: 'localhost', port: 8080 });

Пространства имён

По умолчанию данные хранятся в пространстве app. Чтобы изолировать данные разных частей интерфейса, создайте отдельное пространство:

const orders = InterfaceRuntime.KV.namespace('orders');
await orders.set('last', 42);
const last = await orders.get('last');

Подписка на изменения

subscribe уведомляет об изменении ключа в текущем окне. Ключ '*' — подписка на любые изменения. Возвращает функцию отписки.

const off = InterfaceRuntime.KV.subscribe('user.theme', (value, key) => {
  console.log('Изменилось:', key, '→', value);
});

// Позже
off();

База данных (DB)

InterfaceRuntime.DB даёт прямой доступ к SQL для сложных сценариев хранения. Доступно только в настольном приложении; в браузере вызов завершится ошибкой — тогда используйте KV.

⚠️ Всегда используйте параметризованные запросы (значения через ?), никогда не склеивайте SQL со значениями вручную. Доступ к служебным таблицам хранилища заблокирован.

Открыть базу

InterfaceRuntime.DB.open(имя?) — открывает базу и возвращает объект для работы с ней. Без аргумента открывается база текущего интерфейса; с именем — отдельная база.

const db = await InterfaceRuntime.DB.open();          // база интерфейса
const notes = await InterfaceRuntime.DB.open('notes'); // отдельная база

Объект базы

exec(sql, параметры?) — выполняет запрос без результата (создание таблиц, вставка, изменение).
query(sql, параметры?) — выполняет запрос и возвращает строки.
transaction(функция) — выполняет несколько операций одной транзакцией.
path() — путь к файлу базы.
close() — закрывает базу.

const db = await InterfaceRuntime.DB.open();

await db.exec(
  'CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)'
);
await db.exec('INSERT INTO notes (body) VALUES (?)', ['Первая заметка']);

const rows = await db.query('SELECT * FROM notes WHERE id > ?', [0]);
console.log(rows);

await db.transaction(async (tx) => {
  await tx.exec('DELETE FROM notes WHERE id = ?', [1]);
  await tx.exec('INSERT INTO notes (body) VALUES (?)', ['Заметка в транзакции']);
});

Обработка ошибок — через try/catch:

try {
  const db = await InterfaceRuntime.DB.open();
  await db.exec('INSERT INTO notes (body) VALUES (?)', [text]);
} catch (e) {
  Engine.api.dialog.alert('Не удалось сохранить: ' + e.message, { type: 'error' });
}

Состояние интерфейса

Интерфейс сам сохраняет введённые значения, тему и язык, а при следующем открытии восстанавливает их. Обычно вмешательства не требуется, но при необходимости состоянием можно управлять через Engine.api.ui.

Сохранить состояние принудительно

Engine.api.ui.saveState() — принудительно сохраняет текущее состояние.

Восстановить сохранённое состояние

Engine.api.ui.restoreState() — восстанавливает ранее сохранённое состояние.

Удалить сохранённое состояние

Engine.api.ui.clearState() — удаляет сохранённое состояние.

Выгрузить состояние

Engine.api.ui.exportState() — возвращает текущее состояние, удобно для резервной копии.

const res = Engine.api.ui.exportState();
await InterfaceRuntime.KV.set('backup', res.data);

insertRow(идентификатор, данные) — добавляет строку. данные — объект «столбец → значение».
updateRow(идентификатор, условие, данные) — обновляет строки, подходящие под условие.
deleteRow(идентификатор, условие) — удаляет строки по условию.
getAllData(идентификатор) — возвращает все строки.
getSelectedRows(идентификатор) — возвращает строки, выделенные пользователем.
query(идентификатор, sql, параметры?) — произвольный запрос к таблице.

Engine.api.database.insertRow('accountsTable', {
  login: 'user1',
  status: 'active'
});

Engine.api.database.updateRow('accountsTable',
  { login: 'user1' },        // условие
  { status: 'blocked' }      // новые значения
);

const all = Engine.api.database.getAllData('accountsTable');
console.log(all.data);

Работа с таблицами

getTables(идентификатор) — список таблиц.
getTableInfo(идентификатор, имяТаблицы) — структура таблицы.
createTable(идентификатор, имяТаблицы, столбцы) — создаёт таблицу.
dropTable(идентификатор, имяТаблицы) — удаляет таблицу.
switchTable(идентификатор, имяТаблицы) — переключает активную таблицу компонента.
getRowCount(идентификатор, имяТаблицы?) — число строк.

const count = Engine.api.database.getRowCount('accountsTable');
console.log('Строк в таблице:', count.data);

ℹ️ Engine.api.database управляет видимой таблицей на интерфейсе. Для собственного скрытого хранилища используйте InterfaceRuntime.DB или InterfaceRuntime.KV.