Angular Forms - 自定義 ngModel 繫結值的方式
在 Angular 應用中,我們有兩種方式來實現表單繫結——“模板驅動表單”與“響應式表單”。這兩種方式通常能夠很好的處理大部分的情況,但是對於一些特殊的表單控制元件,例如input[type=datetime]
、input[type=file]
,我們需要重寫預設的表單繫結方式,讓我們繫結的變數不再僅僅只是一個字串,而是一個 Date
或者 File
物件。為了達成這一目的,我們需要自定義表單控制元件的 ControlValueAccessor
。
ControlValueAccessor
介面是 Angular Forms API 與 DOM 之間的橋樑,通過提供不同的 ControlValueAccessor
在我們使用 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]
@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
- 通過定義一個複合的選擇器,我們可以有選擇的對
input[type=file]
重寫ControlValueAccessor
ControlValueAccessor
的注入 token 是一個常量 ——NG_VALUE_ACCESSOR
- 由於 Directive 的定義在這行程式碼的下面,所以需要使用
forwardRef
來引用這個依賴的實現。 - 這裡需要將 multiple 設定為 true,因為 Angular 預設的
ControlValueAccessor
就是提供了多個實現的。在解析依賴的時候,Angular 會優先選擇我們自定義的實現。 - 為了程式碼更加簡單,我在這裡選擇了不利於服務端渲染的
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);
}
}
- 這裡演示了使用
Renderer2
來讀寫元素屬性的操作
整個指令的內容仍然非常簡單,但是卻能夠為我們的日常開發帶來不小的便利,使用了這個指令後,我們就可以非常容易的為 Date 物件進行雙向繫結。
<input type="datetime" valueAsDate="M/d/yyyy h:mm:ss a" [(ngModel)]="foo.date">