ASP.NET Core Blazor 基本概念

發行項
11/19/2024

注意

這不是這篇文章的最新版本。如需目前的版本，請參閱本文的 .NET 9 版本。

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支持原則。如需目前的版本，請參閱本文的 .NET 9 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前的版本，請參閱本文的 .NET 9 版本。

「基本概念」文章會提供 Blazor 基本概念的指引。某些概念可讓您對「Razor 元件」有基本的了解，本文的下一節會進一步說明這些元件，元件文章中也會有詳細說明。

靜態和互動式轉譯概念

Razor 元件會以靜態方式轉譯，或以互動方式轉譯。

靜態或靜態轉譯是伺服器端案例，表示元件無需使用者與 .NET/C# 程式碼之間的互動能力即可轉譯。 JavaScript 和 HTML DOM 事件不受影響，但用戶端上的任何使用者事件都無法使用在伺服器上執行的 .NET 進行處理。

互動式或互動式轉譯表示元件有能力透過 C# 程式碼處理 .NET 事件。 .NET 事件會在伺服器上由 ASP.NET Core 執行階段進行處理，或在用戶端上的瀏覽器中由 WebAssembly 型 Blazor 執行階段進行處理。

重要

當使用 Blazor Web App時，大部分 Blazor 文件範例元件需要互動功能，才能運作，還會示範文章裡頭涵蓋的概念。當您測試文章所提供的範例元件時，請確定應用程式採用全域互動，或元件採用互動式轉譯模式。

如需這些概念以及如何控制靜態和互動式轉譯的詳細資訊，請參閱 Blazor 文件稍後的 ASP.NET Core Blazor 轉譯模式一文。

用戶端和伺服器轉譯概念

在整份 Blazor 文件中，在使用者系統上發生的活動均指稱為發生在用戶端上或用戶端。在伺服器上發生的活動則指稱為發生在伺服器上或伺服器端。

轉譯一詞意指產生瀏覽器所顯示的 HTML 標記。

用戶端轉譯 (CSR) 意指最終的 HTML 標記由用戶端上的 .NET WebAssembly 執行階段產生。應用程式用戶端產生的 UI 沒有任何 HTML 會從伺服器傳送至用戶端以進行此類型的轉譯。假設使用者會與頁面互動。沒有靜態用戶端轉譯之類的概念。 CSR 假定為互動式的，產業或 Blazor 文件中不會使用「互動式用戶端轉譯」和「互動式 CSR」。
伺服器端轉譯 (SSR) 意指最終的 HTML 標記由伺服器上的 ASP.NET Core 執行階段所產生。 HTML 會透過網路傳送至用戶端，供用戶端的瀏覽器顯示。用戶端不會為應用程式伺服器產生的 UI 建立任何 HTML 以進行此類型的轉譯。 SSR 可屬於兩種類型：
- 靜態 SSR：伺服器會產生不提供使用者互動功能或維護 Razor 元件狀態的靜態 HTML。
- 互動式 SSR：Blazor 事件允許使用者互動功能，且 Blazor 架構會維護 Razor 元件狀態。
預先轉譯是伺服器上初始轉譯頁面內容，而不需要為轉譯的控制項啟用事件處理常式的程序。伺服器會盡快輸出頁面的 HTML UI，以回應初始要求，如此可改善應用程式對使用者的回應速度。預先轉譯也可改善搜尋引擎最佳化 (SEO)，方法是轉譯搜尋引擎用來計算頁面排名的初始 HTTP 回應的內容。在伺服器或用戶端上，一律會先進行預先轉譯，再進行最終轉譯。

Razor 元件

Blazor 應用程式會以「Razor 元件」作為基礎，後者通常簡稱「元件」。「元件」是 UI 的元素，例如頁面、對話方塊或資料輸入表單。元件是內建到 .NET 組件的 .NET C# 類別。

