章節:

介紹檢視元件

檢視元件是 ASP.NET Core MVC 中的新特性，與區域性檢視相似，但是它們更加的強大。檢視元件不使用模型繫結，只取決於呼叫它時所提供的資料。檢視元件有以下特點：

• 渲染一個塊，而不是整個響應
• 在控制器和檢視之間同樣包含了關注點分離和可測試性帶來的好處
• 可以擁有引數和業務邏輯
• 通常從佈局頁呼叫

檢視元件可以用在任何需要重複邏輯且對區域性檢視來說過於複雜的情況，比如：

• 動態導航選單
• 標籤雲 (需要從資料庫查詢時)
• 登入面板
• 購物車
• 最近發表的文章
• 一個典型部落格的側邊欄內容
• 會在所有頁面渲染的登入面板，根據使用者登入狀態顯示登入或者登出

一個 檢視元件 包含兩個部分，類（通常派生自 ViewComponent

建立檢視元件

這個章節包含建立檢視元件的高階需求。在稍後的文章中，我們將詳細地檢查每一個步驟，並建立一個檢視元件。

檢視元件類

一個檢視元件類可以由以下任何一個方式建立：

• 派生自 ViewComponent
• 使用 [ViewComponent] 特性裝飾一個類，或者這個類的派生類。
• 建立一個類，並以 ViewComponent 作為字尾。

如同控制器一樣，檢視元件必須是公開的，非巢狀的，以及非抽象的類。檢視元件名稱是類名並去掉“ViewComponent”字尾。也可以通過

一個檢視元件類：

• 完全支援建構函式依賴注入
• 不參與控制器生命週期，意味著你不能在檢視元件中使用過濾器

檢視元件方法

