從伺服器端獲取資料link

Get data from a serverlink

在這節課中，你將藉助 Angular 的 HttpClient 來新增一些資料持久化特性。

In this tutorial, you'll add the following data persistence features with help from Angular's HttpClient.

• HeroService 透過 HTTP 請求獲取英雄資料。

  The HeroService gets hero data with HTTP requests.

• 使用者可以新增、編輯和刪除英雄，並透過 HTTP 來儲存這些更改。

  Users can add, edit, and delete heroes and save these changes over HTTP.

• 使用者可以根據名字搜尋英雄。

  Users can search for heroes by name.

啟用 HTTP 服務link

Enable HTTP serviceslink

HttpClient 是 Angular 透過 HTTP 與遠端伺服器通訊的機制。

HttpClient is Angular's mechanism for communicating with a remote server over HTTP.

要讓 HttpClient 在應用中隨處可用，需要兩個步驟。首先，用匯入語句把它新增到根模組 AppModule 中：

Make HttpClient available everywhere in the app in two steps. First, add it to the root AppModule by importing it:

      
        content_copy
      
      import { HttpClientModule } from '@angular/common/http';
    

接下來，仍然在 AppModule 中，把 HttpClientModule 新增到 imports 陣列中：

Next, still in the AppModule, add HttpClient to the imports array:

      
        content_copy
      
      @NgModule({
  imports: [
    HttpClientModule,
  ],
})
    

模擬資料伺服器link

Simulate a data serverlink

這個教學例子會與一個使用 記憶體 Web API（In-memory Web API） 模擬出的遠端資料伺服器通訊。

This tutorial sample mimics communication with a remote data server by using the In-memory Web API module.

安裝完這個模組之後，應用將會透過 HttpClient 來發起請求和接收響應，而不用在乎實際上是這個記憶體 Web API 在攔截這些請求、操作一個記憶體資料庫，並且給出模擬的響應。

After installing the module, the app will make requests to and receive responses from the HttpClient without knowing that the In-memory Web API is intercepting those requests, applying them to an in-memory data store, and returning simulated responses.

透過使用記憶體 Web API，你不用架設伺服器就可以學習 HttpClient 了。

By using the In-memory Web API, you won't have to set up a server to learn about HttpClient.

用如下命令從 npm 中安裝這個記憶體 Web API 包（譯註：請使用 0.5+ 的版本，不要使用 0.4-）

Install the In-memory Web API package from npm with the following command:

      
        content_copy
      
      npm install angular-in-memory-web-api --save
    

在 AppModule 中，匯入 HttpClientInMemoryWebApiModule 和 InMemoryDataService 類別，稍後你將建立它們。

In the AppModule, import the HttpClientInMemoryWebApiModule and the InMemoryDataService class, which you will create in a moment.

      
        content_copy
      
      import { HttpClientInMemoryWebApiModule } from 'angular-in-memory-web-api';
import { InMemoryDataService } from './in-memory-data.service';
    

在 HttpClientModule 之後，將 HttpClientInMemoryWebApiModule 新增到 AppModule 的 imports 陣列中，並以 InMemoryDataService 為引數對其進行配置。

After the HttpClientModule, add the HttpClientInMemoryWebApiModule to the AppModule imports array and configure it with the InMemoryDataService.

      
        content_copy
      
      HttpClientModule,

// The HttpClientInMemoryWebApiModule module intercepts HTTP requests
// and returns simulated server responses.
// Remove it when a real server is ready to receive requests.
HttpClientInMemoryWebApiModule.forRoot(
  InMemoryDataService, { dataEncapsulation: false }
)
    

forRoot() 配置方法接收一個 InMemoryDataService 類別來初始化記憶體資料庫。

The forRoot() configuration method takes an InMemoryDataService class that primes the in-memory database.

使用以下命令產生類別 src/app/in-memory-data.service.ts：

Generate the class src/app/in-memory-data.service.ts with the following command:

      
        content_copy
      
      ng generate service InMemoryData
    

將 in-memory-data.service.ts 改為以下內容：

Replace the default contents of in-memory-data.service.ts with the following:

      
        content_copy
      
      import { Injectable } from '@angular/core';
import { InMemoryDbService } from 'angular-in-memory-web-api';
import { Hero } from './hero';

@Injectable({
  providedIn: 'root',
})
export class InMemoryDataService implements InMemoryDbService {
  createDb() {
    const heroes = [
      { id: 11, name: 'Dr Nice' },
      { id: 12, name: 'Narco' },
      { id: 13, name: 'Bombasto' },
      { id: 14, name: 'Celeritas' },
      { id: 15, name: 'Magneta' },
      { id: 16, name: 'RubberMan' },
      { id: 17, name: 'Dynama' },
      { id: 18, name: 'Dr IQ' },
      { id: 19, name: 'Magma' },
      { id: 20, name: 'Tornado' }
    ];
    return {heroes};
  }

  // Overrides the genId method to ensure that a hero always has an id.
  // If the heroes array is empty,
  // the method below returns the initial number (11).
  // if the heroes array is not empty, the method below returns the highest
  // hero id + 1.
  genId(heroes: Hero[]): number {
    return heroes.length > 0 ? Math.max(...heroes.map(hero => hero.id)) + 1 : 11;
  }
}
    

in-memory-data.service.ts 檔案已代替了 mock-heroes.ts 檔案，現在後者可以安全的刪除了。

