69 lines
5.6 KiB
Markdown
69 lines
5.6 KiB
Markdown
|
# Хуки (React Hooks)
|
|||
|
|
|
|||
|
|
> В проекте для создания пользовательских хуков используется только React (функциональные компоненты и хуки).
|
|||
|
|
> В этом разделе собраны основные правила и рекомендации по созданию и оформлению хуков. Следуйте этим принципам, чтобы обеспечить чистую архитектуру, переиспользуемость и единый стиль работы с хуками в проекте.
|
|||
|
|
|
|||
|
|
## Рекомендации по использованию сторонних хуков
|
|||
|
|
- Если есть возможность, используйте хуки Mantine в компонентах и кастомных хуках для работы с состоянием, темизацией, медиа-запросами и другими возможностями библиотеки.
|
|||
|
|
- Не дублируйте функциональность, уже реализованную в Mantine.
|
|||
|
|
|
|||
|
|
## Структура
|
|||
|
|
- Каждый хук размещается в отдельном файле с именем `use-<hook-name>.hook.ts` в папке `hooks/` на своём уровне абстракции согласно архитектуре проекта.
|
|||
|
|
- Имя хука — в стиле camelCase с префиксом `use` (например, `useTodoFilter`).
|
|||
|
|
- Для сложных возвращаемых структур использовать отдельные типы или интерфейсы, размещая их в папке `types/` на своём уровне абстракции.
|
|||
|
|
|
|||
|
|
## Именование
|
|||
|
|
- Соблюдайте [правила именования файлов и папок](#правила-именования-файлов-и-папок):
|
|||
|
|
- Файл хука — `use-<hook-name>.hook.ts` (kebab-case).
|
|||
|
|
- Имя хука — camelCase с префиксом `use`.
|
|||
|
|
|
|||
|
|
## Требования
|
|||
|
|
- Хук должен быть строго типизирован: все параметры, возвращаемые значения и внутренние переменные должны иметь явные типы.
|
|||
|
|
- Не хранить бизнес-логику, связанную с несколькими слоями — хук должен быть изолирован в рамках своего слоя/feature.
|
|||
|
|
- Не дублировать логику между хуками — общие части выносить в shared.
|
|||
|
|
- Не использовать side-effects вне useEffect/useLayoutEffect.
|
|||
|
|
- Для мемоизации возвращаемых значений и функций использовать useMemo и useCallback.
|
|||
|
|
- Не использовать устаревшие или неразрешённые паттерны React.
|
|||
|
|
|
|||
|
|
## Типизация
|
|||
|
|
- Всегда явно указывать типы для всех параметров, возвращаемых значений и состояния внутри хука.
|
|||
|
|
- Не используйте неявное приведение типов и не полагайтесь на автоматический вывод, если это может снизить читаемость или безопасность.
|
|||
|
|
|
|||
|
|
## Документирование
|
|||
|
|
- Документируйте только назначение хука (описание), строго по [правилам документирования кода](#правило-для-документирования-кода).
|
|||
|
|
|
|||
|
|
## Экспорт
|
|||
|
|
- Экспортируйте хук только именованным экспортом через `index.ts` слоя/компонента.
|
|||
|
|
|
|||
|
|
## Примеры
|
|||
|
|
|
|||
|
|
```ts
|
|||
|
|
import { useMemo } from 'react';
|
|||
|
|
import { TodoItem } from '../types/todo-item.interface';
|
|||
|
|
import { TodoStatus } from '../types/todo-status.enum';
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* Хук фильтрации задач по статусу.
|
|||
|
|
*/
|
|||
|
|
export const useTodoFilter = (items: TodoItem[], filter: TodoStatus): TodoItem[] => {
|
|||
|
|
return useMemo(() => {
|
|||
|
|
if (filter === TodoStatus.ALL) return items;
|
|||
|
|
if (filter === TodoStatus.ACTIVE) return items.filter((t) => !t.completed);
|
|||
|
|
return items.filter((t) => t.completed);
|
|||
|
|
}, [items, filter]);
|
|||
|
|
};
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Чек-лист
|
|||
|
|
|
|||
|
|
- [ ] Хук размещён в файле `use-<hook-name>.hook.ts` в папке `hooks/` на своём уровне абстракции согласно архитектуре проекта.
|
|||
|
|
- [ ] Именование файлов и сущностей соответствует [правилам именования файлов и папок](#правила-именования-файлов-и-папок).
|
|||
|
|
- [ ] Все параметры, возвращаемые значения и внутренние переменные строго типизированы.
|
|||
|
|
- [ ] Вся бизнес-логика изолирована в рамках слоя/feature.
|
|||
|
|
- [ ] Нет дублирования логики между хуками.
|
|||
|
|
- [ ] Для мемоизации используется useMemo/useCallback.
|
|||
|
|
- [ ] Не используются side-effects вне useEffect/useLayoutEffect.
|
|||
|
|
- [ ] Документировано только назначение хука (см. [правила документирования кода](#правило-для-документирования-кода)).
|
|||
|
|
- [ ] Нет неиспользуемого или невалидного кода.
|
|||
|
|
- [ ] Экспорт только именованный через индексный файл.
|