Razor 會針對用戶端 UI 邏輯和組合，以 Razor 標記頁面的形式指出元件通常的撰寫方式。 Razor 是結合了 HTML 標記與 C# 程式碼的語法，專為開發人員的生產力而設計。 Razor 檔案會使用 .razor 副檔名。

雖然某些 Blazor 開發人員和線上資源使用「Blazor 元件」一詞，但本文不會這麼做，而是會普遍使用「Razor 元件」或「元件」。

Blazor 文件採用數個慣例來顯示和討論元件：

一般而言，範例會遵循 ASP.NET Core/C# 編碼慣例和工程指導方針。如需詳細資訊，請參閱下列資源：
- ASP.NET Core 架構工程指導方針（dotnet/aspnetcore GitHub 存放庫）
- C# 編碼慣例 (C# 指南)
專案程式碼、檔案路徑和名稱、專案範本名稱和其他特製化詞彙都是美式英文，而且通常會以代碼保護。
元件通常會以其 C# 類別名稱 (Pascal 命名法) 加上「元件」一字來指稱。例如，典型的檔案上傳元件稱為「FileUpload 元件」。
元件的 C# 類別名稱通常與其檔案名稱相同。
路由式元件通常會將其相對 URL 設定為元件的類別名稱 (採用 Kebab 命名法)。例如，FileUpload 元件包含路由設定，可在相對 URL /file-upload 連線到轉譯的元件。路由和導覽的說明請見 ASP.NET Core Blazor 路由和導覽。
使用多個版本的元件時，元件會循序編號。例如，在 /file-upload-3 到達 FileUpload3 元件。
元件定義 (.razor file) 頂端的 Razor 指示詞會按下列順序放置：@page、@rendermode (.NET 8 或更新版本)、@using 陳述式、按字母順序排列的其他指示詞。
雖然 private 成員並不需要，但在文章範例與範例應用程式中會使用存取修飾詞。例如，會陳述 private 以將名為 maxAllowedFiles 的欄位宣告為 private int maxAllowedFiles = 3;。
元件參數值會以 Razor 保留 @ 符號開頭，但並非必要。常值 (例如布林值)、關鍵字 (例如 this)，以及作為元件參數值的 null 前面不會加上 @，但這也只是文件慣例。在您自己的程式碼中，您可以視需要對常值使用 @ 前置詞。
C# 類別會使用 this 關鍵字，並避免在建構函式中為指派至的前置欄位加上底線 (_)，這與 ASP.NET Core 架構工程指導方針不同。
在使用主要建構函式的範例中（C# 12 或更新版），主要建構函式參數通常由類別成員直接使用。

如需 Razor 元件語法的其他資訊，請參閱 ASP.NET Core Razor 元件的 Razor 語法 章節。

下面會舉例說明計數器元件以及從 Blazor 專案範本建立的應用程式部分內容。如需詳細的元件說明，請參閱文件稍後的「元件」文章。下列範例會先示範「基本概念」文章中所見的元件概念，再到達文件稍後的「元件」文章。

Counter.razor：

此元件會假設互動式轉譯模式繼承自父元件，或全域套用至應用程式。

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

此元件會假設互動式轉譯模式繼承自父元件，或全域套用至應用程式。

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

上述 Counter 元件：

會在第一行使用 @page 指示詞設定其路由。
會設定其網頁標題和標題。
會使用 @currentCount 轉譯目前的計數。 currentCount 是 @code 區塊的 C# 程式碼所定義的整數變數。
會顯示可觸發 IncrementCount 方法的按鈕，該按鈕也可在 @code 區塊中找到，並且會增加 currentCount 變數的值。

轉譯模式

基礎節點中的文章會參考轉譯模式的概念。此主題詳述於元件節點中的 ASP.NET Core Blazor 轉譯模式一文，編排在基礎文章節點之後。

對於此文章節點中關於轉譯模式概念的早期參考，目前只須留意下列內容：

