Angular Forms - 自定義 ngModel 綁定值的方式

在 Angular 應用中，我們有兩種方式來實現表單綁定——“模板驅動表單”與“響應式表單”。這兩種方式通常能夠很好的處理大部分的情況，但是對於一些特殊的表單控件，例如input[type=datetime]、input[type=file]，我們需要重寫默認的表單綁定方式，讓我們綁定的變量不再僅僅只是一個字符串，而是一個 Date 或者 File 對象。為了達成這一目的，我們需要自定義表單控件的 ControlValueAccessor。

ControlValueAccessor 接口是 Angular Forms API 與 DOM 之間的橋梁，通過提供不同的 ControlValueAccessor，我們就可以使用統一的 Angular Forms API 來操作不同的 HTML 表單元素。

在我們使用 ngModel 或者 formControl 的時候，這兩個 Directive 會向 Angular 的依賴注入容器申請實現了 ControlValueAccessor 接口的對象，這是一種典型的面向接口編程的設計。例如，如果我們需要為 input[type=file] 提供一個用來綁定 File 對象的 ControlValueAccessor，只需要在依賴注入容器中提供一個 FileControlValueAccessor 的實現就可以了。不過，我們並不想覆蓋其他類型 input 元素的 ControlValueAccessor，因為那樣肯定會對已有代碼造成大范圍的破壞。所以在這里，我們需要使用 Angular 的分層注入能力——在 ElementInjector 中提供 FileControlValueAccessor。關於 ElementInjector 更多的內容，請看這里 a-curios-case-of-the-host-decorator-and-element-injectors-in-angular。

下面演示的兩個 Directive 您都可以在這里查看在線演示。

首先讓我們來創建一個 Directive，這個指令將會選中 input[type=file][appInputFile] 元素，這樣我們就可以有選擇的為文件選擇器的 ElementInjector 定義新的 Provider。

@Directive({
    selector: 'input[type=file][inputFile]',		// <1>
    providers: [
        {
            provide: NG_VALUE_ACCESSOR,							// <2>
            useExisting: forwardRef(() => InputFileDirective),	// <3>
            multi: true		// <4>
        }
    ]
})
export class InputFileDirective implements ControlValueAccessor, OnInit, OnDestroy {
	// 當文件選擇器選擇的文件發生改變時調用的回調函數
    onChange: (any) => any;
    // 當文件選擇器選擇的被操作后調用的回調函數
    onTouched: () => any;

	// 監聽宿主元素的 change 事件
    @HostListener('change', ['$event.target.files']) onElChange = (files: FileList) => {
    	this.onChange(files);
    };

	// 監聽宿主元素的 blur 事件
    @HostListener('blur', []) onElTouched = () => {
    	this.onTouched();
    };

    constructor(private el: ElementRef<HTMLInputElement>) {		// <5>
    }
    ngOnInit(): void {
        this.el.nativeElement.addEventListener('change', this.listener);
    }

	// 來自 ControlValueAccessor 接口，用來設置元素的值
    writeValue(obj: any): void {
        this.el.nativeElement.value = obj;
    }
    // 來自 ControlValueAccessor 接口，用來將一個函數注冊為 onChange 回調函數
    registerOnChange(fn: any): void {
        this.onChange = fn;
    }
    // 來自 ControlValueAccessor 接口，用來將一個函數注冊為 onTouched 回調函數
    registerOnTouched(fn: any): void {
        this.onTouched = fn;
    }
    // 來自 ControlValueAccessor 接口，設置表單元素是否啟用
    setDisabledState?(isDisabled: boolean): void {
        this.el.nativeElement.disabled = isDisabled;
    }

}

上面的代碼片段中你可以看到有幾處類似 // <1> 的注釋，這是我用來在下面的文章中引用該行代碼的標記，語法借鑒自 ASCIIDoc

