Українська
Створення проєкту
Крок 1. Angular для розробника C#
Навіщо. Досі все працювало на сервері. Клієнт працює в браузері, а браузери виконують JavaScript. Chatex пише його на TypeScript – JavaScript зі статичними типами, який компілюється в JavaScript – і структурує за допомогою Angular, повноцінного фреймворку від Google: компоненти, маршрутизація, форми, HTTP-клієнт, впровадження залежностей і система збирання в одному пакеті. Його альтернативи, React і Vue, – це бібліотеки, навколо яких кожна команда збирає власний набір інструментів; для розробника C# Angular – найзнайоміший вибір, бо в ньому є контейнер DI, сервіси, атрибути (декоратори) і строгий компілятор.
Таблиця 15.1 зіставляє словник Angular із тим, що ви знаєте з .NET.
Таблиця 15.1. Терміни Angular та їхні відповідники в .NET
| Angular | .NET | Що це |
|---|---|---|
npm, package.json, package-lock.json | NuGet, Directory.Packages.props, packages.lock.json | пакети, їхні версії й точне розв’язане дерево |
angular.json | .csproj, Directory.Build.props | як проєкт збирається, запускається, тестується й перевіряється лінтером |
tsconfig.json | параметри компілятора у файлі проєкту | параметри компілятора TypeScript |
компонент (клас @Component + шаблон) | компонент Razor | частина інтерфейсу користувача з її станом |
сервіс (@Injectable) | клас, зареєстрований в IServiceCollection | логіка й стан, спільні для компонентів |
inject(T) | впровадження через конструктор | отримання залежності з контейнера DI |
Observable<T>, Promise<T> | IObservable<T>, Task<T> | асинхронні результати |
| сигнал | властивість, що викликає PropertyChanged | значення, яке повідомляє своїх читачів про зміну |
Сучасний Angular (тут – версія 22) відрізняється від Angular зі старих посібників трьома речами, які цей модуль використовує всюди:
- Автономні компоненти. Компонент перелічує компоненти, директиви й канали (pipes), що їх використовує його шаблон, у власному масиві
imports. КласівNgModuleнемає. - Сигнали. Стан зберігається в сигналах – значеннях, які сповіщають своїх читачів, – а не у звичайних полях, які Angular мусить порівнювати.
- Виявлення змін без zone.js (zoneless). Angular більше не підміняє кожен API браузера бібліотекою
zone.js, щоб здогадуватися, коли щось могло змінитися. Він перемальовує компонент, коли змінюється сигнал, який той читає, коли спрацьовує обробник події його шаблону або коли про це сказано явно. Це пояснює крок 4 розділу про каркас.
Node.js і npm
Інструменти Angular працюють на Node.js, який ви встановили в темі 2; браузер Node.js не бачить. npm (Node Package Manager) постачається разом із ним. npm install читає package.json, завантажує пакети в папку node_modules і записує точні версії в package-lock.json; npm ci встановлює саме те, що вказано у файлі блокування, як це робить CI. npx <tool> запускає інструмент із node_modules або завантажує його для одного запуску.
Крок 2. Створення робочої області
Навіщо. Angular CLI (@angular/cli) створює робочу область (workspace): папку з конфігурацією, пакетами й першим застосунком. Ми запускаємо його один раз через npx, тож нічого не встановлюється глобально, і фіксуємо його версію, щоб ви отримали ті самі файли, що й в еталоні.
Що зробити. З кореня репозиторію:
powershell
npx @angular/[email protected] new chatex --directory Source/Chatex.Web --style tailwind --ssr=false --zoneless --ai-config none --skip-git --interactive=falseПараметри пояснено в таблиці 15.2.
Таблиця 15.2. Параметри ng new
| Параметр | Значення |
|---|---|
chatex | назва робочої області й проєкту; вона стає ціллю збирання chatex і вихідною папкою dist/chatex |
--directory Source/Chatex.Web | створити робочу область поруч із проєктами .NET, а не в ./chatex |
--style tailwind | використати Tailwind CSS: встановлює tailwindcss і @tailwindcss/postcss та записує .postcssrc.json |
--ssr=false | без рендерингу на сервері; API віддає JSON, а зібрані файли віддає Nginx (тема 24) |
--zoneless | без zone.js: виявлення змін керується сигналами (типово для нових проєктів; ми вказуємо це явно) |
--ai-config none | без файлів конфігурації для ШІ-асистентів кодування |
--skip-git | не створювати репозиторій Git: ми вже всередині нього |
--interactive=false | не ставити запитань; усе, чого не вказано, бере типове значення (наприклад, маршрутизація й Vitest) |
CLI виводить створювані файли й установлює пакети:
CREATE Source/Chatex.Web/.prettierrc (173 bytes)
CREATE Source/Chatex.Web/angular.json (1976 bytes)
CREATE Source/Chatex.Web/package.json (875 bytes)
CREATE Source/Chatex.Web/README.md (1518 bytes)
CREATE Source/Chatex.Web/tsconfig.json (939 bytes)
CREATE Source/Chatex.Web/.editorconfig (331 bytes)
CREATE Source/Chatex.Web/.gitignore (666 bytes)
CREATE Source/Chatex.Web/tsconfig.app.json (412 bytes)
CREATE Source/Chatex.Web/tsconfig.spec.json (423 bytes)
CREATE Source/Chatex.Web/.postcssrc.json (57 bytes)
CREATE Source/Chatex.Web/.vscode/extensions.json (134 bytes)
CREATE Source/Chatex.Web/.vscode/launch.json (490 bytes)
CREATE Source/Chatex.Web/.vscode/tasks.json (1020 bytes)
CREATE Source/Chatex.Web/src/main.ts (228 bytes)
CREATE Source/Chatex.Web/src/index.html (305 bytes)
CREATE Source/Chatex.Web/src/styles.css (105 bytes)
CREATE Source/Chatex.Web/src/app/app.spec.ts (704 bytes)
CREATE Source/Chatex.Web/src/app/app.ts (301 bytes)
CREATE Source/Chatex.Web/src/app/app.css (0 bytes)
CREATE Source/Chatex.Web/src/app/app.html (20488 bytes)
CREATE Source/Chatex.Web/src/app/app.config.ts (322 bytes)
CREATE Source/Chatex.Web/src/app/app.routes.ts (80 bytes)
CREATE Source/Chatex.Web/public/favicon.ico (15086 bytes)
- Installing packages (npm)...
✔ Packages installed successfully.Таблиця 15.3 показує, для чого потрібен кожен створений файл і що з ним відбувається в цьому модулі.
Таблиця 15.3. Створені файли
| Файл | Призначення | У Chatex |
|---|---|---|
package.json, package-lock.json | пакети й скрипти npm | розширюється на кроці 3 |
angular.json | цілі збирання, запуску, тестування й лінтингу | розширюється на кроці 4 |
tsconfig*.json | параметри TypeScript для застосунку й тестів | tsconfig.app.json змінюється на кроці 4 |
.prettierrc, .postcssrc.json | налаштування Prettier і Tailwind (PostCSS) | Prettier отримує плагін у наступному розділі |
.vscode/* | рекомендоване розширення, налагодження й завдання | конфігурація налагодження ng test зникає (наступний розділ) |
src/index.html, src/main.ts, src/styles.css | сторінка, точка входу, глобальні стилі | замінюються в наступних розділах |
src/app/app.ts, app.html, app.css, app.spec.ts | кореневий компонент зі сторінкою привітання та його тест | замінюються й видаляються в розділі про каркас |
src/app/app.config.ts, app.routes.ts | провайдери застосунку та його маршрути | поки що лишаються; теми 16 і 17 їх замінюють |
.editorconfig, .gitignore | налаштування редактора й Git для окремого репозиторію | видаляються зараз: обидва файли вже є в корені репозиторію |
public/favicon.ico | статичні файли, що копіюються у вихідну папку без змін | згодом у цій темі до нього додаються інші піктограми |
Що зробити. Видаліть два файли, які вже покриває корінь репозиторію. Кореневий .editorconfig має розділ для Source/Chatex.Web/**, а кореневий .gitignore ігнорує node_modules/, dist/ і .angular/ (тема 2):
powershell
Remove-Item Source/Chatex.Web/.editorconfig, Source/Chatex.Web/.gitignoreКінці рядків
У Windows CLI записує більшість файлів із кінцями рядків CRLF. Репозиторій зберігає LF (.gitattributes, тема 2), а Prettier, який ми додамо в наступному розділі, наполягає на LF. Файли, які ви заміните лістингами, і так матимуть LF; кілька створених файлів, що їх ми залишаємо, один раз нормалізує npm run format у наступному розділі.
Крок 3. Пакети
Навіщо. ng new установив Angular, TypeScript, Tailwind, Prettier і Vitest. Chatex потребує ще кількох пакетів (табл. 15.4).
Таблиця 15.4. Пакети, додані до створеної робочої області
| Пакет | Вид | Для чого |
|---|---|---|
angular-eslint, eslint, @eslint/js, typescript-eslint | розробка | лінтинг TypeScript і шаблонів Angular (ng lint) |
prettier-plugin-tailwindcss | розробка | Prettier сортує класи Tailwind у фіксованому порядку |
@angular/cdk | виконання | Component Dev Kit: діалоги, меню, накладки, буфер обміну (від теми 17) |
@lucide/angular | виконання | набір піктограм Lucide як компоненти Angular |
@microsoft/signalr | виконання | клієнт SignalR для хаба з теми 14 (тема 20) |
Що зробити. Виконайте такі команди в Source/Chatex.Web:
powershell
Set-Location Source/Chatex.WebESLint додається через ng add, який установлює пакети і запускає схему налаштування бібліотеки: вона записує eslint.config.js, додає ціль lint до angular.json і скрипт lint до package.json:
powershell
npx ng add angular-[email protected] --skip-confirmationCREATE eslint.config.js (1004 bytes)
UPDATE package.json (1020 bytes)
UPDATE angular.json (2187 bytes)
✔ Packages installed successfully.Решта пакетів – звичайні пакети npm:
powershell
npm install @angular/[email protected] @lucide/[email protected] @microsoft/[email protected]powershell
npm install -D prettier-plugin-[email protected]Нарешті вручну додайте до package.json два скрипти Prettier і версію Node.js. Повний файл:
json
{
"name": "chatex",
"version": "0.0.0",
"scripts": {
"ng": "ng",
"start": "ng serve",
"build": "ng build",
"watch": "ng build --watch --configuration development",
"test": "ng test",
"lint": "ng lint",
"format": "prettier --write \"src/**/*.{ts,html,css}\"",
"format:check": "prettier --check \"src/**/*.{ts,html,css}\""
},
"private": true,
"packageManager": "[email protected]",
"engines": {
"node": ">=24"
},
"dependencies": {
"@angular/cdk": "^22.2.6",
"@angular/common": "^22.2.0",
"@angular/compiler": "^22.2.0",
"@angular/core": "^22.2.0",
"@angular/forms": "^22.2.0",
"@angular/platform-browser": "^22.2.0",
"@angular/router": "^22.2.0",
"@lucide/angular": "^1.72.0",
"@microsoft/signalr": "^11.0.0",
"rxjs": "~7.8.0",
"tslib": "^2.3.0"
},
"devDependencies": {
"@angular/build": "^22.2.6",
"@angular/cli": "^22.2.6",
"@angular/compiler-cli": "^22.2.0",
"@eslint/js": "^10.0.1",
"@tailwindcss/postcss": "^4.1.12",
"angular-eslint": "22.6.0",
"eslint": "^10.12.0",
"jsdom": "^30.0.0",
"postcss": "^8.5.3",
"prettier": "^3.8.1",
"prettier-plugin-tailwindcss": "^0.8.1",
"tailwindcss": "^4.1.12",
"typescript": "~6.0.2",
"typescript-eslint": "8.71.0",
"vitest": "^5.0.0"
}
}scripts– це команди проєкту:npm startзапускаєng serve,npm run build–ng build,npm test–ng testі так далі.Run.ps1і робочий процес CI (тема 22) викликають саме ці скрипти.formatпереписує файли,format:checkлише повідомляє про проблеми – його й запускає CI.enginesфіксує, що проєкту потрібен Node.js 24 або новіший.packageManagerзаписавng newразом із версією npm, яку знайшов; у вас може бути інша версія.- Діапазони версій.
^22.2.0дозволяє будь-яку пізнішу версію 22.x,~7.8.0– будь-яку пізнішу 7.8.x;angular-eslintіtypescript-eslintng addзафіксував точно. Діапазони кажуть, що припустимо; файл блокування – що встановлено.
Що зробити. npm install розв’язав найновіші версії в межах цих діапазонів, які можуть бути новішими за еталонні. Щоб збирати з точно тими версіями, що в еталоні – так само, як Directory.Packages.props зафіксував версії NuGet у темі 2, – скопіюйте його файл блокування й установіть із нього:
powershell
Copy-Item D:\Work\Chatex-Reference\Source\Chatex.Web\package-lock.json .powershell
npm cinpm ci видаляє node_modules і встановлює саме те дерево, що в package-lock.json. Відтепер ./Run.ps1 setup робить те саме на свіжому клоні.
Перевірка
powershell
npm ls --depth=0виводить 26 прямих пакетів, наприклад @angular/[email protected], @angular/[email protected], @microsoft/[email protected] і [email protected], без помилок.
Крок 4. Конфігурація робочої області
Навіщо. angular.json описує цілі проєкту – build, serve, test і lint – та параметри збирачів, які їх виконують. Створений файл потребує п’яти змін для Chatex.
Що зробити. Замініть angular.json:
json
{
"$schema": "./node_modules/@angular/cli/lib/config/schema.json",
"version": 1,
"cli": {
"packageManager": "npm",
"schematicCollections": [
"angular-eslint"
],
"analytics": false
},
"newProjectRoot": "projects",
"projects": {
"chatex": {
"projectType": "application",
"schematics": {
"@schematics/angular:component": {
"style": "none"
}
},
"root": "",
"sourceRoot": "src",
"prefix": "app",
"architect": {
"build": {
"builder": "@angular/build:application",
"options": {
"browser": "src/main.ts",
"tsConfig": "tsconfig.app.json",
"assets": [
{
"glob": "**/*",
"input": "public"
}
],
"styles": [
"node_modules/@angular/cdk/overlay-prebuilt.css",
"src/styles.css"
]
},
"configurations": {
"production": {
"budgets": [
{
"type": "initial",
"maximumWarning": "700kB",
"maximumError": "1.2MB"
},
{
"type": "anyComponentStyle",
"maximumWarning": "4kB",
"maximumError": "8kB"
}
],
"outputHashing": "all",
"optimization": {
"scripts": true,
"styles": {
"minify": true,
"inlineCritical": false
},
"fonts": true
}
},
"development": {
"optimization": false,
"extractLicenses": false,
"sourceMap": true
}
},
"defaultConfiguration": "production"
},
"serve": {
"builder": "@angular/build:dev-server",
"configurations": {
"production": {
"buildTarget": "chatex:build:production"
},
"development": {
"buildTarget": "chatex:build:development"
}
},
"defaultConfiguration": "development",
"options": {
"proxyConfig": "proxy.conf.json"
}
},
"test": {
"builder": "@angular/build:unit-test"
},
"lint": {
"builder": "@angular-eslint/builder:lint",
"options": {
"lintFilePatterns": [
"src/**/*.ts",
"src/**/*.html"
]
}
}
}
}
}
}Порівняно зі створеним файлом:
cli.analytics: false– CLI не пропонує надсилати статистику використання.schematicCollectionsдодавng add angular-eslint.schematics–ng generate componentстворює компоненти без файла стилів. Chatex стилізує все класами Tailwind у шаблонах.styles– готовий CSS накладок CDK іде перед нашими стилями: діалоги й меню (тема 17) позиціонуються ним.budgets– збирання попереджає, коли початкове завантаження перевищує 700 кБ, і завершується помилкою понад 1,2 МБ. Створені обмеження (500 кБ і 1 МБ) замалі для застосунку з SignalR і CDK.optimization.styles.inlineCritical: false– типово виробниче збирання вбудовує CSS, потрібний для першого відображення, а решту завантажує невеликим вбудованим скриптом. Виробнича політика безпеки вмісту (Content-Security-Policy, тема 24) дозволяє лише скрипти з наших власних файлів,script-src 'self', тож цей завантажувач було б заблоковано. Вимкнення вбудовування лишає сторінку без вбудованих скриптів.serve.options.proxyConfig– сервер розробки пересилає виклики API до серверної частини (розділ про каркас).lint– додавng add angular-eslint; в еталоні шаблони перелічено по одному в рядку.
Три файли tsconfig лишаються такими, як створені, окрім одного рядка. tsconfig.json містить спільні строгі налаштування (табл. 15.5), tsconfig.app.json компілює застосунок, tsconfig.spec.json – тести. Виключіть із збирання застосунку допоміжні засоби для тестів, які тема 16 кладе в src/testing:
json
/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
{
"extends": "./tsconfig.json",
"compilerOptions": {
"types": []
},
"include": [
"src/**/*.ts"
],
"exclude": [
"src/**/*.spec.ts",
"src/testing/**"
]
}Таблиця 15.5. Помітні параметри компілятора в tsconfig.json
| Параметр | Дія |
|---|---|
strict (з TypeScript 6 увімкнено типово, тож файл його не згадує) | null і undefined – окремі типи, як nullable-референтні типи в C#, а неявний any – помилка: const x: string = null завершується помилкою TS2322 |
noPropertyAccessFromIndexSignature | ключі типу, схожого на словник, треба читати як errors['required'], а не errors.required |
noImplicitReturns, noFallthroughCasesInSwitch | кожен шлях виконання повертає значення, а блоки case не «провалюються» випадково |
strictInjectionParameters, strictInputAccessModifiers | компілятор Angular так само строго перевіряє токени DI та вхідні параметри компонентів |
target: ES2022, module: preserve | сучасний вихідний JavaScript; імпорти розв’язує збирач, а не TypeScript |
Перевірка
Створений застосунок усе ще збирається:
powershell
npm run buildВивід закінчується рядком Application bundle generation complete і папкою dist/chatex/browser.