檢視元件在 InvokeAsync 方法中中定義邏輯，並返回 [IViewComponentResultIViewComponentResult。引數直接來自檢視元件的呼叫，而不是來自模型繫結。檢視元件從來不直接處理請求。通常檢視元件初始化模型並通過呼叫 View方法傳遞它到檢視。總之，檢視元件方法有以下特點：

• 定義一個 InvokeAsync 方法並返回 IViewComponentResult
• 通常初始化模型並通過呼叫ViewComponent View方法傳遞它到檢視
• 引數來自呼叫方法，而不是 HTTP，沒有模型繫結
• 不可直接作為 HTTP 終結點，它們從你的程式碼中呼叫（通常在檢視中）。檢視元件從不處理請求
• 過載的簽名，而不是當前 HTTP 請求中的任何細節

檢視搜尋路徑

執行時對檢視的搜尋路徑如下：

• Views//Components//
• Views/Shared/Components//

檢視元件預設的檢視名是 Default，意味著通常你的檢視檔案會命名為 Default.cshtml。當你建立檢視元件結果或者呼叫 View 方法的時候，你可以指定不同的檢視名。

我們建議你命名檢視檔案為 Default.cshtml 並且使用 Views/Shared/Components// 路徑。在這個例子中使用的 PriorityList 檢視元件使用了 Views/Shared/Components/PriorityList/Default.cshtml 這個路徑。

呼叫檢視元件

要使用檢視元件，從檢視中呼叫 @Component.InvokeAsync("檢視元件名", <匿名型別引數>)。引數將傳遞給 InvokeAsync 方法。在文章中開發的 PriorityList 檢視元件被 Views/Todo/Index.cshtml 檢視檔案呼叫。在下面，使用了兩個引數呼叫 InvokeAsync 方法：

@await Component.InvokeAsync("PriorityList", new { maxPriority = 2, isDone = false })

從控制器直接呼叫檢視元件

檢視元件通常從檢視中呼叫，但是你也可以從控制器方法中直接呼叫。當檢視元件沒有像控制器一樣定義終結點時，你可以簡單實現一個控制器的 Action ，並使用一個 ViewComponentResult作為返回內容。

在這例子中，檢視元件通過控制器直接呼叫：

 public IActionResult IndexVC()
  {
      return ViewComponent("PriorityList", new { maxPriority = 3, isDone = false });
  }

演練：建立一個簡單的檢視元件

下載，生成並測試啟動程式碼。這是一個簡單的專案，使用一個 Todo 控制器來顯示 Todo 項列表。

新增一個檢視元件類

建立一個 ViewComponents 資料夾並新增下面的 PriorityListViewComponent 類。

using Microsoft.AspNet.Mvc;
using Microsoft.Data.Entity;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using ViewComponentSample.Models;

namespace ViewComponentSample.ViewComponents
{
    public class PriorityListViewComponent : ViewComponent
    {
        private readonly ToDoContext db;

        public PriorityListViewComponent(ToDoContext context)
        {
            db = context;
        }

        public async Task<IViewComponentResult> InvokeAsync(
        int maxPriority, bool isDone)
        {
            var items = await GetItemsAsync(maxPriority, isDone);
            return View(items);
        }
        private Task<List<TodoItem>> GetItemsAsync(int maxPriority, bool isDone)
        {
            return db.ToDo.Where(x => x.IsDone == isDone &&
                                 x.Priority <= maxPriority).ToListAsync();
        }       
    }
}

程式碼註釋：

• 檢視元件類可以被放在專案中 任何 資料夾內。
• 因為類命名為 PriorityListViewComponent，以 ViewComponent 作為字尾結束，在執行時會從檢視中使用 "PriorityList" 字串來引用元件類。我會在後面詳細解釋。
• [ViewComponent] 特性可以改變被用來引用檢視元件的名字。比如，我們可以命名類為 XYZ，然後應用 ViewComponent 特性：

[ViewComponent(Name = "PriorityList")]
public class XYZ : ViewComponent

• 上面的 [ViewComponent] 特性告知檢視元件選擇器在尋找與元件相關的檢視時使用名字 PriorityList，並且在從檢視中引用元件類時使用 "PriorityList" 字串。我會在後面詳細解釋。
• 元件使用依賴注入使得資料上下文可用。
• InvokeAsync 暴露一個可以在檢視中呼叫的方法，並且它可以接受任意數量的引數。
• InvokeAsync 方法返回沒有完成並優先順序小於等於 maxPriority 的 ToDo 項的集合。

建立檢視元件 Razor 檢視

1. 建立 Views/Shared/Components 資料夾。這個資料夾 必須 命名為 Components。
2. 建立 Views/Shared/Components/PriorityList 資料夾。這個資料夾必須和檢視元件類名字匹配，或者是類名去掉字尾（如果我們遵循了約定並且使用 ViewComponent 作為類名字尾）。如果你使用 ViewComponent 特性，類名需要匹配特性中指定的名字。
3. 建立一個 Views/Shared/Components/PriorityList/Default.cshtml Razor 檢視。

@model IEnumerable<ViewComponentSample.Models.TodoItem>

<h3>Priority Items</h3>
<ul>
    @foreach (var todo in Model)
    {
        <li>@todo.Name</li>
    }
</ul>

Razor 檢視取一組 TodoItem 並顯示它們。如果檢視元件的 InvokeAsync 方法沒有傳遞檢視名（就像我們例子中），按照約定會使用 Default 作為檢視名。在教程的後面部分，我會告訴你如何傳遞檢視的名稱。為特定控制器重寫預設的樣式，新增一個檢視到特定控制器的檢視資料夾（比如 Views/Todo/Components/PriorityList/Default.cshtml）。

如果檢視元件是特定控制器的，你可以新增到特定控制器資料夾（Views/Todo/Components/PriorityList/Default.cshtml）。

1. 在 Views/Todo/index.cshtml 檔案底部新增一個 div 包含呼叫 PriorityList 元件：

  }
</table>
<div >
    @await Component.InvokeAsync("PriorityList", new { maxPriority = 2, isDone = false })
</div>

標記 @Component.InvokeAsync 展示了呼叫檢視元件的語法。第一個引數是我們想要呼叫的元件名。隨後的引數傳遞給元件。InvokeAsync 可以接受任意數量的引數。

下面的圖片顯示了 Priority 項：

你也可以從控制器直接呼叫檢視元件：

public IActionResult IndexVC()
{
    return ViewComponent("PriorityList", new { maxPriority = 3, isDone = false });
}

