Angularパイプ一覧｜date・number・asyncとカスタムパイプ

Angularのパイプとは、テンプレートの中で {{ 値 | パイプ名 }} と書いて、値の「見た目」を整える仕組みです。 日付を 2026/10/03 にする、数値に桁区切りを入れる、Observable の中身を取り出す、といった表示用の変換を、コンポーネントのクラスに処理を足さずに書けます。

この記事では、組み込みパイプ13種すべてを「書式 → 実際の出力」の表にまとめ、date の書式記号、日本語ロケール（ja）を登録したときの出力の違い、引数付きのカスタムパイプの作り方、pure と impure の違いを呼び出し回数のログで確かめた結果まで扱います。表の出力は、すべて下の環境で実際に描画した文字列です。

確認環境：Ubuntu 24.04 / Node.js 24.19.0 / Angular 22.2.1（@angular/cli 22.2.1 の ng new で作成）/ TypeScript 6.0.3 / Vitest 5.0.3（ng test）/ Chromium 141（Playwright 1.56.0）。タイムゾーンは Asia/Tokyo、日付の例は 2026年10月3日（土）14時5分9秒 078 ミリ秒です。

組み込みパイプの早見表

@angular/common が公開しているパイプは次の13種です（22.2.1 の公開名を列挙して確かめました）。出力は既定のロケール（en-US）のものです。

使うパイプは、コンポーネントの imports にクラス名で追加します。 引数はコロン（:）で区切って渡し、パイプは | でいくつでもつなげられます。

パイプの基本の書き方

imports に追加してテンプレートで使う

よく使うパイプをひととおり入れた、そのまま貼って動くコンポーネントです。

// src/app/pipes/order-summary.ts
import { AsyncPipe, CurrencyPipe, DatePipe, DecimalPipe, KeyValuePipe, PercentPipe, SlicePipe, UpperCasePipe } from '@angular/common';
import { Component } from '@angular/core';
import { of } from 'rxjs';
import { TruncatePipe } from './custom.pipes';

@Component({
  selector: 'app-order-summary',
  // 使うパイプだけを imports に並べる
  imports: [AsyncPipe, CurrencyPipe, DatePipe, DecimalPipe, KeyValuePipe, PercentPipe, SlicePipe, UpperCasePipe, TruncatePipe],
  template: `
    <h2>{{ order.code | uppercase }}</h2>
    <p>注文日: {{ order.orderedAt | date: 'yyyy/MM/dd(EEE) HH:mm' }}</p>
    <p>合計: {{ order.total | currency: 'JPY' }}（{{ order.count | number }}点）</p>
    <p>割引率: {{ order.discount | percent: '1.1-1' }}</p>
    <p>メモ: {{ order.note | truncate: 12 }}</p>
    <ul>
      @for (item of order.items | slice: 0 : 2; track item) {
        <li>{{ item }}</li>
      }
    </ul>
    <dl>
      @for (entry of order.options | keyvalue; track entry.key) {
        <dt>{{ entry.key }}</dt>
        <dd>{{ entry.value }}</dd>
      }
    </dl>
    <p>状態: {{ status$ | async }}</p>
  `,
})
export class OrderSummary {
  readonly order = {
    code: 'ord-0042',
    orderedAt: new Date(2026, 9, 3, 14, 5),
    total: 12800,
    count: 1200,
    discount: 0.125,
    note: '午前中の配達を希望します。不在のときは宅配ボックスへ',
    items: ['ノート', 'ペン', '付せん'],
    options: { wrapping: 'あり', receipt: 'なし' },
  };
  readonly status$ = of('発送準備中');
}

既定のロケール（en-US）で描画したテキストです。

ORD-0042
注文日: 2026/10/03(Sat) 14:05
合計: ¥12,800（1,200点）
割引率: 12.5%
メモ: 午前中の配達を希望します…
ノート
ペン
receipt
なし
wrapping
あり
状態: 発送準備中

曜日が Sat になっています。これを「土」にするには、あとで説明する ja ロケールの登録が必要です。登録後は次のように変わりました（変わった行だけ抜き出しています）。

注文日: 2026/10/03(土) 14:05
合計: ￥12,800（1,200点）

引数・連結・優先順位

三項演算子と組み合わせるときは、かっこで囲みます。 公式ドキュメントには、パイプ演算子は + - && || ?? などの二項演算子より優先順位が低く、三項演算子よりは高い、と書かれています。上の表の6行目と7行目は、そのとおりの結果になっています。

date パイプの書式と出力

