Українська
Каркас застосунку
Крок 1. Папки вихідного коду
Навіщо. Серверна частина поділена на проєкти, посилання між якими йдуть лише в один бік (тема 2). Клієнт – один проєкт Angular, тож ту саму дисципліну підтримують папки в src/app (табл. 15.6, рис. 15.2).
Таблиця 15.6. Папки в src/app
| Папка | Що містить | Що може використовувати | Теми |
|---|---|---|---|
core/ | одинаки (singleton) без інтерфейсу користувача: api (служби HTTP, моделі DTO, problem details), auth (сесія, перехоплювач, охоронці маршрутів), realtime (SignalR, присутність, набір тексту), media (захищені файли як blob-адреси), ui (тема, сповіщення) | інші папки core/ | 15–20 |
state/ | сховища на сигналах ChatsStore і MessagesStore | core/ | 18–20 |
shared/ui/ | невеликі повторно використовувані компоненти й допоміжні засоби: піктограми, аватар, діалоги, пошук користувачів, канали | core/ | 15–18 |
features/ | сторінки й діалоги, по одній папці на функцію: auth, shell, chat-list, conversation, chat-info, new-chat, discover, settings, user-profile | усе перелічене вище та діалоги інших функцій | 17–21 |
Рис. 15.2. Залежності між папками
Назви файлів відповідають посібнику зі стилю Angular 2025 року, за яким працював ng new: login.page.ts для сторінки, theme.service.ts для сервісу, shell.ts для компонента, chats.store.ts для сховища, problem.spec.ts для тестів problem.ts. Назви класів позбулися старих суфіксів: кореневий компонент називається App, а не AppComponent.
Git не зберігає порожніх папок, тому папки з’являються разом із файлами. Перші дві створюються в цьому розділі.
Крок 2. Запуск без zone.js
Навіщо. Програма C# стартує в Program.cs, будує хост зі своїми сервісами й запускає його. Застосунок Angular робить те саме в src/main.ts: bootstrapApplication створює кореневий інжектор зі списку провайдерів і відображає кореневий компонент у <app-root>.
Що зробити. main.ts лишається таким, як створено; після npm run format він ідентичний еталонному:
ts
import { bootstrapApplication } from '@angular/platform-browser';
import { appConfig } from './app/app.config';
import { App } from './app/app';
bootstrapApplication(App, appConfig).catch((err) => console.error(err));Провайдери надходять з app.config.ts. Поки що він зберігає створений вміст, відформатований Prettier:
ts
import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';
export const appConfig: ApplicationConfig = {
providers: [provideBrowserGlobalErrorListeners(), provideRouter(routes)],
};provideBrowserGlobalErrorListeners()передає помилки, що вислизнули з обробників подій і промісів, доErrorHandlerAngular, який записує їх у консоль.provideRouter(routes)реєструє маршрутизатор із маршрутами зapp.routes.ts, поки що порожнім масивом. Тема 17 заповнює його; тема 16 замінюєapp.config.tsостаточною версією.- Чого бракує, не менш важливо. Старіші застосунки викликали
provideZoneChangeDetection()і завантажувалиzone.jsуpolyfills. Застосунок без zone.js не має ні того, ні другого: уpackage.jsonнемаєzone.js, а вangular.jsonнемаєpolyfills.
Виявлення змін із zone.js і без нього
Angular має знати, коли оновлювати DOM. Роками він використовував zone.js – бібліотеку, що підміняє кожен асинхронний API браузера (setTimeout, addEventListener, fetch, проміси) і після кожного з них повідомляє Angular: «щось могло змінитися». Тоді Angular перевіряв кожен компонент дерева. Це працювало без жодних зусиль розробника, але коштувало додаткового завантаження, зайвої роботи після кожного таймера й руху миші та трасувань стека, повних кадрів zone.
В Angular без zone.js про це говорять явно. Компонент перевіряється, коли змінюється сигнал, який читає його шаблон, коли спрацьовує обробник події його шаблону, коли змінюється один із його вхідних параметрів або коли код викликає markForCheck(). Коли всюди сигнали, як у Chatex, це відбувається автоматично й точно: зміна тексту одного повідомлення перемальовує рівно ті прив’язки, що його читають. Ціна – правило: стан, який показує шаблон, має бути сигналом (або походити із сигналу, вхідного параметра чи каналу async). Звичайне поле, змінене в setTimeout, не відобразиться, доки щось інше не запустить перевірку.
Крок 3. Набір піктограм
Навіщо. Chatex використовує піктограми з Lucide – відкритого набору чітких лінійних піктограм. @lucide/angular постачає кожну піктограму як автономний компонент, що відображає вбудований <svg>. Імпортування лише потрібних піктограм зменшує пакет, а тримання їх в одному списку дозволяє кожному компоненту імпортувати одну константу.
Що зробити. Створіть список:
ts
import {
LucideArrowDown,
LucideArrowLeft,
LucideBell,
LucideBellOff,
LucideCamera,
LucideCheck,
LucideCheckCheck,
LucideCircleExclamationPoint,
LucideCompass,
LucideCopy,
LucideCrown,
LucideDownload,
LucideEllipsisVertical,
LucideFile,
LucideFileText,
LucideGlobe,
LucideInfo,
LucideKeyRound,
LucideLoaderCircle,
LucideLock,
LucideLogOut,
LucideMegaphone,
LucideMessagesSquare,
LucideMonitor,
LucideMoon,
LucidePaperclip,
LucidePencil,
LucidePlus,
LucideReply,
LucideRotateCw,
LucideSearch,
LucideSend,
LucideSettings,
LucideShield,
LucideSquarePen,
LucideSun,
LucideTrash,
LucideUser,
LucideUserMinus,
LucideUserPlus,
LucideUsers,
LucideWifiOff,
LucideX,
} from '@lucide/angular';
/** Every icon the app uses; import this array into a component to use `<svg lucideXxx class="size-5" />`. */
export const ICONS = [
LucideArrowDown,
LucideArrowLeft,
LucideBell,
LucideBellOff,
LucideCamera,
LucideCheck,
LucideCheckCheck,
LucideCircleExclamationPoint,
LucideCompass,
LucideCopy,
LucideCrown,
LucideDownload,
LucideEllipsisVertical,
LucideFile,
LucideFileText,
LucideGlobe,
LucideInfo,
LucideKeyRound,
LucideLoaderCircle,
LucideLock,
LucideLogOut,
LucideMegaphone,
LucideMessagesSquare,
LucideMonitor,
LucideMoon,
LucidePaperclip,
LucidePencil,
LucidePlus,
LucideReply,
LucideRotateCw,
LucideSearch,
LucideSend,
LucideSettings,
LucideShield,
LucideSquarePen,
LucideSun,
LucideTrash,
LucideUser,
LucideUserMinus,
LucideUserPlus,
LucideUsers,
LucideWifiOff,
LucideX,
] as const;Компонент кладе ICONS у свій imports і пише в шаблоні <svg lucideSend class="size-5"></svg>. Атрибут lucideSend вибирає компонент, що малює піктограму; size-5 у Tailwind робить її 20 × 20 px, а text-* її фарбує, бо піктограми малюються кольором currentColor. as const перетворює масив на кортеж лише для читання, який Angular приймає в imports.
Крок 4. Сигнали й сервіс теми
Навіщо. Перший сервіс клієнта зберігає тему: світлу, темну або «як у системі». Це гарний перший приклад сигналів, бо тема – це стан, який має показувати сторінка і який змінюється з трьох боків: за вибором користувача, зі збереженого налаштування й від операційної системи.
Що зробити. Створіть сервіс:
ts
import { DOCUMENT, Injectable, computed, effect, inject, signal } from '@angular/core';
export type ThemePreference = 'light' | 'dark' | 'system';
export const THEME_STORAGE_KEY = 'chatex.theme';
/** Light, dark or follow the OS. The choice is kept per browser; index.html applies it before paint. */
@Injectable({ providedIn: 'root' })
export class ThemeService {
private readonly document = inject(DOCUMENT);
private readonly media = this.document.defaultView?.matchMedia?.('(prefers-color-scheme: dark)');
private readonly systemDark = signal(this.media?.matches ?? false);
readonly preference = signal<ThemePreference>(this.load());
readonly isDark = computed(() => {
const preference = this.preference();
return preference === 'dark' || (preference === 'system' && this.systemDark());
});
constructor() {
this.media?.addEventListener?.('change', (event) => this.systemDark.set(event.matches));
effect(() => {
const dark = this.isDark();
this.document.documentElement.classList.toggle('dark', dark);
this.document
.querySelector('meta[name="theme-color"]')
?.setAttribute('content', dark ? '#18181b' : '#4f46e5');
});
}
set(preference: ThemePreference): void {
this.preference.set(preference);
try {
localStorage.setItem(THEME_STORAGE_KEY, preference);
} catch {
// Storage can be blocked; the choice then lasts for this tab only.
}
}
private load(): ThemePreference {
try {
const saved = localStorage.getItem(THEME_STORAGE_KEY);
return saved === 'light' || saved === 'dark' ? saved : 'system';
} catch {
return 'system';
}
}
}@Injectable({ providedIn: 'root' })реєструє клас як одинак у кореневому інжекторі, що еквівалентноservices.AddSingleton<ThemeService>(). Його створюють, коли хтось уперше його впроваджує, а якщо ніхто не впроваджує – прибирає під час tree-shaking.inject(DOCUMENT)– це впровадження залежностей в Angular як виклик функції. Воно працює в ініціалізаторах полів і конструкторах класів, які створює Angular. ВпровадженняDOCUMENTзамість глобальногоdocumentробить сервіс придатним до тестування й до використання поза браузером.signal(value)створює сигнал, доступний для запису. Читання – це виклик,this.preference(), а запис –set(value)абоupdate(fn).ThemePreference– це об’єднання рядкових літералів: TypeScript дозволяє рівно'light','dark'або'system', як перелічення, значеннями якого є самі рядки.computed(fn)виводить сигнал лише для читання.isDarkчитаєpreferenceіsystemDark; Angular записує ці залежності й перераховуєisDarkлише тоді, коли одна з них змінюється, а між змінами кешує результат.effect(fn)виконує побічну дію щоразу, коли змінюються сигнали, які він прочитав: тут він перемикає класdarkна<html>і перефарбовує панель браузера. Ефекти призначені для синхронізації сигналів із зовнішнім світом (DOM, сховищем); вони не повинні встановлювати інші сигнали.- Налаштування ОС – це запит
matchMedia. Його подіяchangeоновлюєsystemDark, тож користувач із режимом «система», який увімкнув у ОС темну тему на заході сонця, одразу отримує темну тему. setзберігає вибір уlocalStorageза тим самим ключем, якийtheme-init.jsчитає під час наступного запуску.loadприймає лише два допустимі значення, тож пошкоджений запис означає «система».
Сигнали для розробника C#
Сигнал схожий на властивість моделі подання, що викликає PropertyChanged, із двома відмінностями: залежності виявляються автоматично під час виклику геттера, а похідні значення (computed) обчислюються ліниво й кешуються. Немає ні шаблонного коду INotifyPropertyChanged, ні рядка з назвою властивості. Angular використовує сигнали для стану, який показує інтерфейс користувача; спостережувані об’єкти RxJS, з якими ви зустрінетеся в темі 16, лишаються інструментом для потоків подій, як-от відповіді HTTP чи повідомлення хаба.
Тепер перший тест клієнта:
ts
import { TestBed } from '@angular/core/testing';
import { THEME_STORAGE_KEY, ThemeService } from './theme.service';
describe('ThemeService', () => {
beforeEach(() => {
localStorage.clear();
document.documentElement.classList.remove('dark');
});
it('follows the system by default', () => {
const theme = TestBed.inject(ThemeService);
expect(theme.preference()).toBe('system');
});
it('switches to dark, toggles the html class and remembers the choice', () => {
const theme = TestBed.inject(ThemeService);
theme.set('dark');
TestBed.tick();
expect(theme.isDark()).toBe(true);
expect(document.documentElement.classList.contains('dark')).toBe(true);
expect(localStorage.getItem(THEME_STORAGE_KEY)).toBe('dark');
theme.set('light');
TestBed.tick();
expect(document.documentElement.classList.contains('dark')).toBe(false);
});
it('loads the saved choice', () => {
localStorage.setItem(THEME_STORAGE_KEY, 'dark');
expect(TestBed.inject(ThemeService).preference()).toBe('dark');
});
});beforeEachскидає спільний стан, бо jsdom зберігаєlocalStorageі елемент<html>між тестами.TestBed.inject(ThemeService)створює сервіс у свіжому тестовому інжекторі.TestBed.tick()виконує відкладені ефекти. Ефекти планують, а не виконують синхронно, коли змінюється сигнал; у застосунку Angular виконує їх під час виявлення змін, а в тесті це робитьtick().
Крок 5. Кореневий компонент
Навіщо. Створений кореневий компонент показує сторінку привітання Angular з app.html, має порожній app.css і тест для тексту привітання. Кореневий компонент Chatex – лише рамка: <router-outlet>, куди маршрутизатор кладе поточну сторінку, і, починаючи з теми 17, сповіщення.
Що зробити. Видаліть створені шаблон, стилі й тест:
powershell
Remove-Item src/app/app.html, src/app/app.css, src/app/app.spec.tsЗамініть app.ts. Два рядки, виділені жовтим, тимчасові: тема 17 додасть до них систему сповіщень.
angular-ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { ThemeService } from './core/ui/theme.service';
@Component({
selector: 'app-root',
imports: [RouterOutlet],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `<router-outlet />`,
})
export class App {
constructor() {
// Created eagerly so the saved theme and OS changes apply on every page.
inject(ThemeService);
}
}@Component– це декоратор, тобто атрибут, що виконує код, який перетворює клас на компонент.selector: 'app-root'– елемент уindex.html, де Angular його відображає.imports: [RouterOutlet]перелічує те, що використовує шаблон. Автономний компонент компілює свій шаблон точно за цим списком; використання<router-outlet>без імпортуRouterOutlet– помилка компіляції.ChangeDetectionStrategy.OnPush– її використовує кожен компонент Chatex: компонент перевіряється лише тоді, коли про це говорять його вхідні параметри, події або сигнали (правила з вставки про виявлення змін без zone.js вище), а не тому, що десь щось змінилося.templateзаписано вбудовано в шаблонний літерал (зворотні лапки). Для невеликих шаблонів Chatex це тримає клас і розмітку в одному файлі; Angular Language Service усе одно перевіряє його типи.inject(ThemeService)у конструкторі створює сервіс теми під час запуску, тож його ефект застосовує збережену тему й стежить за ОС на кожній сторінці, навіть до того, як якась сторінка скористається сервісом.
Перевірка
powershell
npm test -- --watch=false Test Files 1 passed (1)
Tests 3 passed (3)npm run build, npm run lint і npm run format:check також завершуються успішно.
Крок 6. Проксі для розробки
Навіщо. У виробничому середовищі Nginx віддає файли Angular і пересилає /api та /hubs до API, тож браузер бачить одне джерело (origin, тема 24). Під час розробки сервер розробки Angular працює на http://localhost:4200, а API – на http://localhost:5214: два джерела. Токен оновлення подорожує в cookie HttpOnly, обмеженому шляхом API (тема 13), а міждоменним викликам знадобилися б CORS і cookie з SameSite=None. Простіше й вірніше надати розробці ту саму форму, що й у виробничому середовищі: сервер розробки пересилає виклики API, а браузер спілкується лише з одним джерелом.
Що зробити. Створіть конфігурацію проксі, на яку angular.json уже посилається:
json
{
"/api": {
"target": "http://localhost:5214",
"secure": false,
"changeOrigin": false
},
"/hubs": {
"target": "http://localhost:5214",
"secure": false,
"ws": true
}
}- Запити
/apiпересилаються до API.changeOrigin: falseзберігає заголовокHostіз запиту браузера. /hubsтакож пересилає оновлення до WebSocket (ws: true): з’єднання SignalR із/hubs/chat(тема 20) теж іде через проксі.secure: falseприймав би самопідписаний сертифікат, якби ціль була HTTPS; API під час розробки працює на звичайному HTTP.
Запустіть API в одному терміналі, з кореня репозиторію:
powershell
./Run.ps1 apiа клієнт – у другому:
powershell
./Run.ps1 web ➜ Local: http://localhost:4200/
➜ press h + enter to show helpПеревірка
Відкрийте
http://localhost:4200. Сторінка порожня, але має заголовок «Chatex», піктограму Chatex на вкладці й колір тла теми вашої ОС: перемикайте ОС між світлою й темною темою, і сторінка йтиме за нею. В інструментах розробника браузера (F12) елемент<html>у темній темі має класdark.Виконайте в консолі
localStorage.setItem('chatex.theme', 'light')і перезавантажте сторінку: вона лишається світлою навіть за темної ОС.localStorage.removeItem('chatex.theme')повертає до режиму «система».У третьому терміналі викличте API через проксі:
powershellcurl.exe -i http://localhost:4200/api/meПерший рядок –
HTTP/1.1 401 Unauthorized: запит дійшов до API, якому потрібен токен. Без проксі сервер розробки відповів би200 OKзindex.html– його запасним варіантом для невідомих шляхів.