Blazor Web App 中的所有元件都會採用 轉譯模式 來確認使用到的裝載模型、轉譯位置，還有是否透過靜態方式，在伺服器上完成轉譯，針對伺服器上的使用者互動功能進行轉譯，或者針對用戶端上的使用者互動功能進行轉譯 (通常會在伺服器上預先轉譯)。

.NET 8 之前的 ASP.NET Core 版本的 Blazor Server 和 Blazor WebAssembly 應用程式仍著重於裝載模型概念，而不是轉譯模式。從概念層面來看，轉譯模式適用於 .NET 8 或更新版本中的 Blazor Web App。

以下表格顯示可用的轉譯模式，可用來轉譯 Razor 元件，元件源自 Blazor Web App。轉譯模式可透過元件執行個體或元件定義上的 @rendermode 指示詞套用至元件。此外也可設定整個應用程式的轉譯模式。

名稱	描述	轉譯位置	互動式
靜態伺服器	靜態伺服器端轉譯 (靜態 SSR)	伺服器	否
互動式伺服器	使用 Blazor Server 的互動式伺服器端轉譯 (互動式 SSR)	伺服器	是
互動式 WebAssembly	使用 Blazor WebAssembly 的用戶端轉譯 (CSR)†	Client	是
互動式自動	一開始使用 Blazor Server 進行互動式 SSR，然後在下載 Blazor 套件組合之後，於後續造訪時使用 CSR	伺服器，然後用戶端	是

† 用戶端轉譯 (CSR) 會假設為互動式。產業或 Blazor 文件中不會使用「互動式用戶端轉譯」和「互動式 CSR」。

只要掌握上述有關於轉譯模式的資訊，就能了解基礎節點文章。如果您不熟悉 Blazor，並依照目錄順序閱讀 Blazor 文章，則可能要等到您閱讀元件節點中的 ASP.NET Core Blazor 轉譯模式一文時，才會看到轉譯模式的深入資訊。

文件物件模型 (DOM)

文件物件模型 的參考會使用縮寫 DOM。

如需詳細資訊，請參閱以下資源：

適用於 Blazor WebAssembly 應用程式的 .NET API 子集

目前並未選列瀏覽器上支援用於 Blazor WebAssembly 的特定 .NET API。不過，您可以手動搜尋加註 [UnsupportedOSPlatform("browser")] 的 .NET API 清單，以探索 WebAssembly 中不支援的 .NET API。

注意

.NET 參考來源的文件連結通常會載入存放庫的預設分支，這表示下一版 .NET 的目前開發。若要選取特定版本的標籤，請使用 [切換分支或標籤] 下拉式清單。如需詳細資訊，請參閱如何選取 ASP.NET Core 原始程式碼 (dotnet/AspNetCore.Docs #26205) 的版本標籤。

如需詳細資訊，請參閱以下資源：

範例應用程式

文件範例應用程式可供檢查和下載：

Blazor 範例 GitHub 存放庫 (dotnet/blazor-samples)

先選取與您使用的 .NET 版本相符的版本資料夾，以找出範例應用程式。

存放庫中的範例應用程式：

Blazor Web App
Blazor WebAssembly
Blazor Web App 使用到 EF Core (ASP.NET Core Blazor 搭載 Entity Framework Core (EF Core))
Blazor Web App 使用到 SignalR (使用 ASP.NET Core SignalR 搭載 Blazor)
有兩種 Blazor Web App 和這款 Blazor WebAssembly 應用程式，可用來呼叫 Web（伺服器）API（透過 ASP.NET Core Blazor 應用程式呼叫 Web API）
Blazor Web App 搭載 OIDC（BFF 和非 BFF 模式）（使用 OpenID Connect (OIDC) 保護 ASP.NET Core Blazor Web App 的安全）
Blazor WebAssembly 已啟用範圍的記錄 (ASP.NET Core Blazor 記錄)
Blazor WebAssembly 與 ASP.NET Core Identity (使用 ASP.NET Core Identity 保護 ASP.NET Core Blazor WebAssembly)
.NET MAUIBlazor Hybrid 應用程式搭載 Blazor Web App 和 Razor 類別庫 (RCL) 提供的共用 UI（組建 .NET MAUIBlazor Hybrid 應用程式會使用到Blazor Web App)

