Обобщенные компоненты в Vue позволяют повторно использовать список, не указывая заранее, что именно он будет содержать. Давайте создадим такой компонент с помощью <script setup lang="ts" generic>.
Некоторое время назад я написал статью «Vue 3 с TypeScript: быстрый старт», в которой разобрал основы, необходимые для продуктивной работы с первого дня: типизацию пропсов, событий (emits), Ref<T> и способы заставить редактор кода перестать выдавать ошибки там, где их нет. Та статья заканчивалась на том, на чем останавливается большинство разработчиков: типизации компонента, который точно знает, с какими данными он работает.
Эта статья продолжает тему там, где типы перестают быть конкретными. Допустим, вы создали <UserList>. Затем кому-то понадобился такой же список для продуктов, а потом для счетов, и теперь вы смотрите на три почти идентичных компонента или на один компонент, пропсы которого типизированы как any[].
Это проблема, которую решают обобщенные компоненты. Вы пишете список один раз, и он принимает тип того, что вы ему передаете. Родительский компонент получает полную автоподстановку для пропсов слотов, полезной нагрузки событий и всего остального.
Давайте создадим такой компонент!
Что такое обобщенный компонент?
Обобщенный компонент — это компонент с параметром типа, по аналогии с обобщенными функциями в TypeScript. Вы объявляете тип-заполнитель, используете его в пропсах и событиях, а вызывающий компонент подставляет конкретный тип.
Синтаксис заключается в использовании атрибута generic в теге <script setup>:
Теперь этот T доступен везде внутри блока. Все, что можно написать между угловыми скобками обобщенной функции, можно написать и в этом атрибуте. Вы можете ограничить T с помощью extends, задать значение по умолчанию, объявить второй параметр или указать на тип, импортированный в начале файла.
Краткое примечание о версиях. Атрибут generic появился в Vue 3.3. Инструментарий вокруг него улучшался в версиях 3.4 и 3.5, а в 3.5 деструктуризация реактивных пропсов стала стабильной и включенной по умолчанию. Именно это делает работу со значениями пропсов по умолчанию в обобщенных компонентах удобной, мы рассмотрим это ниже.
Проблема на конкретном примере
Вот компонент списка до внедрения обобщений, написанный для экземпляров User.
UserList.vue
С этим компонентом все в порядке. Он типизирован, работает, редактор помогает вам внутри шаблона. Единственная проблема в том, что он «приварен» к типу User.
Когда поступает запрос на список продуктов, у вас есть два плохих варианта. Скопировать файл и заменить тип, что означает, что каждое исправление теперь придется вносить дважды. Или ослабить типизацию до any[] и потерять всю безопасность типов, как внутри компонента, так и в родительском.
Честно говоря, я в свое время использовал оба этих подхода, и версия с any[] — это та, которая аукнется вам позже.
Тот же список, но обобщенный
TypedList.vue
Давайте разберем это. Атрибут generic="T" вводит параметр типа. С этого момента T — это просто имя типа, которое можно использовать где угодно в блоке, поэтому items: T[] означает «массив того, с чем был вызван этот компонент».
Объявление emit использует тот же T. Это важная часть, потому что полезная нагрузка события select теперь привязана к элементам, которые вы передали, а не к типу, который компонент выбрал заранее.
defineSlots здесь необязателен (инструментарий обычно может сам определить тип пропса слота из <slot :item="item" />), но мне нравится прописывать его для любого переиспользуемого кода. Это документирует контракт слота в начале файла, где его увидит читатель, вместо того чтобы оставлять его скрытым в шаблоне.
Теперь родительский компонент:
Dashboard.vue
Обратите внимание, что здесь нигде не объявляется, чем является T. TypeScript выводит это из :items="users", видит User[] и подставляет User вместо T для всего компонента.
Результат проявляется в двух местах. Внутри слота item является User, поэтому item.email работает с автодополнением, а item.emial подсвечивается красным. А handleSelect проверяется на соответствие событию, поэтому если бы вы типизировали его как (product: Product), вы бы получили ошибку при привязке @select, а не сюрприз во время выполнения.
Замените users на Product[] в другом родительском компоненте, и все перевычислится автоматически. Тот же файл компонента, никаких изменений.
Ограничения и keyof T
Неограниченный T означает, что компонент не может ничего предполагать об элементах. Это нормально для простого оберточного компонента, но реальным компонентам обычно нужно что-то большее. Ключ для v-for, метка для отображения, поле для сортировки.
Вы можете использовать extends и потребовать определенную структуру:
Теперь все, что передается, должно иметь id, и вы можете безопасно написать :key="item.id". Передайте массив объектов без него, и родитель получит ошибку при привязке.
Это работает, но навязывает вызывающему компоненту ваши названия полей. Версия, которую я использую чаще, позволяет вызывающему компоненту самому выбрать поле, при этом проверяя, что оно существует:
KeyedList.vue
Это работает благодаря keyof T. Проп принимает только имена ключей, которые действительно существуют в типе элемента. В родительском компоненте ввод item-key=" открывает список автодополнения с id, name, email, а опечатка вроде item-key="nmae" приведет к ошибке компиляции.
Directory.vue
Я нахожу этот паттерн наиболее полезным в компонентах таблиц и селекторов. Именно там вы в конечном итоге передаете имена столбцов или полей в виде строк и надеетесь, что никто ничего не переименует.
Один момент. Обратите внимание на вызов String() вокруг item[itemKey]. keyof T принимает все ключи типа, включая те, что содержат объекты или даты, а :key ожидает строку или число. Если вы хотите быть строже, вы можете отфильтровать ключи по типу их значений.
Для этого нужен небольшой помощник, отображаемый тип (mapped type), который вы найдете во многих кодовых базах, обычно под разными именами. Поскольку generic может ссылаться на импортированные типы, вы можете вынести его за пределы компонента:
types.ts
KeyedList.vue
Допустим, у User появилось поле createdAt с типом Date. Родитель теперь получит это:
Directory.vue
Ошибка возникнет в label-key в родительском компоненте, именно там, где кто-то сделал неправильный выбор. KeysOfType<User, string | number> разрешается в 'id' | 'name' | 'email', а createdAt просто отсутствует в этом списке. Родитель может называть только те поля, которые действительно можно отобразить.
Вызов String() должен оставаться в шаблоне. Пока T является заполнителем, TypeScript не может разрешить это ограничение. Он не заходит так далеко, чтобы увидеть, что T[K] — это строка или число.
Оба пропса ключей здесь используют один K, что сохраняет сигнатуру читаемой. Им не обязательно называть одно и то же поле, но они подчиняются одному и тому же ограничению. Если им когда-нибудь понадобятся разные ограничения (ключ, который может быть числом, и метка, которая должна быть строкой), им потребуется по отдельному параметру.
Обычно я не утруждаю себя второй версией. Два параметра типа плюс вспомогательный тип делают компонент сложнее для чтения, чем та дополнительная безопасность, которую они дают, а случайный [object Object] в списке — это баг, который исправляется за пять секунд. Но эта возможность полезна, когда компонент достаточно широко используется.
Значения пропсов по умолчанию в обобщенном компоненте
Это часть, которая заметно улучшилась в Vue 3.5. withDefaults всегда была здесь не совсем к месту. Она оборачивает defineProps в еще один вызов функции, и именно на этом дополнительном слое раньше ломался вывод типов. Большинство этих багов уже исправлены, но это все еще выглядит как обходной путь.
Деструктуризация реактивных пропсов, ставшая стабильной и включенной по умолчанию в версии 3.5, полностью решает эту проблему. Вы деструктурируете пропсы и используете обычные значения по умолчанию JavaScript:
EmptyableList.vue
items и emptyMessage остаются реактивными после деструктуризации, потому что компилятор автоматически добавляет к этим именам префикс props. Вывод типов (generic inference) при этом не затрагивается, так как defineProps вызывается напрямую.
Однако есть важное предостережение! И оно довольно серьезное.
Компилятор выполняет это действие путем переписывания имен, причем делает это везде в блоке. Поэтому watch(emptyMessage, ...) будет означать watch(props.emptyMessage, ...). Это считывает свойство один раз и передает результат, из-за чего watch получает строку, которую он никак не может отслеживать.
Компилятор обнаруживает это и прерывает сборку с ошибкой, предлагая вместо этого передать геттер. Вот как это исправить:
EmptyableList.vue
Тело геттера по-прежнему находится внутри <script setup>, поэтому emptyMessage там тоже превращается в props.emptyMessage, и теперь оно считывается заново при каждом запуске.
То же правило действует и для композитных функций (composables). Передавайте () => emptyMessage, а не само значение. Компилятор проверяет только watch и toRef, так что это остается на вашей совести. Это правило, которому вы уже следуете для пропсов, просто теперь его легче забыть, так как они выглядят как обычные переменные.
Когда вывод типов не справляется
Вывод типов работает, когда проп несет в себе тип. Иногда это не так. Представьте компонент выбора (select), который получает свои опции из эндпоинта, передаваемого в виде строки:
RemoteSelect.vue
Давайте разберем это.
Ограничение (constraint) для T — это то, что позволяет шаблону считывать option.id и option.label без жалоб, так как гарантируется, что каждая опция имеет оба этих поля.
Я вынес loadOptions в отдельную функцию, чтобы колбэк onMounted оставался синхронным. Vue действительно перехватывает ошибки из асинхронных хуков жизненного цикла, но отправляет их в обработчик ошибок уровня приложения, а не в ваш ref для ошибок. Пользователь останется перед пустым списком, не понимая, в чем причина. Самостоятельный вызов .catch() позволяет сохранить ошибку там, где вы сможете ее отобразить.
Проблема типизации заключается в том, что ни один проп не передает T в компонент. TypeScript не имеет данных для обратного вывода, поэтому T откатывается к ограничению. Внутри компонента это нормально, но проблема возникает, как только опция передается наружу. Полезная нагрузка (payload) события change типизируется как { id: number; label: string } и никак иначе, поэтому родитель, ожидающий выбранную страну, не получает ни одного поля, которое есть в его собственном типе Country.
У Vue Language Tools есть решение для этого — комментарий, который позволяет родителю вручную указать тип:
AddressForm.vue
Комментарий ставится на строке прямо перед компонентом, и тип внутри фигурных скобок становится тем, чем будет T для этого конкретного экземпляра. Country все еще должна соответствовать ограничению, поэтому если ваш тип Country называет поля code и name, вы получите ошибку на строке с комментарием, а не в самом компоненте. Стоит знать об этом, прежде чем тратить на это полдня.
Еще две вещи. Это функция проверки типов от инструментов разработки, а не то, что известно среде выполнения Vue, поэтому она работает только если вы используете vue-tsc или работаете в редакторе с расширением Vue. И это не самая красивая вещь, которую вы напишете на этой неделе.
Честно говоря, когда я сталкиваюсь с этим, я сначала спрашиваю себя, должен ли компонент вообще заниматься загрузкой данных. Загрузка данных снаружи и передача массива в виде пропа дает вам вывод типов «бесплатно» и компонент, который гораздо проще тестировать. Однако иногда самодостаточный виджет — это именно то, что вам нужно, и вот как его типизировать.
Когда не стоит использовать дженерики
Дженерики предназначены для компонентов, которым действительно не важно, какую структуру имеют их данные. Списки, таблицы, селекторы, выпадающие списки — все, что упорядочивает элементы и возвращает их в слот.
Это неподходящий инструмент, когда компоненту действительно важно, что внутри. Скажем, у вас есть <UserCard>, который считывает user.avatarUrl, использует инициалы из user.firstName и показывает бейдж, если user.role — admin. Этот компонент работает с пользователями. Типизация пропа как User говорит об этом одним словом, и любой, кто читает файл, знает, с чем имеет дело. Сделайте его дженериком, и вам придется добавить ограничение, перечисляющее все три поля. Это та же информация, но в форме, которую сложнее читать. И вам придется обновлять ее вручную каждый раз, когда карточка начинает использовать еще одно поле.
Другой случай, когда я бы пропустил это — если компонент используется ровно в одном месте. Параметр типа — это реальная сложность, и она окупается только при использовании в нескольких местах. Напишите конкретный тип, а сделайте его дженериком в тот день, когда появится второй потребитель.
Заключение
Дженерик-компоненты закрывают последний реальный пробел в поддержке TypeScript в Vue. Компоненты, работающие со структурами данных, которые они не знают заранее, теперь могут быть правильно типизированы с помощью одного атрибута. Вы получаете выводимые пропсы слотов, выводимые полезные нагрузки событий и ограничения keyof T, которые заставляют строковые пропсы проверять самих себя.
Подробности можно найти в разделе о дженериках и разделе defineSlots в документации <script setup> — они короткие и стоят прочтения, а Reactive Props Destructure полностью раскрывает поведение значений по умолчанию.
Удачной типизации!