定義済みの書式（en-US と ja の出力）

date の第1引数には、定義済みの名前か、書式記号の組み合わせを渡します。

定義済みの書式はロケールによって並びや区切りが変わります。 画面の表示を固定したいときは、次の書式記号で直接指定します。

書式記号の早見表

よく使う組み合わせと、その出力です。

「年」「月」「日」のような漢字は、書式の中にそのまま書いて出力できました。記号はこのほかにも、単独表記の月（L）や曜日（c）、月内の週（W）などが公式の API ドキュメントの表に載っています。なお、'B h:mm'（時間帯を表す記号）は ja では次のエラーになりました。追加のロケールデータが必要な記号です。

NG02100: InvalidPipeArgument: 'NG02303: Missing extra locale data for the locale "ja". Use "registerLocaleData" to load new data. See the "I18n guide" on angular.io to know more.' for pipe 'DatePipe'

渡せる値とタイムゾーン

最後の行のエラー文は次のとおりです。

NG02100: InvalidPipeArgument: 'NG02311: Unable to convert "abc" into a date' for pipe 'DatePipe'

タイムゾーンを省略すると、利用者の端末のタイムゾーンで表示されます。 公式の API ドキュメントにも、指定がなければ DATE_PIPE_DEFAULT_OPTIONS の値を見て、それもなければ端末のローカルのタイムゾーンを使う、と書かれています。

ja ロケールを登録して日本語の表記にする

登録前に LOCALE_ID を ja にするとエラーになる

LOCALE_ID だけを 'ja' にして date と number を使うと、次のエラーになりました。

NG02100: InvalidPipeArgument: 'NG0701: Missing locale data for the locale "ja".' for pipe 'DatePipe'
NG02100: InvalidPipeArgument: 'NG0701: Missing locale data for the locale "ja".' for pipe 'DecimalPipe'

Angular に最初から入っているロケールデータは en-US だけなので、ja のデータを registerLocaleData で登録してから LOCALE_ID を切り替えます。

app.config.ts に3行足す

// src/app/app.config.ts（ロケールに関係する部分）
import { registerLocaleData } from '@angular/common';
import localeJa from '@angular/common/locales/ja';
import { ApplicationConfig, DEFAULT_CURRENCY_CODE, LOCALE_ID, provideBrowserGlobalErrorListeners } from '@angular/core';

registerLocaleData(localeJa);

export const appConfig: ApplicationConfig = {
  providers: [
    provideBrowserGlobalErrorListeners(),
    { provide: LOCALE_ID, useValue: 'ja' },
    { provide: DEFAULT_CURRENCY_CODE, useValue: 'JPY' },
  ],
};

この設定で ng build したアプリを Chromium で開き、{{ today | date: 'fullDate' }} と {{ 1980 | currency }} の表示を読み取った結果です。

date  = 2026年10月3日土曜日 / price = ￥1,980

ロケールで変わるもの・変わらないもの

LOCALE_ID を ja にしても、currency の既定の通貨は USD のままでした。円で表示したいときは、引数で 'JPY' を渡すか、DEFAULT_CURRENCY_CODE を登録します。

そのほか、次の設定と書き方も動かして確かめました。

number・percent・currency の書式と出力

桁の指定は「整数の最小桁.小数の最小桁-小数の最大桁」

number・percent・currency の桁の指定は共通で、'1.0-2' のような文字列で渡します。

NG02100: InvalidPipeArgument: 'NG02309: abc is not a number' for pipe 'DecimalPipe'

percent

percent は値を100倍して % を付けます。すでに 25.6 のような百分率の数値を持っている場合は、number に % を自分で付けるほうが合っています。

currency

引数は「通貨コード : 表示方法 : 桁の指定」の順です。出力は en-US のものです。

「1,980円」のように後ろへ単位を付けたいときは、{{ 1980 | number }}円 と書くのが手軽です。

文字列・配列・オブジェクト用のパイプ

uppercase・lowercase・titlecase・slice

slice は JavaScript の slice() と同じ「開始位置 : 終了位置（含まない）」の指定で、負の数は末尾からの位置になります。@for (item of items | slice: 0 : 2; track item) のように、一覧の先頭だけを表示する用途でよく使います。

json（中身を確認する）

{{ obj | json }} の出力（obj = { id: 1, tags: ['x', 'y'] }）
{
  "id": 1,
  "tags": [
    "x",
    "y"
  ]
}