The in-memory-data.service.ts file will take over the function of mock-heroes.ts. However, don't delete mock-heroes.ts yet, as you still need it for a few more steps of this tutorial.

等伺服器就緒後，你就可以拋棄這個記憶體 Web API，應用的請求將直接傳給伺服器。

When the server is ready, you'll detach the In-memory Web API, and the app's requests will go through to the server.

英雄與 HTTPlink

Heroes and HTTPlink

在 HeroService 中，匯入 HttpClient 和 HttpHeaders：

In the HeroService, import HttpClient and HttpHeaders:

      
        content_copy
      
      import { HttpClient, HttpHeaders } from '@angular/common/http';
    

仍然在 HeroService 中，把 HttpClient 注入到建構函式中一個名叫 http 的私有屬性中。

Still in the HeroService, inject HttpClient into the constructor in a private property called http.

      
        content_copy
      
      constructor(
  private http: HttpClient,
  private messageService: MessageService) { }
    

注意保留對 MessageService 的注入，但是因為你將頻繁呼叫它，因此請把它包裹進一個私有的 log 方法中。

Notice that you keep injecting the MessageService but since you'll call it so frequently, wrap it in a private log() method:

      
        content_copy
      
      /** Log a HeroService message with the MessageService */
private log(message: string) {
  this.messageService.add(`HeroService: ${message}`);
}
    

把伺服器上英雄資料資源的訪問地址 heroesURL 定義為 :base/:collectionName 的形式。 這裡的 base 是要請求的資源，而 collectionName 是 in-memory-data-service.ts 中的英雄資料物件。

Define the heroesUrl of the form :base/:collectionName with the address of the heroes resource on the server. Here base is the resource to which requests are made, and collectionName is the heroes data object in the in-memory-data-service.ts.

      
        content_copy
      
      private heroesUrl = 'api/heroes';  // URL to web api
    

透過 HttpClient 獲取英雄link

Get heroes with HttpClientlink

當前的 HeroService.getHeroes() 使用 RxJS 的 of() 函式來把模擬英雄資料返回為 Observable<Hero[]> 格式。

The current HeroService.getHeroes() uses the RxJS of() function to return an array of mock heroes as an Observable<Hero[]>.

      
        content_copy
      
      getHeroes(): Observable<Hero[]> {
  return of(HEROES);
}
    

把該方法轉換成使用 HttpClient 的，程式碼如下：

Convert that method to use HttpClient as follows:

      
        content_copy
      
      /** GET heroes from the server */
getHeroes(): Observable<Hero[]> {
  return this.http.get<Hero[]>(this.heroesUrl)
}
    

重新整理瀏覽器後，英雄資料就會從模擬伺服器被成功讀取。

Refresh the browser. The hero data should successfully load from the mock server.

你用 http.get() 替換了 of()，沒有做其它修改，但是應用仍然在正常工作，這是因為這兩個函式都返回了 Observable<Hero[]>。

You've swapped of() for http.get() and the app keeps working without any other changes because both functions return an Observable<Hero[]>.

HttpClient 的方法返回單個值link

HttpClient methods return one valuelink

所有的 HttpClient 方法都會返回某個值的 RxJS Observable。

All HttpClient methods return an RxJS Observable of something.

HTTP 是一個請求/響應式協議。你發起請求，它返回單個的響應。

HTTP is a request/response protocol. You make a request, it returns a single response.

通常，Observable 可以在一段時間內返回多個值。 但來自 HttpClient 的 Observable 總是發出一個值，然後結束，再也不會發出其它值。

In general, an observable can return multiple values over time. An observable from HttpClient always emits a single value and then completes, never to emit again.

具體到這次 HttpClient.get() 呼叫，它返回一個 Observable<Hero[]>，也就是“一個英雄陣列的可觀察物件”。在實踐中，它也只會返回一個英雄陣列。

This particular HttpClient.get() call returns an Observable<Hero[]>; that is, "an observable of hero arrays". In practice, it will only return a single hero array.

HttpClient.get() 返回響應資料link

HttpClient.get() returns response datalink

HttpClient.get() 預設情況下把回應內文當做無型別的 JSON 物件進行返回。 如果指定了可選的範本型別 <Hero[]>，就會給返回你一個型別化的物件。

HttpClient.get() returns the body of the response as an untyped JSON object by default. Applying the optional type specifier, <Hero[]> , adds TypeScript capabilities, which reduce errors during compile time.

伺服器的資料 API 決定了 JSON 資料的具體形態。 英雄之旅的資料 API 會把英雄資料作為一個數組進行返回。

The server's data API determines the shape of the JSON data. The Tour of Heroes data API returns the hero data as an array.

錯誤處理link

Error handlinglink

凡事皆會出錯，特別是當你從遠端伺服器獲取資料的時候。 HeroService.getHeroes() 方法應該捕獲錯誤，並做適當的處理。

Things go wrong, especially when you're getting data from a remote server. The HeroService.getHeroes() method should catch errors and do something appropriate.

要捕獲錯誤，你就要使用 RxJS 的 catchError() 運算子來建立對 Observable 結果的處理管道（pipe）。

To catch errors, you "pipe" the observable result from http.get() through an RxJS catchError() operator.

從 rxjs/operators 中匯入 catchError 符號，以及你稍後將會用到的其它運算子。

Import the catchError symbol from rxjs/operators, along with some other operators you'll need later.

      
        content_copy
      
      import { catchError, map, tap } from 'rxjs/operators';
    

現在，使用 pipe() 方法來擴充套件 Observable 的結果，並給它一個 catchError() 運算子。

