Angular で進行状況を示すファイルアップロードとローカルサーバー
選択したファイルを Angular の HttpClient で
FormData として送信し、サーバーが受け付けた場合にのみ成功を表示します。このチュートリアルでは、進行状況とエラーを表示する単一ファイルのアップローダーと、実行可能な Node.js 受信サーバーを構築します。受信サーバーはリクエストを検証してチェックサムを返しますが、ファイルは保存しません。
必要な環境
Node.js 26.8.2、Corepack と Yarn 4.12.0、モダンブラウザーを使用します。この例では Angular 22.1.7、Angular CLI/build 22.1.8、TypeScript 6.0.3 にバージョンを固定しています。Angular 22 はサポート対象のリリースです。Node と TypeScript の要件は互換性一覧で確認できます。サーバーサイドレンダリングを使わないスタンドアロンのブラウザーアプリです。この例は macOS 上の Chromium 145 でテストしました。コマンドは、macOS、Linux、WSL 上の Bash など、POSIX シェルで実行します。
新しい angular-upload-demo フォルダーを作成したい親ディレクトリで、次のコマンドを実行します。mkdir は既存の作成先を拒否し、依存する各コマンドは直前のコマンドが成功した場合にのみ実行されます。以降のインストールでも同じ依存関係の解決結果を使えるよう、生成されたロックファイルを保持してください。
(
mkdir angular-upload-demo &&
cd angular-upload-demo &&
NG_CLI_ANALYTICS=false corepack yarn@4.12.0 dlx @angular/cli@22.1.8 new upload-demo \
--directory . --standalone --routing=false --ssr=false --style=css \
--skip-tests --skip-git --skip-install --package-manager=yarn --defaults &&
printf 'nodeLinker: node-modules\n' > .yarnrc.yml &&
touch yarn.lock &&
corepack yarn@4.12.0 add --exact \
@angular/common@22.1.7 @angular/compiler@22.1.7 @angular/core@22.1.7 \
@angular/forms@22.1.7 @angular/platform-browser@22.1.7 @angular/router@22.1.7 \
rxjs@7.8.2 fastify@5.12.5 @fastify/multipart@10.1.1 &&
corepack yarn@4.12.0 add --dev --exact \
@angular/build@22.1.8 @angular/cli@22.1.8 @angular/compiler-cli@22.1.7 typescript@6.0.3
)
成功したら、エディターで angular-upload-demo を開きます。以下のファイル名はすべて、このフォルダーからの相対パスです。生成された src/main.ts だけを置き換え、ほかの三つのファイルは指定の名前で作成します。
ブラウザーのマルチパートエンコーディングの利用
ネイティブのファイル入力から File を取得し、FormData.append('file', file) で、そのバイト列をサーバーが期待するマルチパートフィールドに入れます。Content-Type は設定しないでください。MDN の FormData ガイドで説明されているとおり、ブラウザーがマルチパートの境界を追加します。この入力の change イベントには、FormsModule も
ngModel も不要です。
アップロードの進行状況を取得するには、Angular の XHR バックエンドが必要です。provideHttpClient(withXhr()) を設定し、observe: 'events' と
reportProgress: true でイベントを要求します。デフォルトの Fetch バックエンドはアップロードの進行状況を通知しません。Angular のドキュメントには、XHR の設定とリクエストのイベント順序が記載されています。進行状況イベントが示すのは、マルチパートの区切りなども含めたリクエスト本文の送信状況です。送信が 100% になっても、サーバーがファイルを受け付けたとは限りません。
アップロードコンポーネントの追加
src/main.ts を、次の完全なエントリーポイントに置き換えます。HTTP イベントを受信すると、シグナルがビューを更新します。リクエストの処理中は両方のコントロールが無効になり、ハンドラーでも重複呼び出しを防ぎます。リクエストが失敗した場合は、手動で再試行できるように選択したファイルを保持します。成功した場合はネイティブ入力をクリアし、同じファイルを再び選択できるようにします。
import { HttpClient, HttpErrorResponse, HttpEventType, provideHttpClient, withXhr } from '@angular/common/http'
import { Component, DestroyRef, inject, signal } from '@angular/core'
import { takeUntilDestroyed } from '@angular/core/rxjs-interop'
import { bootstrapApplication } from '@angular/platform-browser'
import { finalize } from 'rxjs'
@Component({
selector: 'app-root',
standalone: true,
templateUrl: './upload.html',
})
class UploadDemo {
readonly selected = signal<File | null>(null)
readonly busy = signal(false)
readonly progress = signal<number | null>(null)
readonly message = signal('Choose a file to upload.')
readonly #http = inject(HttpClient)
readonly #destroyRef = inject(DestroyRef)
select(event: Event): void {
if (this.busy()) return
const input = event.target
if (!(input instanceof HTMLInputElement)) return
const file = input.files?.[0] ?? null
this.progress.set(null)
this.selected.set(null)
if (file === null) {
this.message.set('Choose a file to upload.')
return
}
if (file.size > 1024 * 1024) {
input.value = ''
this.message.set('Choose a file of 1 MiB or smaller.')
return
}
this.selected.set(file)
this.message.set(`Ready to upload “${file.name}”.`)
}
upload(input: HTMLInputElement): void {
const file = this.selected()
if (file === null || this.busy()) return
this.busy.set(true)
this.progress.set(null)
this.message.set(`Sending “${file.name}”…`)
const body = new FormData()
body.append('file', file)
this.#http.post('/api/upload', body, {
observe: 'events',
reportProgress: true,
timeout: 30_000,
}).pipe(
takeUntilDestroyed(this.#destroyRef),
finalize(() => this.busy.set(false)),
).subscribe({
next: (event) => {
if (event.type === HttpEventType.UploadProgress) {
const total = event.total
this.progress.set(total != null && total > 0
? Math.floor(100 * event.loaded / total)
: null)
if (total != null && total > 0 && event.loaded >= total) {
this.message.set('Transfer complete. Waiting for server acceptance…')
}
} else if (event.type === HttpEventType.Response) {
this.selected.set(null)
input.value = ''
this.message.set(`Server accepted “${file.name}”. This demo did not save it.`)
}
},
error: (error: unknown) => {
this.progress.set(null)
this.message.set(error instanceof HttpErrorResponse && error.status !== 0
? `Upload failed (HTTP ${error.status}). Try again or choose another file.`
: 'Network error or timeout. The server may have received the file; check before retrying.')
},
})
}
}
bootstrapApplication(UploadDemo, {
providers: [provideHttpClient(withXhr())],
}).catch(console.error)
コントロールとフィードバックへのラベル付け
src/upload.html を作成します。ネイティブ入力とボタンはキーボード操作に対応しています。ステータス領域はフォーカスを移動せずにフィードバックを読み上げます。合計サイズが不明な場合、プログレスバーは進捗不定の表示になります。ローカルでの小さなファイルのアップロードは、途中のパーセンテージを表示する前に完了する場合があります。
<main>
<h1>Upload a file</h1>
<p id="file-hint">Up to 1 MiB. The server rejects empty files and does not save uploads.</p>
<label for="upload-file">Choose a file</label>
<input #fileInput id="upload-file" type="file" aria-describedby="file-hint"
[disabled]="busy()" (change)="select($event)" />
<button type="button" [disabled]="selected() === null || busy()"
(click)="upload(fileInput)">Upload</button>
@if (busy()) {
<p>
<progress aria-label="Request upload progress" max="100" [attr.value]="progress()"></progress>
@if (progress() !== null) {
<span>{{ progress() }}% transferred</span>
}
</p>
}
<p role="status" aria-atomic="true">{{ message() }}</p>
</main>
アップロードを検証する受信サーバーの実行
プロジェクトルートに server.ts を作成します。POST /api/upload を受け付け、マルチパートのファイルフィールドは
file という名前のものがちょうど一つ必要です。空のファイルは HTTP 422 で拒否し、ファイルサイズの上限は 1 MiB とします。マルチパートプラグインがサイズとパート数の上限を適用し、toBuffer() がレスポンス生成前にファイルを読み取ります。
受信サーバーは、受信したファイル名、フィールド名、バイト数、SHA-256 チェックサムを返します。ファイルはメモリ内にバッファリングし、リクエストの処理後に破棄します。保存先パスがないため、既存のファイルを上書きすることはありません。このローカルデモはあらゆる種類のファイルを受け付け、ループバックアドレスにのみバインドします。
import { createHash } from 'node:crypto'
import multipart from '@fastify/multipart'
import Fastify from 'fastify'
const server = Fastify()
await server.register(multipart, {
limits: { files: 1, fields: 0, parts: 1, fileSize: 1024 * 1024 },
})
server.setErrorHandler((error, _request, reply) => {
// A part-count limit can interrupt toBuffer() before the parser's own error surfaces.
if (error instanceof Error && 'code' in error && error.code === 'ERR_STREAM_PREMATURE_CLOSE') {
return reply.code(400).send({ error: 'Incomplete multipart upload.' })
}
const status = error instanceof Error && 'statusCode' in error
&& typeof error.statusCode === 'number'
&& error.statusCode >= 400 && error.statusCode <= 599
? error.statusCode : 500
reply.code(status).send({ error: 'Upload failed.' })
})
server.post('/api/upload', async (request, reply) => {
let receipt: { field: string; filename: string; bytes: number; sha256: string } | null = null
for await (const part of request.parts()) {
if (part.type !== 'file') {
return reply.code(400).send({ error: 'Send one file field named file.' })
}
const bytes = await part.toBuffer()
if (part.fieldname !== 'file') {
return reply.code(400).send({ error: 'Send one file field named file.' })
}
if (bytes.length === 0) {
return reply.code(422).send({ error: 'Empty files are not accepted.' })
}
receipt = {
field: part.fieldname,
filename: part.filename,
bytes: bytes.length,
sha256: createHash('sha256').update(bytes).digest('hex'),
}
}
if (receipt === null) {
return reply.code(400).send({ error: 'Send one file field named file.' })
}
return receipt
})
const address = await server.listen({ host: '127.0.0.1', port: Number(process.env.PORT ?? '3000') })
console.log(`Receiver listening at ${address}`)
プロジェクトルートに proxy.json を作成し、Angular 開発サーバーが
/api リクエストを Node に転送するようにします。ブラウザーは自身のオリジンを使用するため、この例では CORS の設定は不要です。
{
"/api/**": {
"target": "http://127.0.0.1:3000"
}
}
セットアップに使った親ディレクトリから、一つ目のターミナルで受信サーバーを起動します。
cd angular-upload-demo && node server.ts
二つ目のターミナルでも同じ親ディレクトリから、アプリをビルドして配信します。
cd angular-upload-demo &&
corepack yarn@4.12.0 ng build &&
NG_CLI_ANALYTICS=false corepack yarn@4.12.0 ng serve --host 127.0.0.1 --port 4200 --proxy-config proxy.json
http://127.0.0.1:4200 を開きます。いずれかのポートが使用中の場合は、別の空いているポートを使います。Node の起動時に PORT を設定し、それに合わせてプロキシの転送先を更新してください。Angular の --port も必要に応じて変更します。終了時には Ctrl+C で両方のサーバーを停止します。再ビルドすると、この生成アプリの dist/ 出力が置き換わります。アップロードされたファイルがそこに書き込まれることはありません。
成功と失敗の個別確認
1 MiB 未満の空でないファイルを選択し、Upload を押します。最終メッセージに「Server accepted」と表示され、デモではファイルを保存していないことが説明されているか確認してください。ブラウザーの Network パネルで
/api/upload のレスポンスを確認します。field は file である必要があり、bytes と sha256 は、マルチパートの区切りなどを除いた受信ファイルの内容を表します。同じファイルをもう一度選択して、別のリクエストを送信してください。
空のファイルで HTTP 422 のメッセージを確認してください。1 MiB を超えるファイルは、送信前に UI で拒否されるはずです。UI を経由しない呼び出しに対しても、サーバー側で独自に上限を適用します。アップロードの処理中は、送信が 100% に達した後も、ファイル選択と Upload ボタンは無効のままです。サーバーのレスポンスが遅延した場合や拒否を示した場合に、アップロードが受け付けられたというメッセージを表示してはいけません。
接続失敗を試すには、ページを読み込んだ後、ブラウザーの Network パネルをオフラインに切り替えてアップロードしてください。再試行する前に接続を復元します。Node 受信サーバーだけを停止すると、代わりに開発用プロキシから HTTP エラーが返る場合があります。ネットワークエラーやタイムアウトからは、接続が失敗する前にサーバーがリクエストを処理したかどうかは判断できません。この例では自動再試行は行いません。
サイズの確認は利用者の利便性のためであり、セキュリティ境界ではありません。アプリケーションで JPEG、PNG、PDF のアップロードが必要な場合、入力の
accept 属性で選択を誘導できますが、この属性も
File.type もクライアントが制御できるヒントにすぎません。受信サーバーで実際の内容を検証してください。MDN では、ファイル選択の制限ではアップロードを検証できない理由を説明しています。デプロイする受信サーバーには、アプリケーションの認証、認可、リクエスト偽造対策、ストレージポリシーも必要です。ローカルの受信サーバーはこれらを提供しません。
必要に応じた再開機能の追加
このマルチパートリクエストでは、転送に失敗すると最初からやり直します。中断したアップロードを続行する必要がある場合は、tus-js-client を使った Angular での再開可能なファイルアップロードを参照してください。既製のファイル選択とアップロード UI が必要な場合は、公式の Uppy Angular ガイドでコンポーネントと互換バージョンを確認できます。その UI に、同じプロトコルを使うアップローダープラグインと受信サーバーを組み合わせてください。