インデント付きで出力されるので、pre 要素の中に置くと読みやすくなります。開発中に値を確かめるためのパイプです。{{ nul | json }} は null と表示されました。

keyvalue（オブジェクトを @for で回す）

{ math: 80, art: 95, english: 70 } というオブジェクトを渡したときの並び順です。

第1引数には、配列の sort() に渡すのと同じ形の比較関数を渡せます。関数はコンポーネントのプロパティとして定義しておきます。

i18nPlural・i18nSelect（値に応じて文言を切り替える）

i18nPlural は件数に応じた文言、i18nSelect はキーに応じた文言を返します。# は数値に置き換わり、どれにも当てはまらないときは other が使われました。テンプレートに @if を並べるかわりに、文言の対応表を1つ持つだけで済みます。

async パイプで Observable と Promise を表示する

async は、Observable や Promise を購読して最新の値を返し、コンポーネントが破棄されるときに購読を自動で解除するパイプです。

import { AsyncPipe } from '@angular/common';
import { Component } from '@angular/core';
import { Subject } from 'rxjs';

@Component({ imports: [AsyncPipe], template: `<p>{{ value$ | async }}</p><p>{{ (user$ | async)?.name }}</p><p>{{ promise | async }}</p>
  @if (user$ | async; as user) { <b>{{ user.name }}</b> } @else { <b>読み込み中</b> }` })
class AsyncHost {
  value$ = new Subject<number>();
  user$ = new Subject<{ name: string }>();
  promise = new Promise<string>((r) => setTimeout(() => r('done'), 10));
}

4つの要素のテキストを、値が届く前・届いた後・Promise の解決後に出力した結果です。

値が届く前 : "" | "" | "" | "読み込み中"
next の後   : "1" | "Sato" | "" | "Sato"
Promise 解決: "1" | "Sato" | "done" | "Sato"
購読数（破棄前）= 2
購読数（破棄後）= 0

カスタムパイプの作り方

引数付きのパイプを作る

カスタムパイプは、@Pipe({ name: '...' }) を付けたクラスに transform メソッドを書くだけです。transform の第1引数が | の左側の値、第2引数以降がコロンで渡した引数になります。

// src/app/pipes/custom.pipes.ts
import { Pipe, PipeTransform } from '@angular/core';

/** 長い文字列を指定の長さで切り、末尾に記号を付ける */
@Pipe({ name: 'truncate' })
export class TruncatePipe implements PipeTransform {
  transform(value: string | null | undefined, limit = 20, suffix = '…'): string {
    if (!value) return '';
    return value.length <= limit ? value : value.slice(0, limit) + suffix;
  }
}

/** バイト数を KB / MB などに直す */
@Pipe({ name: 'fileSize' })
export class FileSizePipe implements PipeTransform {
  transform(bytes: number | null | undefined, digits = 1): string {
    if (bytes == null || Number.isNaN(bytes)) return '';
    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
    let n = bytes;
    let i = 0;
    while (n >= 1024 && i < units.length - 1) {
      n /= 1024;
      i++;
    }
    return `${i === 0 ? n : n.toFixed(digits)} ${units[i]}`;
  }
}

export const calls = { pure: 0, impure: 0 };

@Pipe({ name: 'sumPure' }) // pure: true が既定
export class SumPurePipe implements PipeTransform {
  transform(values: number[]): number {
    calls.pure++;
    return values.reduce((a, b) => a + b, 0);
  }
}

@Pipe({ name: 'sumImpure', pure: false })
export class SumImpurePipe implements PipeTransform {
  transform(values: number[]): number {
    calls.impure++;
    return values.reduce((a, b) => a + b, 0);
  }
}

後半の SumPurePipe と SumImpurePipe は、次の章で pure と impure を比べるためのものです。使う側は、組み込みパイプと同じように imports へ追加します。

（long は「Angularのパイプはテンプレートの中で値の見た目を整える仕組みです」という文字列です。）

サービスや LOCALE_ID を使うパイプ

パイプのクラスでも inject() が使えます。LOCALE_ID を受け取り、ブラウザー標準の Intl.RelativeTimeFormat で「3日前」のような表記を返す例です。

// src/app/pipes/relative.pipe.ts
import { LOCALE_ID, Pipe, PipeTransform, inject } from '@angular/core';

/** 「3日前」「2時間後」のような相対表記。LOCALE_ID を注入して使う */
@Pipe({ name: 'relativeTime' })
export class RelativeTimePipe implements PipeTransform {
  private readonly rtf = new Intl.RelativeTimeFormat(inject(LOCALE_ID), { numeric: 'auto' });