Now extend the observable result with the pipe() method and give it a catchError() operator.

      
        content_copy
      
      getHeroes(): Observable<Hero[]> {
  return this.http.get<Hero[]>(this.heroesUrl)
    .pipe(
      catchError(this.handleError<Hero[]>('getHeroes', []))
    );
}
    

catchError() 運算子會攔截失敗的 Observable。 它把錯誤物件傳給錯誤處理器，錯誤處理器會處理這個錯誤。

The catchError() operator intercepts an Observable that failed. The operator then passes the error to the error handling function.

下面的 handleError() 方法會報告這個錯誤，並返回一個無害的結果（安全值），以便應用能正常工作。

The following handleError() method reports the error and then returns an innocuous result so that the application keeps working.

handleErrorlink

下面這個 handleError() 將會在很多 HeroService 的方法之間共享，所以要把它通用化，以支援這些彼此不同的需求。

The following handleError() will be shared by many HeroService methods so it's generalized to meet their different needs.

它不再直接處理這些錯誤，而是返回給 catchError 返回一個錯誤處理函式。還要用操作名和出錯時要返回的安全值來對這個錯誤處理函式進行配置。

Instead of handling the error directly, it returns an error handler function to catchError that it has configured with both the name of the operation that failed and a safe return value.

      
        content_copy
      
      /**
 * Handle Http operation that failed.
 * Let the app continue.
 * @param operation - name of the operation that failed
 * @param result - optional value to return as the observable result
 */
private handleError<T>(operation = 'operation', result?: T) {
  return (error: any): Observable<T> => {

    // TODO: send the error to remote logging infrastructure
    console.error(error); // log to console instead

    // TODO: better job of transforming error for user consumption
    this.log(`${operation} failed: ${error.message}`);

    // Let the app keep running by returning an empty result.
    return of(result as T);
  };
}
    

在控制檯中彙報了這個錯誤之後，這個處理器會彙報一個使用者友好的訊息，並給應用返回一個安全值，讓應用繼續工作。

After reporting the error to the console, the handler constructs a user friendly message and returns a safe value to the app so the app can keep working.

因為每個服務方法都會返回不同型別的 Observable 結果，因此 handleError() 也需要一個型別引數，以便它返回一個此型別的安全值，正如應用所期望的那樣。

Because each service method returns a different kind of Observable result, handleError() takes a type parameter so it can return the safe value as the type that the app expects.

窺探 Observablelink

Tap into the Observablelink

HeroService 的方法將會窺探 Observable 的資料流，並透過 log() 方法往頁面底部發送一條訊息。

The HeroService methods will tap into the flow of observable values and send a message, via the log() method, to the message area at the bottom of the page.

它們可以使用 RxJS 的 tap() 運算子來實現，該運算子會檢視 Observable 中的值，使用那些值做一些事情，並且把它們傳出來。 這種 tap() 回呼(Callback)不會改變這些值本身。

They'll do that with the RxJS tap() operator, which looks at the observable values, does something with those values, and passes them along. The tap() call back doesn't touch the values themselves.

下面是 getHeroes() 的最終版本，它使用 tap() 來記錄各種操作。

Here is the final version of getHeroes() with the tap() that logs the operation.

      
        content_copy
      
      /** GET heroes from the server */
getHeroes(): Observable<Hero[]> {
  return this.http.get<Hero[]>(this.heroesUrl)
    .pipe(
      tap(_ => this.log('fetched heroes')),
      catchError(this.handleError<Hero[]>('getHeroes', []))
    );
}
    

透過 id 獲取英雄link

Get hero by idlink

大多數的 Web API 都支援以 :baseURL/:id 的形式根據 id 進行獲取。

Most web APIs support a get by id request in the form :baseURL/:id.

這裡的 baseURL 就是在 英雄列表與 HTTP 部分定義過的 heroesURL（api/heroes）。而 id 則是你要獲取的英雄的編號，比如，api/heroes/11。 把 HeroService.getHero() 方法改成這樣，以發起該請求：

Here, the base URL is the heroesURL defined in the Heroes and HTTP section (api/heroes) and id is the number of the hero that you want to retrieve. For example, api/heroes/11. Update the HeroService getHero() method with the following to make that request:

      
        content_copy
      
      /** GET hero by id. Will 404 if id not found */
getHero(id: number): Observable<Hero> {
  const url = `${this.heroesUrl}/${id}`;
  return this.http.get<Hero>(url).pipe(
    tap(_ => this.log(`fetched hero id=${id}`)),
    catchError(this.handleError<Hero>(`getHero id=${id}`))
  );
}
    

這裡和 getHeroes() 相比有三個顯著的差異:

There are three significant differences from getHeroes():

• getHero() 使用想獲取的英雄的 id 構造了一個請求 URL。

  getHero() constructs a request URL with the desired hero's id.

• 伺服器應該使用單個英雄作為迴應，而不是一個英雄陣列。

  The server should respond with a single hero rather than an array of heroes.

• 所以，getHero() 會返回 Observable<Hero>（“一個可觀察的單個英雄物件”），而不是一個可觀察的英雄物件陣列。

  getHero() returns an Observable<Hero> ("an observable of Hero objects") rather than an observable of hero arrays .

修改英雄link

Update heroeslink

在英雄詳情檢視中編輯英雄的名字。 隨著輸入，英雄的名字也跟著在頁面頂部的標題區更新了。 但是當你點選“後退”按鈕時，這些修改都丟失了。

