Структура объектов данных

Библиотека Awesomplete работает поверх стандартных HTML-элементов ввода и опирается на универсальную модель данных, позволяющую использовать как простые строки, так и структурированные объекты. Понимание того, как устроены объекты данных внутри Awesomplete, критично для построения расширяемых списков автодополнения, особенно в случаях, когда требуется отображение дополнительной информации, кастомная сортировка или динамическое формирование подсказок.

Базовая модель данных

Awesomplete поддерживает два основных формата источников данных:

  • массив строк
  • массив объектов

Строковый формат используется для простых сценариев:

new Awesomplete(input, {
  list: ["Apple", "Apricot", "Avocado"]
});

Однако при переходе к объектной модели структура данных становится более гибкой:

new Awesomplete(input, {
  list: [
    { label: "Apple", value: "apple" },
    { label: "Apricot", value: "apricot" },
    { label: "Avocado", value: "avocado" }
  ]
});

В объектной форме библиотека разделяет два ключевых понятия:

  • label — отображаемый текст
  • value — значение, подставляемое в input

Структура объекта элемента списка

Объект, используемый в Awesomplete, может быть минимально представлен следующими полями:

label

Поле label определяет текст, который пользователь видит в выпадающем списке.

Пример:

{ label: "New York", value: "NYC" }

Если объект содержит только одно поле label, Awesomplete может использовать его как отображаемое и как подставляемое значение одновременно.

value

Поле value определяет фактическое значение, которое будет вставлено в input после выбора элемента.

Пример поведения:

{ label: "JavaScript", value: "js" }
  • отображается: JavaScript
  • вставляется в input: js

key (внутреннее использование)

Awesomplete может создавать внутренние ключи для оптимизации поиска и сопоставления. При передаче объектов без явной структуры библиотека нормализует их в единый формат.

Неявная нормализация данных

Если в список передается массив строк, Awesomplete автоматически преобразует их в объектную форму:

["Berlin", "Bern", "Bergen"]

Преобразуется внутренне в:

[
  { label: "Berlin", value: "Berlin" },
  { label: "Bern", value: "Bern" },
  { label: "Bergen", value: "Bergen" }
]

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

Объекты с расширенной структурой

Хотя официально Awesomplete использует только label и value, разработчики часто расширяют объект для собственных нужд:

{
  label: "Tokyo",
  value: "TYO",
  country: "Japan",
  population: 37_000_000
}

Дополнительные поля не участвуют в логике библиотеки, но могут использоваться в пользовательских расширениях:

  • кастомный рендеринг списка
  • фильтрация по дополнительным параметрам
  • аналитика выбора

Обработка объектов в фильтрации

При поиске совпадений Awesomplete опирается на строковое представление объекта. Обычно используется label, преобразованный к строке.

Логика упрощенно выглядит так:

  • если элемент — строка → используется напрямую
  • если элемент — объект → используется label

Пример:

{ label: "San Francisco", value: "SFO" }

Поиск выполняется по строке "San Francisco".

Сравнение строкового и объектного форматов

Строковый формат

["Red", "Green", "Blue"]

Характеристики:

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

Объектный формат

[
  { label: "Red", value: "#ff0000" },
  { label: "Green", value: "#00ff00" },
  { label: "Blue", value: "#0000ff" }
]

Характеристики:

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

Использование функций как источника данных

Awesomplete допускает передачу функции вместо массива. В этом случае структура объектов формируется динамически:

new Awesomplete(input, {
  list: function (text, callback) {
    callback([
      { label: text + "1", value: "A" },
      { label: text + "2", value: "B" }
    ]);
  }
});

Здесь структура объектов становится результатом вычисления, а не статического массива.

Внутреннее приведение типов

При инициализации Awesomplete выполняет нормализацию:

  1. Проверка типа элемента
  2. Преобразование строки в объект
  3. Установка label и value
  4. Индексация для поиска

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

Влияние структуры объекта на UX

Правильное использование структуры объектов напрямую влияет на пользовательский опыт:

  • label улучшает читаемость подсказок
  • value обеспечивает корректную передачу данных в форму
  • расширенные поля позволяют отображать контекст

Пример полезной структуры:

{
  label: "Berlin — Germany",
  value: "berlin",
  code: "DE-BE"
}

Ограничения структуры данных

Несмотря на гибкость, структура объектов в Awesomplete имеет ограничения:

  • игнорируются все поля, кроме label и value
  • отсутствует встроенная поддержка вложенных объектов
  • поиск не индексирует дополнительные свойства
  • сортировка зависит от строкового представления

Роль структуры данных в расширениях

При создании кастомных расширений Awesomplete структура объектов становится основой для:

  • кастомного рендера элементов списка
  • интеграции с REST API
  • асинхронной подгрузки данных
  • фильтрации по сложным правилам

В таких случаях объект перестает быть просто контейнером данных и превращается в модель доменной сущности.

Пример комплексной структуры данных

[
  {
    label: "Python",
    value: "python",
    type: "language",
    popularity: 1
  },
  {
    label: "JavaScript",
    value: "javascript",
    type: "language",
    popularity: 2
  },
  {
    label: "Go",
    value: "go",
    type: "language",
    popularity: 3
  }
]

Такая структура позволяет:

  • группировать элементы
  • реализовывать фильтрацию по типу
  • сортировать по популярности
  • сохранять семантику данных вне UI

Нормализация и предсказуемость данных

Ключевым принципом Awesomplete является предсказуемость:

  • любой входной формат приводится к единой модели
  • отображение отделено от значения
  • логика поиска основана на нормализованном label

Это делает структуру данных стабильной основой для построения автодополнения в любых сценариях использования.

Оглавление