1. 通過定義一個復合的選擇器，我們可以有選擇的對 input[type=file] 重寫 ControlValueAccessor
2. ControlValueAccessor 的注入 token 是一個常量 —— NG_VALUE_ACCESSOR
3. 由於 Directive 的定義在這行代碼的下面，所以需要使用 forwardRef 來引用這個依賴的實現。
4. 這里需要將 multiple 設置為 true，因為 Angular 默認的 ControlValueAccessor 就是提供了多個實現的。在解析依賴的時候，Angular 會優先選擇我們自定義的實現。
5. 為了代碼更加簡單，我在這里選擇了不利於服務端渲染的 ElementRef.nativeElement 來讀取原生 HTML 元素的屬性，如果你對服務端渲染有需求，你應該使用 Renderer2 來讀寫元素的屬性。

有了這個 Directive，我們就可以在 Angular Forms 中綁定 File 對象了：

<input type="file" [(ngModel)]="foo.files" inputFile />

Date 類型的數據也是日常開發中比較頭疼的一個地方，因為在 JSON 中，Date 類型往往會被序列化為字符串，而在前端代碼中，我們又需要將其反序列化為 Date 對象，最終在頁面上展示的時候，我們又需要按照產品需求再將其序列化為制定格式的字符串。現在，有了 ControlValueAccessor 的幫助，我們就可以實現讓 input[type=datetime] 與 Date 對象進行雙向綁定的功能，同時還能夠定制 Date 對象在輸入框中的顯示格式。

@Directive({
    // tslint:disable-next-line:directive-selector
    selector: 'input[type=datetime][valueAsDate]',
    providers: [
        {
            provide: NG_VALUE_ACCESSOR,
            useExisting: forwardRef(() => DateValueDirective),
            multi: true
        }
    ]
})
export class DateValueDirective implements ControlValueAccessor {

    /**
     * See https://date-fns.org/v2.0.0-alpha.25/docs/format
     * 自定義日期展示格式
     * @type {string}
     * @memberof DateValueDirective
     */
    // tslint:disable-next-line:no-input-rename
    @Input('valueAsDate') format: string;

    private dateValue: Date;

    @HostListener('input', ['$event.target.value']) onChange = (_: any) => { };

    @HostListener('blur', []) onTouched = () => { };

    get element() { return this.elementRef.nativeElement; }

    constructor(
        private elementRef: ElementRef,
        private renderer: Renderer2		// <1>
    ) { }

    parseDate(str: string) {
        return parseDate(str, this.format, new Date(), { awareOfUnicodeTokens: true });
    }

    formatDate(date: Date) {
        return formatDate(date, this.format, { awareOfUnicodeTokens: true });
    }

	/**
     * 設置組件的值的時候，先把新的值存到一個成員變量中，然后再把新的值格式化為 string
     */
    writeValue(date: Date): void {
        this.dateValue = date;
        this.renderer.setProperty(this.element, 'value', this.formatDate(date));
    }

	/**
     * 在 input 元素值發生變化的時候，先嘗試把變化后的值轉換成 Date 對象
     * 如果轉換失敗，那么依然使用之前的值
     * 否則，將新的值傳遞給回調函數
     */
    registerOnChange(fn: any): void {
        const onChange = (value: string) => {
            const date = this.parseDate(value);
            if (isValidDate(date)) {
                this.dateValue = date;
                fn(date);
            } else {
                fn(this.dateValue);
            }
        };
        this.onChange = onChange;
    }
    registerOnTouched(fn: any): void {
        this.onTouched = fn;
    }
    setDisabledState?(isDisabled: boolean): void {
        this.renderer.setProperty(this.element, 'disabled', isDisabled);
    }
}

1. 這里演示了使用 Renderer2 來讀寫元素屬性的操作

整個指令的內容仍然非常簡單，但是卻能夠為我們的日常開發帶來不小的便利，使用了這個指令后，我們就可以非常容易的為 Date 對象進行雙向綁定。

<input type="datetime" valueAsDate="M/d/yyyy h:mm:ss a" [(ngModel)]="foo.date">