Edit a hero's name in the hero detail view. As you type, the hero name updates the heading at the top of the page. But when you click the "go back button", the changes are lost.

如果你希望保留這些修改，就要把它們寫回到伺服器。

If you want changes to persist, you must write them back to the server.

在英雄詳情範本的底部新增一個儲存按鈕，它綁定了一個 click 事件，事件繫結會呼叫元件中一個名叫 save() 的新方法：

At the end of the hero detail template, add a save button with a click event binding that invokes a new component method named save().

      
        content_copy
      
      <button (click)="save()">save</button>
    

在 HeroDetail 元件類別中，新增如下的 save() 方法，它使用英雄服務中的 updateHero() 方法來儲存對英雄名字的修改，然後導航回前一個檢視。

In the HeroDetail component class, add the following save() method, which persists hero name changes using the hero service updateHero() method and then navigates back to the previous view.

      
        content_copy
      
      save(): void {
  this.heroService.updateHero(this.hero)
    .subscribe(() => this.goBack());
}
    

新增 HeroService.updateHero()link

Add HeroService.updateHero()link

updateHero() 的總體結構和 getHeroes() 很相似，但它會使用 http.put() 來把修改後的英雄儲存到伺服器上。 把下列程式碼新增進 HeroService。

The overall structure of the updateHero() method is similar to that of getHeroes(), but it uses http.put() to persist the changed hero on the server. Add the following to the HeroService.

      
        content_copy
      
      /** PUT: update the hero on the server */
updateHero(hero: Hero): Observable<any> {
  return this.http.put(this.heroesUrl, hero, this.httpOptions).pipe(
    tap(_ => this.log(`updated hero id=${hero.id}`)),
    catchError(this.handleError<any>('updateHero'))
  );
}
    

HttpClient.put() 方法接受三個引數：

The HttpClient.put() method takes three parameters:

• URL 地址

  the URL

• 要修改的資料（這裡就是修改後的英雄）

  the data to update (the modified hero in this case)

• 選項

  options

URL 沒變。英雄 Web API 透過英雄物件的 id 就可以知道要修改哪個英雄。

The URL is unchanged. The heroes web API knows which hero to update by looking at the hero's id.

英雄 Web API 期待在儲存時的請求中有一個特殊的頭。 這個頭是在 HeroService 的 httpOptions 常量中定義的。

The heroes web API expects a special header in HTTP save requests. That header is in the httpOptions constant defined in the HeroService. Add the following to the HeroService class.

      
        content_copy
      
      httpOptions = {
  headers: new HttpHeaders({ 'Content-Type': 'application/json' })
};
    

重新整理瀏覽器，修改英雄名，儲存這些修改。在 HeroDetailComponent 的 save() 方法中導航到前一個檢視。 現在，改名後的英雄已經顯示在列表中了。

Refresh the browser, change a hero name and save your change. The save() method in HeroDetailComponent navigates to the previous view. The hero now appears in the list with the changed name.

新增新英雄link

Add a new herolink

要新增英雄，本應用中只需要英雄的名字。你可以使用一個和新增按鈕成對的 <input> 元素。

To add a hero, this app only needs the hero's name. You can use an <input> element paired with an add button.

把下列程式碼插入到 HeroesComponent 範本中標題的緊後面：

Insert the following into the HeroesComponent template, just after the heading:

      
        content_copy
      
      <div>
  <label>Hero name:
    <input #heroName />
  </label>
  <!-- (click) passes input value to add() and then clears the input -->
  <button (click)="add(heroName.value); heroName.value=''">
    add
  </button>
</div>
    

當點選事件觸發時，呼叫元件的點選處理器（add()），然後清空這個輸入框，以便用來輸入另一個名字。把下列程式碼新增到 HeroesComponent 類別：

In response to a click event, call the component's click handler, add(), and then clear the input field so that it's ready for another name. Add the following to the HeroesComponent class:

      
        content_copy
      
      add(name: string): void {
  name = name.trim();
  if (!name) { return; }
  this.heroService.addHero({ name } as Hero)
    .subscribe(hero => {
      this.heroes.push(hero);
    });
}
    

當指定的名字非空時，這個處理器會用這個名字建立一個類似於 Hero 的物件（只缺少 id 屬性），並把它傳給服務的 addHero() 方法。