範例存放庫包含兩種類型的範例：

程式碼片段範例應用程式會提供出現在文章中的程式碼範例。這些應用程式會編譯，但不一定可執行應用程式。這些應用程式僅適用於取得出現在文章中的範例程式碼。
Blazor 文章隨附的範例應用程式會針對下列案例來進行編譯並執行：
- 包含 EF Core 的 Blazor Server
- Blazor Server 和 Blazor WebAssembly 與 SignalR
- Blazor WebAssembly 已啟用範圍的記錄

如需存放庫中範例的詳細資訊和清單，請參閱 Blazor GitHub 存放庫範例 README.md 檔案。

ASP.NET Core 存放庫的基本測試應用程式也是各種 Blazor 案例的一組實用範例:

ASP.NET 核心參考來源 () 中的 BasicTestAppdotnet/aspnetcore

注意

若要下載範例應用程式：

下載 Blazor 範例存放庫 ZIP 檔案。
將檔案解壓縮。

位元組倍數

.NET 位元組大小會根據 1024 的乘冪使用非十進位位元組倍數的計量前置詞。

名稱 (縮寫)	大小	範例
Kilobyte (KB)	1,024 個位元組	1 KB = 1,024 個位元組
Megabyte (MB)	1,024² 個位元組	1 MB = 1,048,576 個位元組
Gigabyte (GB)	1,024³ 個位元組	1 GB = 1,073,741,824 個位元組

支援要求

只有文件相關問題會適用於 dotnet/AspNetCore.Docs 存放庫。 如需產品支援，請勿開啟文件問題。請透過下列一或多個支援管道來尋求協助：

如有架構潛在錯誤 (bug) 或產品意見反應，請在 dotnet/aspnetcore 問題針對 ASP.NET Core 產品單位提出問題。錯誤報告通常「需要」下列資訊：

清楚說明問題：在提出問題時，請遵循產品單位所提供的 GitHub 問題範本中的指示。
最小重現專案：將專案放在 GitHub 上，以供產品單位工程師下載並執行。將專案交叉連結至問題的開啟留言。

如需 Blazor 文章的潛在問題，請提出文件問題。若要開啟文件問題，請使用文章底部的開啟文件問題意見反應連結。為問題新增的中繼資料會提供追蹤資料，並自動偵測文章的作者。如果在開啟文件問題之前，產品單元已討論過該主題，請將工程問題的交叉連結放在文件問題的開放式留言中。

如有 Visual Studio 的問題或意見反應，請從 Visual Studio 內使用 [回報問題] 或 [建議功能] 態勢，以開啟 Visual Studio 的內部問題。如需詳細資訊，請參閱 Visual Studio 意見反應。

如有 Visual Studio Code 問題，請在社群支援論壇上尋求支援。如有錯誤報告和產品意見反應，請在 microsoft/vscode GitHub 存放庫上提出問題。

Blazor 文件中的 GitHub 問題會自動針對 Blazor.Docs 專案 (dotnet/AspNetCore.Docs GitHub 存放庫) 加上標記以進行分級。請稍候一會以取得回應，特別是遇到週末和假日時。如果是工作日，文件作者通常會在 24 小時內回應。

Blazor 資源的社群連結

如需社群所維護的 Blazor 資源的連結集合，請造訪有趣的 Blazor。

注意

Microsoft 未擁有、維護或支援有趣的 Blazor，以及該處所述和連結的大部分社群產品與服務。

共用方式為