時間の差や期間を「○時間○分」「2日3時間」などの人にとって読みやすい文字列に変換したいときに便利なのが DateComponentsFormatter です。
このクラスを使うことで、秒数や時間の差分を自然な文章にフォーマットできるため、ユーザーインターフェースの改善や、ログ出力の見やすさ向上に役立ちます。
この記事では DateComponentsFormatter の基本的な使い方から、主な引数の意味、代表的な活用シーン、注意点までわかりやすく解説します！
DateComponentsFormatter とは？
DateComponentsFormatter は、時間の差（TimeInterval）や期間などを、人間が読みやすい形式の文字列に変換してくれるクラスです。
たとえば、下記のような形式にすることができます。。
- "1時間 30分"
- "2日 4時間"
- "5分"
- "3時間45分後"
秒単位の数値をユーザー向けのラベルに変換したい場面で特に便利です。
具体例：600秒を「10分」に変換する
600秒を10分に変換する例を見ていきましょう。
|
1 2 3 4 5 6 7 |
let formatter = DateComponentsFormatter() formatter.allowedUnits = [.minute] formatter.unitsStyle = .full let result = formatter.string(from: 600) print(result ?? "エラー") // "10分" |
上記例では、秒を「分」に変換し、自然な日本語に近い表記を自動で出力してくれます。
主なプロパティとその意味
DateComponentsFormatter を使いこなす上で重要なプロパティを紹介します。
| プロパティ名 | 型 | 説明 |
|---|---|---|
allowedUnits |
NSCalendar.Unit | 表示する単位（例：秒、分、時間、日など） |
unitsStyle |
UnitsStyle | 出力スタイル（.positional, .abbreviated, .fullなど） |
includesApproximationPhrase |
Bool | 「約」を含めるか（例："約2時間"） |
includesTimeRemainingPhrase |
Bool | 「あと〜」などの文言を含めるか（例："残り3分"） |
zeroFormattingBehavior |
ZeroFormattingBehavior | ゼロ値の扱い（非表示・表示） |
これらのプロパティを組み合わせて、自分の目的に合った表記スタイルを柔軟に設定できます。
よく使う出力スタイル（unitsStyle）の違い
unitsStyle の指定の仕方によって文字列のフォーマットが変わります。
|
1 2 3 4 |
formatter.unitsStyle = .positional // 例: "1:30" formatter.unitsStyle = .abbreviated // 例: "1h 30m" formatter.unitsStyle = .full // 例: "1時間 30分" |
UIやユーザー層に合わせて適切なスタイルを選びましょう。
具体例：複数の単位を使ってフォーマット
allowedUnitsは複数の単位を指定することができます。
|
1 2 3 4 5 6 7 |
let formatter = DateComponentsFormatter() formatter.allowedUnits = [.hour, .minute] formatter.unitsStyle = .full let result = formatter.string(from: 5400) // 1時間30分（5400秒） print(result ?? "") |
上記例では .hour と .minute と複数の指定をしています。
これにより、単位を跨ぐフォーマット（例：1時間30分）も簡単に実現しています。
活用シーン
DateComponentsFormatter は以下のような場面で特に有効です。
- タイマーやカウントダウンの表示
- イベントまでの残り時間（「あと5分」など）
- 経過時間の表示（「2日経過」など）
- ユーザーのアクティビティ時間の合計表示（「合計3時間45分」など）
- ログや履歴画面の「○時間前」などの記録表現
特に「時間を見せるUI」を持つアプリにおいて、ユーザーの理解を助ける重要な役割を果たします。
注意点と落とし穴
便利な DateComponentsFormatter ですが、注意すべき点もいくつかあります。
allowedUnitsを設定しないと何も表示されないunitsStyleによっては言語やロケールの影響を受ける（多言語対応では注意）nilが返ることがあるので、?? ""などで安全に扱うこと- 秒単位の誤差が生じることがあるため、ピタリ一致を期待しないこと
また、時刻ではなく「時間の長さ（差分）」を表すクラスなので、「13:45」などの時刻をフォーマットしたい場合は DateFormatter を使いましょう。
まとめ
今回は Swift の DateComponentsFormatter について詳しく紹介しました。
DateComponentsFormatterは時間の差や継続時間を人間が読みやすい文字列に変換するためのフォーマッターallowedUnits,unitsStyle,includesTimeRemainingPhraseなどで出力スタイルを柔軟にコントロール可能- タイマーUI、残り時間表示、経過時間表示など多くのアプリで活用される
- 多言語対応やゼロの扱いなどに注意しつつ、ユーザーにとって親切な時間表示が実現できる
アプリに時間表現を取り入れる際は、ぜひ DateComponentsFormatter を活用して、より直感的でわかりやすいUIを目指してみてください。
