ASP.NET Core Blazor 基本概念

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

用戶端和伺服器轉譯概念

在整份 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 事件允許使用者互動功能，且 Razor 架構會維護 Blazor 元件狀態。

• 預先轉譯是伺服器上初始轉譯頁面內容，而不需要為轉譯的控制項啟用事件處理常式的程序。 伺服器會盡快輸出頁面的 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 路由和導覽。
• 使用多個版本的元件時，元件會循序編號。 例如，在 FileUpload3 到達 /file-upload-3 元件。
• 元件定義 (Razor) 頂端的 會按下列順序放置：.razor file、@page (.NET 8 或更新版本)、@rendermode 陳述式、按字母順序排列的其他指示詞。
• 雖然 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 變數的值。

文件物件模型 (DOM)

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

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

• DOM 簡介 (MDN 文件)
• 層級 1 文件物件模型規格 (W3C)

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

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

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

• 類別庫：用戶端瀏覽器相容性分析器
• 將 API 標註為在特定平台上不受支援 (dotnet/designs GitHub 存放庫

範例應用程式

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

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

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

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

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

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

若要下載範例應用程式：

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

位元組倍數

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

支援要求

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

• 堆疊溢位 (標籤：blazor)
• 一般 ASP.NET Core Slack 小組
• Blazor Gitter

如有架構潛在錯誤 (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。