Formatter — その概要、入力フォーマッタ、およびNSFormatter

iOSのFormatterとは？

Formatter はiOSのコンポーネントで、指定されたパターンに従って生のユーザー入力を構造化された形式に変換します。フォーム送信後の単純な検証とは異なり、フォーマッタはリアルタイムで動作し、入力されると同時にデータ表示を修正します。これが重要な違いです。ユーザーは手動で区切り文字を入力することなく、すぐにフォーマットされた結果を確認できます。

iOSにはいくつかのフォーマットレベルがあります：データ表示用のシステムFoundationフォーマッタ（NumberFormatter、DateFormatter、ByteCountFormatter）、電話番号用のPhoneNumberKitフレームワーク、カスタム入力マスク用のサードパーティInputMaskライブラリです。レベルの選択は、データの種類と必要なフォーマットの柔軟性によって異なります。

Apple Human Interface Guidelinesによると、入力フォーマッタは3つのタスクを解決します：ユーザーの認知的負荷の軽減（区切り文字について考える必要がない）、エラー数の削減（データが正しい形式で入力される）、フォーム入力の高速化（数字グループ間の自動遷移）。

フォーマッタは特にモバイルデバイスで重要です。画面上のキーボードでの入力は物理キーボードよりも多くの労力を要するからです。手動で入力しなければならない余分な文字はすべて、フォーム入力時間とエラーのリスクを増加させます。区切り文字の自動挿入により、一般的な形式ではタップ数が20～40%削減されます。

入力フォーマッタの種類

iOSの入力フォーマッタは3つのカテゴリに分類されます：システムFoundationフォーマッタ、Appleの専用フォーマッタ（PhoneNumberKit）、サードパーティライブラリ（InputMask、MaskedTextField）です。各カテゴリは独自のタスクを解決し、実装の特徴があります。

システムFoundationフォーマッタ

NumberFormatterは数値をフォーマットします：金額、パーセンテージ、科学的表記。グループ区切りと小数点のローカライズをサポートします。DateFormatterは日付と時刻をローカライズされた文字列に変換します。これらのフォーマッタは表示用に設計されており、入力マスキング用ではないため、入力中にUITextFieldに直接適用するのは困難です。

PhoneNumberKit

PhoneNumberKitは、国の標準に従って電話番号をフォーマットするAppleのライブラリです。コードによって自動的に国を検出し、対応する形式を適用します。例えば、ロシアの番号+7 912 345-67-89は、アメリカの番号+1 212-555-0198とは異なる形式になります。PhoneNumberKitは番号の正当性も検証します。

Input Maskライブラリ

サードパーティライブラリ InputMaskは、あらゆる形式に対応するユニバーサルな入力マスキングメカニズムを提供します：カード番号（0000 0000 0000 0000）、日付（DD.MM.YYYY）、SNILS（000-000-000 00）、INN（000000000000）。ライブラリはUITextFieldDelegateを通じて動作し、入力をインターセプトしてリアルタイムでマスクを適用します。

抽象クラスNSFormatter

NSFormatterはFoundationの抽象クラスで、すべてのシステムiOSフォーマッタが継承しています。2つの主要メソッドを定義します：オブジェクトを文字列に変換するstring(for:)と、文字列からオブジェクトに逆変換するgetObjectValue(_:for:errorDescription:)です。この双方向メカニズムにより、データの表示とテキストフィールドからの読み取りの両方が可能になります。

システムクラスでカバーされていない特定の形式については、NSFormatterに基づくカスタムフォーマッタを作成することが可能です。そのためには、string(for:)とgetObjectValue(_:for:errorDescription:)メソッドをオーバーライドする必要があります。カスタムフォーマッタは、formatterプロパティを介してUILabel、UITextField、その他のビューで使用できます。

Appleはカスタムフォーマッタを作成する代わりに、既存のFoundationフォーマッタを使用することを推奨しています。NumberFormatterは32の言語と地域標準を正しく処理し、DateFormatterは異なる文化のカレンダーを考慮し、ByteCountFormatterは値のサイズに応じてバイト、キロバイト、メガバイトを自動的に切り替えます。

NSFormatterは不正な入力に対するエラーメッセージのローカライズもサポートしています。getObjectValueメソッドはエラーの説明を返し、ローカライズされた形でユーザーに表示できます。これは特に、ユーザーが誤った形式でデータを入力するフォームで重要です。エラーメッセージは理解しやすく、インターフェースの言語である必要があります。

Input Maskと入力マスキング

Input Mask（入力マスク）は、入力データの形式を定義し、入力に応じて自動的に区切り文字を挿入するテンプレートです。マスクはプレースホルダ文字（通常、数字は0または9、文字はA）と、自動的に挿入される定数文字（括弧、ハイフン、スペース）で構成されます。ユーザーは意味のある文字のみを入力し、区切り文字はシステムによって挿入されます。