指定檢視名

一個複雜的檢視元件在某些條件下可能需要指定非預設的檢視。下面的程式碼展示如何從 InvokeAsync 方法中指定 "PVC" 檢視。更新 PriorityListViewComponent 類中的 InvokeAsync 方法。

public async Task<IViewComponentResult> InvokeAsync(int maxPriority, bool isDone)
{
    string MyView = "Default"; // 手動高亮
    // If asking for all completed tasks, render with the "PVC" view. // 手動高亮
    if (maxPriority > 3 && isDone == true) // 手動高亮
    {   // 手動高亮
        MyView = "PVC"; // 手動高亮
    }   // 手動高亮
    var items = await GetItemsAsync(maxPriority, isDone);
    return View(MyView, items);
}

複製 Views/Shared/Components/PriorityList/Default.cshtml 檔案到一個檢視中並命名為 Views/Shared/Components/PriorityList/PVC.cshtml。新增一個標題到 PVC 檢視來表明正在使用此檢視。

@model IEnumerable<ViewComponentSample.Models.TodoItem>

<h2> PVC Named Priority Component View</h2> // 手動高亮
<h4>@ViewBag.PriorityMessage</h4>
<ul>
    @foreach (var todo in Model)
    {
        <li>@todo.Name</li>
    }
</ul>

更新 Views/TodoList/Index.cshtml

</table>

<div>
    @await Component.InvokeAsync("PriorityList", new { maxPriority = 4, isDone = true })
</div>

執行應用程式並驗證 PVC 檢視。

如果 PVC 檢視沒有渲染，請驗證你是否使用 4 或者更高 priority 引數來呼叫檢視元件。

檢查檢視路徑

1. 改變 priority 引數到 3 或者更低，使得不返回優先順序檢視。
2. 暫時重新命名 Views/Todo/Components/PriorityList/Default.cshtml 為 Temp.cshtml。

3. 測試應用程式，你將得到以下錯誤：

   An unhandled exception occurred while processing the request.

   InvalidOperationException: The view 'Components/PriorityList/Default'
   was not found. The following locations were searched:
   /Views/ToDo/Components/PriorityList/Default.cshtml
   /Views/Shared/Components/PriorityList/Default.cshtml.
   Microsoft.AspNetCore.Mvc.ViewEngines.ViewEngineResult.EnsureSuccessful()

4. 複製 Views/Shared/Components/PriorityList/Default.cshtml 到 Views/Todo/Components/PriorityList/Default.cshtml。
5. 新增一些標記到 Todo 檢視元件檢視來表明檢視是來自 Todo 資料夾。

6. 測試 非共享 元件檢視。

避免魔法字串

如果你想編譯時安全你可以用類名替換硬編碼檢視元件名。建立檢視元件不以 "ViewComponent" 作為字尾：

using Microsoft.AspNet.Mvc;
using Microsoft.Data.Entity;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using ViewComponentSample.Models;

namespace ViewComponentSample.ViewComponents
{
    public class PriorityList : ViewComponent // 手動高亮
    {
        private readonly ToDoContext db;

        public PriorityList(ToDoContext context) // 手動高亮
        {
            db = context;
        }

        public async Task<IViewComponentResult> InvokeAsync(
        int maxPriority, bool isDone)
        {
            var items = await GetItemsAsync(maxPriority, isDone);
            return View(items);
        }
        private Task<List<TodoItem>> GetItemsAsync(int maxPriority, bool isDone)
        {
            return db.ToDo.Where(x => x.IsDone == isDone &&
                                 x.Priority <= maxPriority).ToListAsync();
        }
    }
}

新增一個 using 語句到你的 Razor 檢視檔案並使用 nameof 操作符：

@using ViewComponentSample.Models
@using ViewComponentSample.ViewComponents
@model IEnumerable<TodoItem>

<h2>ToDo nameof</h2>
<!-- Markup removed for brevity.  -->
    }
</table>

<div>

    @await Component.InvokeAsync(nameof(PriorityList), new { maxPriority = 4, isDone = true })
</div>

附加的資源

返回目錄