When the given name is non-blank, the handler creates a Hero-like object from the name (it's only missing the id) and passes it to the services addHero() method.

當 addHero() 儲存成功時，subscribe() 的回呼(Callback)函式會收到這個新英雄，並把它追加到 heroes 列表中以供顯示。

When addHero() saves successfully, the subscribe() callback receives the new hero and pushes it into to the heroes list for display.

往 HeroService 類別中新增 addHero() 方法。

Add the following addHero() method to the HeroService class.

      
        content_copy
      
      /** POST: add a new hero to the server */
addHero(hero: Hero): Observable<Hero> {
  return this.http.post<Hero>(this.heroesUrl, hero, this.httpOptions).pipe(
    tap((newHero: Hero) => this.log(`added hero w/ id=${newHero.id}`)),
    catchError(this.handleError<Hero>('addHero'))
  );
}
    

addHero() 和 updateHero() 有兩點不同。

addHero() differs from updateHero() in two ways:

• 它呼叫 HttpClient.post() 而不是 put()。

  It calls HttpClient.post() instead of put().

• 它期待伺服器為這個新的英雄產生一個 id，然後把它透過 Observable<Hero> 返回給呼叫者。

  It expects the server to generate an id for the new hero, which it returns in the Observable<Hero> to the caller.

重新整理瀏覽器，並新增一些英雄。

Refresh the browser and add some heroes.

刪除某個英雄link

Delete a herolink

英雄列表中的每個英雄都有一個刪除按鈕。

Each hero in the heroes list should have a delete button.

把下列按鈕（button）元素新增到 HeroesComponent 的範本中，就在每個 <li> 元素中的英雄名字後方。

Add the following button element to the HeroesComponent template, after the hero name in the repeated <li> element.

      
        content_copy
      
      <button class="delete" title="delete hero"
  (click)="delete(hero)">x</button>
    

英雄列表的 HTML 應該是這樣的：

The HTML for the list of heroes should look like this:

      
        content_copy
      
      <ul class="heroes">
  <li *ngFor="let hero of heroes">
    <a routerLink="/detail/{{hero.id}}">
      <span class="badge">{{hero.id}}</span> {{hero.name}}
    </a>
    <button class="delete" title="delete hero"
      (click)="delete(hero)">x</button>
  </li>
</ul>
    

要把刪除按鈕定位在每個英雄條目的最右邊，就要往 heroes.component.css 中新增一些 CSS。你可以在下方的 最終程式碼 中找到這些 CSS。

To position the delete button at the far right of the hero entry, add some CSS to the heroes.component.css. You'll find that CSS in the final review code below.

把 delete() 處理器新增到元件中。

Add the delete() handler to the component class.

      
        content_copy
      
      delete(hero: Hero): void {
  this.heroes = this.heroes.filter(h => h !== hero);
  this.heroService.deleteHero(hero).subscribe();
}
    

雖然這個元件把刪除英雄的邏輯委託給了 HeroService，但仍保留了更新它自己的英雄列表的職責。 元件的 delete() 方法會在 HeroService 對伺服器的操作成功之前，先從列表中移除要刪除的英雄。

Although the component delegates hero deletion to the HeroService, it remains responsible for updating its own list of heroes. The component's delete() method immediately removes the hero-to-delete from that list, anticipating that the HeroService will succeed on the server.

元件與 heroService.delete() 返回的 Observable 還完全沒有關聯。必須訂閱它。

There's really nothing for the component to do with the Observable returned by heroService.delete() but it must subscribe anyway.

接下來，把 deleteHero() 方法新增到 HeroService 中，程式碼如下。

Next, add a deleteHero() method to HeroService like this.

      
        content_copy
      
      /** DELETE: delete the hero from the server */
deleteHero(hero: Hero | number): Observable<Hero> {
  const id = typeof hero === 'number' ? hero : hero.id;
  const url = `${this.heroesUrl}/${id}`;

  return this.http.delete<Hero>(url, this.httpOptions).pipe(
    tap(_ => this.log(`deleted hero id=${id}`)),
    catchError(this.handleError<Hero>('deleteHero'))
  );
}
    

注意

Note the following key points:

• deleteHero() 呼叫了 HttpClient.delete()。

  deleteHero() calls HttpClient.delete().

• URL 就是英雄的資源 URL 加上要刪除的英雄的 id。

  The URL is the heroes resource URL plus the id of the hero to delete.

• 你不用像 put() 和 post() 中那樣傳送任何資料。

  You don't send data as you did with put() and post().

• 你仍要傳送 httpOptions。

  You still send the httpOptions.

重新整理瀏覽器，並試一下這個新的刪除功能。

Refresh the browser and try the new delete functionality.

根據名字搜尋link

Search by namelink

在最後一次練習中，你要學到把 Observable 的運算子串在一起，讓你能將相似 HTTP 請求的數量最小化，並節省網路頻寬。

In this last exercise, you learn to chain Observable operators together so you can minimize the number of similar HTTP requests and consume network bandwidth economically.

你將往儀表盤中加入英雄搜尋特性。 當用戶在搜尋框中輸入名字時，你會不斷髮送根據名字過濾英雄的 HTTP 請求。 你的目標是僅僅發出儘可能少的必要請求。

You will add a heroes search feature to the Dashboard. As the user types a name into a search box, you'll make repeated HTTP requests for heroes filtered by that name. Your goal is to issue only as many requests as necessary.

HeroService.searchHeroes()link

先把 searchHeroes() 方法新增到 HeroService 中。

Start by adding a searchHeroes() method to the HeroService.

      
        content_copy
      
      /* GET heroes whose name contains search term */
searchHeroes(term: string): Observable<Hero[]> {
  if (!term.trim()) {
    // if not search term, return empty hero array.
    return of([]);
  }
  return this.http.get<Hero[]>(`${this.heroesUrl}/?name=${term}`).pipe(
    tap(x => x.length ?
       this.log(`found heroes matching "${term}"`) :
       this.log(`no heroes matching "${term}"`)),
    catchError(this.handleError<Hero[]>('searchHeroes', []))
  );
}
    

如果沒有搜尋詞，該方法立即返回一個空陣列。 剩下的部分和 getHeroes() 很像。 唯一的不同點是 URL，它包含了一個由搜尋片語成的查詢字串。

The method returns immediately with an empty array if there is no search term. The rest of it closely resembles getHeroes(), the only significant difference being the URL, which includes a query string with the search term.

為儀表盤新增搜尋功能link

Add search to the Dashboardlink

開啟 DashboardComponent 的範本並且把用於搜尋英雄的元素 <app-hero-search> 新增到程式碼的底部。

Open the DashboardComponent template and add the hero search element, <app-hero-search>, to the bottom of the markup.

      
        content_copy
      
      <h3>Top Heroes</h3>
<div class="grid grid-pad">
  <a *ngFor="let hero of heroes" class="col-1-4"
      routerLink="/detail/{{hero.id}}">
    <div class="module hero">
      <h4>{{hero.name}}</h4>
    </div>
  </a>
</div>

<app-hero-search></app-hero-search>
    

這個範本看起來很像 HeroesComponent 範本中的 *ngFor 複寫器。

This template looks a lot like the *ngFor repeater in the HeroesComponent template.

為此，下一步就是新增一個元件，它的選擇器要能匹配 <app-hero-search>。

For this to work, the next step is to add a component with a selector that matches <app-hero-search>.

建立 HeroSearchComponentlink

Create HeroSearchComponentlink

使用 CLI 建立一個 HeroSearchComponent。

Create a HeroSearchComponent with the CLI.

      
        content_copy
      
      ng generate component hero-search
    

CLI 生成了 HeroSearchComponent 的三個檔案，並把該元件新增到了 AppModule 的宣告中。

The CLI generates the three HeroSearchComponent files and adds the component to the AppModule declarations.

把產生的 HeroSearchComponent 的範本改成一個 <input> 和一個匹配到的搜尋結果的列表。程式碼如下：

Replace the generated HeroSearchComponent template with an <input> and a list of matching search results, as follows.

      
        content_copy
      
      <div id="search-component">
  <h4><label for="search-box">Hero Search</label></h4>

  <input #searchBox id="search-box" (input)="search(searchBox.value)" />

  <ul class="search-result">
    <li *ngFor="let hero of heroes$ | async" >
      <a routerLink="/detail/{{hero.id}}">
        {{hero.name}}
      </a>
    </li>
  </ul>
</div>
    

從下面的 最終程式碼 中把私有 CSS 樣式新增到 hero-search.component.css 中。

Add private CSS styles to hero-search.component.css as listed in the final code review below.

當用戶在搜尋框中輸入時，一個 keyup 事件繫結會呼叫該元件的 search() 方法，並傳入新的搜尋框的值。

As the user types in the search box, an input event binding calls the component's search() method with the new search box value.

AsyncPipelink

*ngFor 會重複渲染這些英雄物件。注意，*ngFor 在一個名叫 heroes$ 的列表上迭代，而不是 heroes。$ 是一個約定，表示 heroes$ 是一個 Observable 而不是陣列。

The *ngFor repeats hero objects. Notice that the *ngFor iterates over a list called heroes$, not heroes. The $ is a convention that indicates heroes$ is an Observable, not an array.

      
        content_copy
      
      <li *ngFor="let hero of heroes$ | async" >
    

由於 *ngFor 不能直接使用 Observable，所以要使用一個管道字元（|），後面緊跟著一個 async。這表示 Angular 的 AsyncPipe 管道，它會自動訂閱 Observable，這樣你就不用在元件類別中這麼做了。

Since *ngFor can't do anything with an Observable, use the pipe character (|) followed by async. This identifies Angular's AsyncPipe and subscribes to an Observable automatically so you won't have to do so in the component class.

修正 HeroSearchComponent 類別link

Edit the HeroSearchComponent classlink

修改所產生的 HeroSearchComponent 類別及其元資料，程式碼如下：

Replace the generated HeroSearchComponent class and metadata as follows.

      
        content_copy
      
      import { Component, OnInit } from '@angular/core';

import { Observable, Subject } from 'rxjs';

import {
   debounceTime, distinctUntilChanged, switchMap
 } from 'rxjs/operators';

import { Hero } from '../hero';
import { HeroService } from '../hero.service';

@Component({
  selector: 'app-hero-search',
  templateUrl: './hero-search.component.html',
  styleUrls: [ './hero-search.component.css' ]
})
export class HeroSearchComponent implements OnInit {
  heroes$: Observable<Hero[]>;
  private searchTerms = new Subject<string>();

  constructor(private heroService: HeroService) {}

  // Push a search term into the observable stream.
  search(term: string): void {
    this.searchTerms.next(term);
  }

  ngOnInit(): void {
    this.heroes$ = this.searchTerms.pipe(
      // wait 300ms after each keystroke before considering the term
      debounceTime(300),

      // ignore new term if same as previous term
      distinctUntilChanged(),

      // switch to new search observable each time the term changes
      switchMap((term: string) => this.heroService.searchHeroes(term)),
    );
  }
}
    

注意，heroes$ 宣告為一個 Observable

Notice the declaration of heroes$ as an Observable:

      
        content_copy
      
      heroes$: Observable<Hero[]>;
    

你將會在 ngOnInit()中設定它，在此之前，先仔細看看 searchTerms 的定義。

You'll set it in ngOnInit(). Before you do, focus on the definition of searchTerms.

RxJS Subject 型別的 searchTermslink

The searchTerms RxJS subjectlink

searchTerms 屬性是 RxJS 的 Subject 型別。

The searchTerms property is an RxJS Subject.

      
        content_copy
      
      private searchTerms = new Subject<string>();

// Push a search term into the observable stream.
search(term: string): void {
  this.searchTerms.next(term);
}
    

Subject 既是可觀察物件的資料來源，本身也是 Observable。 你可以像訂閱任何 Observable 一樣訂閱 Subject。

A Subject is both a source of observable values and an Observable itself. You can subscribe to a Subject as you would any Observable.

你還可以透過呼叫它的 next(value) 方法往 Observable 中推送一些值，就像 search() 方法中一樣。

You can also push values into that Observable by calling its next(value) method as the search() method does.

文字框的 input 事件的事件繫結會呼叫 search() 方法。

The event binding to the textbox's input event calls the search() method.

      
        content_copy
      
      <input #searchBox id="search-box" (input)="search(searchBox.value)" />
    

每當使用者在文字框中輸入時，這個事件繫結就會使用文字框的值（搜尋詞）呼叫 search() 函式。 searchTerms 變成了一個能發出搜尋詞的穩定的流。

Every time the user types in the textbox, the binding calls search() with the textbox value, a "search term". The searchTerms becomes an Observable emitting a steady stream of search terms.

串聯 RxJS 運算子link

Chaining RxJS operatorslink

如果每當使用者擊鍵後就直接呼叫 searchHeroes() 將導致建立海量的 HTTP 請求，浪費伺服器資源並干擾資料排程計劃。

Passing a new search term directly to the searchHeroes() after every user keystroke would create an excessive amount of HTTP requests, taxing server resources and burning through data plans.

應該怎麼做呢？ngOnInit() 往 searchTerms 這個可觀察物件的處理管道中加入了一系列 RxJS 運算子，用以縮減對 searchHeroes() 的呼叫次數，並最終返回一個可及時給出英雄搜尋結果的可觀察物件（每次都是 Hero[] ）。

Instead, the ngOnInit() method pipes the searchTerms observable through a sequence of RxJS operators that reduce the number of calls to the searchHeroes(), ultimately returning an observable of timely hero search results (each a Hero[]).

程式碼如下：

Here's a closer look at the code.

      
        content_copy
      
      this.heroes$ = this.searchTerms.pipe(
  // wait 300ms after each keystroke before considering the term
  debounceTime(300),

  // ignore new term if same as previous term
  distinctUntilChanged(),

  // switch to new search observable each time the term changes
  switchMap((term: string) => this.heroService.searchHeroes(term)),
);
    

各個運算子的工作方式如下：

Each operator works as follows:

• 在傳出最終字串之前，debounceTime(300) 將會等待，直到新增字串的事件暫停了 300 毫秒。 你實際發起請求的間隔永遠不會小於 300ms。

  debounceTime(300) waits until the flow of new string events pauses for 300 milliseconds before passing along the latest string. You'll never make requests more frequently than 300ms.

• distinctUntilChanged() 會確保只在過濾條件變化時才傳送請求。

  distinctUntilChanged() ensures that a request is sent only if the filter text changed.

• switchMap() 會為每個從 debounce() 和 distinctUntilChanged() 中透過的搜尋詞調用搜索服務。 它會取消並丟棄以前的搜尋可觀察物件，只保留最近的。

  switchMap() calls the search service for each search term that makes it through debounce() and distinctUntilChanged(). It cancels and discards previous search observables, returning only the latest search service observable.

記住，元件類別中並沒有訂閱 heroes$ 這個可觀察物件，而是由範本中的 AsyncPipe完成的。

Remember that the component class does not subscribe to the heroes$ observable. That's the job of the AsyncPipein the template.

試試看link

Try itlink

再次執行本應用。在這個 儀表盤 中，在搜尋框中輸入一些文字。如果你輸入的字元匹配上了任何現有英雄的名字，你將會看到如下效果：

Run the app again. In the Dashboard, enter some text in the search box. If you enter characters that match any existing hero names, you'll see something like this.

檢視最終程式碼link

Final code reviewlink

本文討論過的程式碼檔案如下（都位於 src/app/ 資料夾中）。

Here are the code files discussed on this page (all in the src/app/ folder).

HeroService, InMemoryDataService, AppModulelink

      
        content_copy
      
      import { Injectable } from '@angular/core';
import { HttpClient, HttpHeaders } from '@angular/common/http';

import { Observable, of } from 'rxjs';
import { catchError, map, tap } from 'rxjs/operators';

import { Hero } from './hero';
import { MessageService } from './message.service';


@Injectable({ providedIn: 'root' })
export class HeroService {

  private heroesUrl = 'api/heroes';  // URL to web api

  httpOptions = {
    headers: new HttpHeaders({ 'Content-Type': 'application/json' })
  };

  constructor(
    private http: HttpClient,
    private messageService: MessageService) { }

  /** GET heroes from the server */
  getHeroes(): Observable<Hero[]> {
    return this.http.get<Hero[]>(this.heroesUrl)
      .pipe(
        tap(_ => this.log('fetched heroes')),
        catchError(this.handleError<Hero[]>('getHeroes', []))
      );
  }

  /** GET hero by id. Return `undefined` when id not found */
  getHeroNo404<Data>(id: number): Observable<Hero> {
    const url = `${this.heroesUrl}/?id=${id}`;
    return this.http.get<Hero[]>(url)
      .pipe(
        map(heroes => heroes[0]), // returns a {0|1} element array
        tap(h => {
          const outcome = h ? `fetched` : `did not find`;
          this.log(`${outcome} hero id=${id}`);
        }),
        catchError(this.handleError<Hero>(`getHero id=${id}`))
      );
  }

  /** GET hero by id. Will 404 if id not found */
  getHero(id: number): Observable<Hero> {
    const url = `${this.heroesUrl}/${id}`;
    return this.http.get<Hero>(url).pipe(
      tap(_ => this.log(`fetched hero id=${id}`)),
      catchError(this.handleError<Hero>(`getHero id=${id}`))
    );
  }

  /* GET heroes whose name contains search term */
  searchHeroes(term: string): Observable<Hero[]> {
    if (!term.trim()) {
      // if not search term, return empty hero array.
      return of([]);
    }
    return this.http.get<Hero[]>(`${this.heroesUrl}/?name=${term}`).pipe(
      tap(x => x.length ?
         this.log(`found heroes matching "${term}"`) :
         this.log(`no heroes matching "${term}"`)),
      catchError(this.handleError<Hero[]>('searchHeroes', []))
    );
  }

  //////// Save methods //////////

  /** POST: add a new hero to the server */
  addHero(hero: Hero): Observable<Hero> {
    return this.http.post<Hero>(this.heroesUrl, hero, this.httpOptions).pipe(
      tap((newHero: Hero) => this.log(`added hero w/ id=${newHero.id}`)),
      catchError(this.handleError<Hero>('addHero'))
    );
  }

  /** DELETE: delete the hero from the server */
  deleteHero(hero: Hero | number): Observable<Hero> {
    const id = typeof hero === 'number' ? hero : hero.id;
    const url = `${this.heroesUrl}/${id}`;

    return this.http.delete<Hero>(url, this.httpOptions).pipe(
      tap(_ => this.log(`deleted hero id=${id}`)),
      catchError(this.handleError<Hero>('deleteHero'))
    );
  }

  /** PUT: update the hero on the server */
  updateHero(hero: Hero): Observable<any> {
    return this.http.put(this.heroesUrl, hero, this.httpOptions).pipe(
      tap(_ => this.log(`updated hero id=${hero.id}`)),
      catchError(this.handleError<any>('updateHero'))
    );
  }

  /**
   * Handle Http operation that failed.
   * Let the app continue.
   * @param operation - name of the operation that failed
   * @param result - optional value to return as the observable result
   */
  private handleError<T>(operation = 'operation', result?: T) {
    return (error: any): Observable<T> => {

      // TODO: send the error to remote logging infrastructure
      console.error(error); // log to console instead

      // TODO: better job of transforming error for user consumption
      this.log(`${operation} failed: ${error.message}`);

      // Let the app keep running by returning an empty result.
      return of(result as T);
    };
  }

  /** Log a HeroService message with the MessageService */
  private log(message: string) {
    this.messageService.add(`HeroService: ${message}`);
  }
}
    

HeroesComponentlink

      
        content_copy
      
      <h2>My Heroes</h2>

<div>
  <label>Hero name:
    <input #heroName />
  </label>
  <!-- (click) passes input value to add() and then clears the input -->
  <button (click)="add(heroName.value); heroName.value=''">
    add
  </button>
</div>

<ul class="heroes">
  <li *ngFor="let hero of heroes">
    <a routerLink="/detail/{{hero.id}}">
      <span class="badge">{{hero.id}}</span> {{hero.name}}
    </a>
    <button class="delete" title="delete hero"
      (click)="delete(hero)">x</button>
  </li>
</ul>
    

HeroDetailComponentlink

      
        content_copy
      
      <div *ngIf="hero">
  <h2>{{hero.name | uppercase}} Details</h2>
  <div><span>id: </span>{{hero.id}}</div>
  <div>
    <label>name:
      <input [(ngModel)]="hero.name" placeholder="name"/>
    </label>
  </div>
  <button (click)="goBack()">go back</button>
  <button (click)="save()">save</button>
</div>
    

DashboardComponentlink

      
        content_copy
      
      <h3>Top Heroes</h3>
<div class="grid grid-pad">
  <a *ngFor="let hero of heroes" class="col-1-4"
      routerLink="/detail/{{hero.id}}">
    <div class="module hero">
      <h4>{{hero.name}}</h4>
    </div>
  </a>
</div>

<app-hero-search></app-hero-search>
    

HeroSearchComponentlink

      
        content_copy
      
      <div id="search-component">
  <h4><label for="search-box">Hero Search</label></h4>

  <input #searchBox id="search-box" (input)="search(searchBox.value)" />

  <ul class="search-result">
    <li *ngFor="let hero of heroes$ | async" >
      <a routerLink="/detail/{{hero.id}}">
        {{hero.name}}
      </a>
    </li>
  </ul>
</div>
    

小結link

Summarylink

旅程即將結束，不過你已經收穫頗豐。

You're at the end of your journey, and you've accomplished a lot.

• 你添加了在應用程式中使用 HTTP 的必備依賴。

  You added the necessary dependencies to use HTTP in the app.

• 你重構了 HeroService，以透過 web API 來載入英雄資料。

  You refactored HeroService to load heroes from a web API.

• 你擴充套件了 HeroService 來支援 post()、put() 和 delete() 方法。

  You extended HeroService to support post(), put(), and delete() methods.

• 你修改了元件，以允許使用者新增、編輯和刪除英雄。

  You updated the components to allow adding, editing, and deleting of heroes.

• 你配置了一個記憶體 Web API。

  You configured an in-memory web API.

• 你學會了如何使用“可觀察物件”。

  You learned how to use observables.

《英雄之旅》課程結束了。 如果你準備開始學習 Angular 開發的原理，請開始 架構 一章。

This concludes the "Tour of Heroes" tutorial. You're ready to learn more about Angular development in the fundamentals section, starting with the Architecture guide.