iOSで最も人気のあるライブラリはRedMadRobotのInputMaskです。条件、オプションブロック、接辞（プレフィックスとサフィックス）を持つ複雑なマスクをサポートしています。ライブラリはデリゲートを介して実装されているため、サブクラス化なしで任意のUITextFieldで使用できます。電話番号、銀行カード、日付、確認コード、その他の構造化データのマスクがサポートされています。

InputMask形式は独自の構文を使用します：必須文字には角括弧、オプション文字には波括弧、括弧の外側には定数文字。例えば、カード番号マスクは[0000] [0000] [0000] [0000]、日付マスクは[00]{.}[00]{.}[0000]のようになります。波括弧内のオプションブロックは、ユーザーがデータを入力しないと消えます。

電話番号の場合、マスクには通常、接辞に国コードが含まれます：+7 ([000]) [000]-[00]-[00]。ユーザーは番号の10桁のみを入力し、+7、(、)、-の文字は自動的に挿入されます。文字を削除する際、マスクはバックスペースを正しく処理し、最後の有意味文字を削除して前の位置に戻ります。

電話番号のフォーマット

電話番号のフォーマットは、モバイルアプリケーションにおけるフォーマッタの最も一般的な使用例です。iOSはこの目的のためにPhoneNumberKitフレームワークを提供しており、コードによって自動的に国を特定し、対応する国内形式を適用します。このライブラリは200以上の国をサポートし、定期的に更新されています。

PhoneNumberKitは2段階で動作します：形式の検出とその適用です。最初の段階では、ライブラリは入力された国コード（例えば+7はロシアを特定）を分析し、フォーマットルールをロードします。第二段階では、国内標準に対応するマスクを適用します：ロシアの場合は+7 XXX XXX-XX-XX、米国の場合は+1 XXX-XXX-XXXX、英国の場合は+44 XXXX XXX XXXです。

Apple Developer Documentationによると、iOS 16以降、UIContentUnavailableConfigurationを介した電話番号フォーマットの組み込みメカニズムが導入されました。ただし、完全なリアルタイムフォーマットには、UITextFieldDelegateを介したPhoneNumberKitの使用が推奨されます。ライブラリは番号の検証も行います：桁数、国コードの有効性、国内形式への準拠をチェックします。

国際的なアプリケーションでは、ユーザーが+7、8（ロシアの場合）、または国コードなしで番号を入力する可能性があることを考慮することが重要です。優れたフォーマッタは、任意の初期形式を認識し、+プレフィックスと国コードを含む単一の国際標準に正規化する必要があります。

Swiftでのフォーマッタ実装

Swiftでのフォーマッタ実装は、選択したアプローチによって異なります。システムFoundationフォーマッタの場合は、iOS 15以降でUITextFieldで利用可能なformatterプロパティを使用します。Input Maskの場合は、InputMaskライブラリとともにUITextFieldDelegateを使用します。電話番号の場合は、デリゲートを介したPhoneNumberKitを使用します。

import PhoneNumberKit

class PhoneViewController: UIViewController {

    let phoneNumberKit = PhoneNumberKit()
    @IBOutlet var phoneField: UITextField!

    override func viewDidLoad() {
        super.viewDidLoad()
        phoneField.delegate = self
    }
}

extension PhoneViewController: UITextFieldDelegate {
    func textField(
        _ textField: UITextField,
        shouldChangeCharactersIn range: NSRange,
        replacementString string: String
    ) -> Bool {
        guard let text = textField.text else { return true }
        let partial = (text as NSString).replacingCharacters(in: range, with: string)
        textField.text = partial.applyPhoneMask()
        return false
    }
}

NumberFormatterの場合、iOS 15+ではUITextFieldにformatterプロパティが利用可能で、入力された数値を入力中に自動的にフォーマットします。このアプローチではデリゲートの実装は不要で、ユーザーのロケールを考慮して、通貨形式、パーセンテージ、その他の数値データに対してすぐに機能します。

let amountField = UITextField()
let formatter = NumberFormatter()
formatter.numberStyle = .currency
formatter.locale = Locale(identifier: "ru_RU")
amountField.formatter = formatter

RedMadRobotのInputMaskライブラリの場合、セットアップはマスクの初期化とデリゲートを介した適用によって行われます。ライブラリはペースト処理、バックスペース削除をサポートし、テキスト選択で正しく動作します。

import InputMask

class CardViewController: UIViewController {
    @IBOutlet var cardField: UITextField!
    var listener: MaskedTextFieldDelegate!

    override func viewDidLoad() {
        super.viewDidLoad()
        listener = MaskedTextFieldDelegate(
            primaryMaskFormat: "[0000] [0000] [0000] [0000]"
        )
        cardField.delegate = listener
    }
}