  transform(value: Date | string | number, now: Date = new Date()): string {
    const diffSec = Math.round((new Date(value).getTime() - now.getTime()) / 1000);
    const table: [Intl.RelativeTimeFormatUnit, number][] = [
      ['day', 86400],
      ['hour', 3600],
      ['minute', 60],
    ];
    for (const [unit, sec] of table) {
      if (Math.abs(diffSec) >= sec) return this.rtf.format(Math.round(diffSec / sec), unit);
    }
    return this.rtf.format(diffSec, 'second');
  }
}

3日前の日時を渡したときの出力です。

エラーになる例と直し方

imports への追加を忘れたときと、引数の型が合わないときの ng build のエラーです。

✘ [ERROR] NG8004: No pipe found with name 'truncate'. [plugin angular-compiler]
✘ [ERROR] TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. [plugin angular-compiler]
✘ [ERROR] TS2345: Argument of type 'number' is not assignable to parameter of type 'string'. [plugin angular-compiler]

transform の引数に型を付けておくと、テンプレートの書き間違いをビルドの時点で見つけられます。

テストの書き方

依存のないパイプは、new して transform を呼ぶだけで確かめられます。

// src/app/pipes/truncate.pipe.spec.ts
import { Component } from '@angular/core';
import { TestBed } from '@angular/core/testing';
import { describe, expect, it } from 'vitest';
import { FileSizePipe, TruncatePipe } from './custom.pipes';

describe('TruncatePipe', () => {
  const pipe = new TruncatePipe(); // 依存がないパイプは new するだけで試せる

  it('上限を超えたら切って記号を付ける', () => {
    expect(pipe.transform('abcdefghij', 5)).toBe('abcde…');
    expect(pipe.transform('abcdefghij', 5, '...')).toBe('abcde...');
  });

  it('上限以内ならそのまま、null は空文字', () => {
    expect(pipe.transform('abc', 5)).toBe('abc');
    expect(pipe.transform(null)).toBe('');
  });

  it('テンプレートの中で引数付きで使える', () => {
    @Component({
      imports: [TruncatePipe, FileSizePipe],
      template: `<p>{{ title | truncate: 8 : '...' }} / {{ size | fileSize: 2 }}</p>`,
    })
    class Host {
      title = 'Angular pipe guide';
      size = 5300000;
    }
    const fixture = TestBed.createComponent(Host);
    fixture.detectChanges();
    expect(fixture.nativeElement.textContent).toBe('Angular ... / 5.05 MB');
  });
});

 ✓ |demo| src/app/pipes/truncate.pipe.spec.ts > TruncatePipe > 上限を超えたら切って記号を付ける 1ms
 ✓ |demo| src/app/pipes/truncate.pipe.spec.ts > TruncatePipe > 上限以内ならそのまま、null は空文字 0ms
 ✓ |demo| src/app/pipes/truncate.pipe.spec.ts > TruncatePipe > テンプレートの中で引数付きで使える 8ms

pure と impure の違いを呼び出し回数で確かめる

pure パイプは「参照が変わったとき」だけ再計算する

パイプは既定で pure です。公式ドキュメントでは、pure パイプは、文字列や数値などの値が変わったとき、または配列やオブジェクトなどの参照が変わったときにだけ実行される、と説明されています。配列に push しても参照は同じなので、再計算されません。

前の章の SumPurePipe（pure）と SumImpurePipe（pure: false）を同じ配列に使い、transform が呼ばれた回数を数えます。

// src/app/pipes/pure-demo.spec.ts
import { ChangeDetectorRef, Component } from '@angular/core';
import { TestBed } from '@angular/core/testing';
import { expect, it } from 'vitest';
import { SumImpurePipe, SumPurePipe, calls } from './custom.pipes';

@Component({
  imports: [SumPurePipe, SumImpurePipe],
  template: `pure={{ items | sumPure }} impure={{ items | sumImpure }}`,
})
class SumHost {
  items = [1, 2, 3];
  other = 0;
}

it('pure と impure の呼び出し回数を比べる', () => {
  const fixture = TestBed.createComponent(SumHost);
  const host = fixture.componentInstance;
  const cdr = fixture.componentRef.injector.get(ChangeDetectorRef);
  const check = (label: string) => {
    cdr.markForCheck();
    fixture.detectChanges(); // 変更検知を 1 回走らせる
    console.log(`${label} | ${fixture.nativeElement.textContent} | pure=${calls.pure}回 impure=${calls.impure}回`);
  };

  calls.pure = calls.impure = 0;
  check('1. 初回表示');
  host.items.push(4);
  check('2. items.push(4)');
  host.other++;
  check('3. 無関係な値を変更');
  host.items = [...host.items, 5];
  check('4. 新しい配列に差し替え');
  check('5. 何も変えずに再チェック');

  expect(calls.pure).toBe(2);
  expect(calls.impure).toBe(5);
});

1. 初回表示 | pure=6 impure=6 | pure=1回 impure=1回
2. items.push(4) | pure=6 impure=10 | pure=1回 impure=2回
3. 無関係な値を変更 | pure=6 impure=10 | pure=1回 impure=3回
4. 新しい配列に差し替え | pure=15 impure=15 | pure=2回 impure=4回
5. 何も変えずに再チェック | pure=15 impure=15 | pure=2回 impure=5回

pure パイプは push では再計算されず、表示が 6 のまま残りました。新しい配列に差し替えた時点で 15 に更新されています。 impure パイプは変更検知が走るたびに毎回呼ばれ、配列と関係のない値を変えたときも、何も変えていないときも回数が増えています。

どちらを選ぶかの判断表

公式ドキュメントは、impure パイプは使い方によって性能への影響が大きくなるため、本当に必要な場合に限るようすすめています。まずは「配列は差し替える」を基本にすると、pure のままで済みます。

signal に入れた配列でも同じ結果でした。{{ items() | sumPure }} に対して、同じ配列へ push して返した場合と、新しい配列を返した場合の表示です。

初回 = 6
update で push（同じ配列）= 6
update で新しい配列 = 15

TypeScript の中で同じ書式を使う

テンプレートではなくクラスの中で整形したいときは、@angular/common の関数か、パイプのインスタンスを使います。ja を登録した状態での出力です。

関数はロケールを引数で渡す形、注入したパイプは LOCALE_ID に従う形です。ファイル名や CSV の中身など、テンプレートの外で文字列を組み立てる場面で使えます。

よくある質問

Q. パイプとメソッド呼び出し（{{ format(value) }}）はどう使い分けますか？ A. 表示用の変換はパイプにするのがおすすめです。pure パイプは入力が変わったときだけ transform が呼ばれることを、この記事の呼び出し回数のログで確かめました。同じ変換を複数のコンポーネントで使い回せる点も利点です。

Q. date パイプで曜日を日本語にするにはどうしますか？ A. registerLocaleData(localeJa) で ja のデータを登録し、LOCALE_ID を 'ja' にします。そのうえで {{ d | date: 'yyyy年M月d日(EEE)' }} と書くと「2026年10月3日(土)」と表示されました。登録せずに LOCALE_ID だけ変えると NG0701 のエラーになります。

Q. currency で「¥」ではなく「円」を後ろに付けたいときは？ A. currency の第2引数に文字列を渡すと、数値の前に付きます（円1,980）。後ろに付けたい場合は {{ price | number }}円 のように number と文字を組み合わせると、「1,980円」と書けます。

Q. 配列を追加したのにパイプの結果が変わりません。 A. pure パイプは配列の参照が変わったときだけ再計算します。items.push(x) のかわりに items = [...items, x] と新しい配列に差し替えると更新されます。この記事の実行結果でも、push のあとは 6 のままで、差し替えたあとに 15 へ変わりました。

まとめ

• 組み込みパイプは13種。使うものをコンポーネントの imports にクラス名で追加する。
• 引数はコロンで区切り、| で連結できる。三項演算子と組み合わせるときはかっこで囲む。
• date は定義済み書式がロケールで変わる。表示を固定したいときは 'yyyy/MM/dd HH:mm' のように書式記号で指定する。
• 日本語の曜日や月名には registerLocaleData(localeJa) と LOCALE_ID の登録が必要。 円の表示は 'JPY' か DEFAULT_CURRENCY_CODE で指定する。
• number・percent・currency の桁は '整数の最小桁.小数の最小桁-小数の最大桁' で指定する。
• カスタムパイプは @Pipe と transform だけで作れる。 引数に型と既定値を付け、null を受け取れるようにしておく。
• pure パイプは push では再計算されない。配列は新しいものに差し替える。 impure は変更検知のたびに呼ばれるので、必要な場面に絞る。

参考・出典

• Angular 公式ドキュメント「Pipes」 https://angular.dev/guide/templates/pipes
• Angular 公式 API ドキュメント「DatePipe」 https://angular.dev/api/common/DatePipe

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。