@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/Furion_Teaching_Manual/17-/346/252/242/350/246/226/347/257/204/346/234/254/345/274/225/346/223/216.md

@@ -0,0 +1,327 @@
+# 17. 檢視/範本引擎
+
+## 17.1 關於檢視引擎
+
+檢視引擎負責根據檢視範本建立 HTML。檢視通常是 HTML 和程式語言的某種混合，支援變數定義、方法呼叫及邏輯編寫。
+
+在 Furion 框架中，底層整合了微軟提供的 Razor 檢視引擎元件並提供更加靈活方便的語法糖。
+
+---
+
+## 17.2 檢視引擎作用
+
+- 支援 ASP.NET Core 完整的 Razor 語法
+- 根據不同的資料編譯範本產生不同的輸出
+- 實現強大的外掛化機制
+- 實現全站頁面靜態化
+- 可以用作郵件範本、簡訊範本、優惠券資訊範本等
+
+---
+
+## 17.3 基礎使用
+
+### 17.3.1 註冊服務
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddViewEngine();
+}
+```
+
+### 17.3.2 使用方式
+
+**建構函式注入 `IViewEngine`：**
+
+```csharp
+using Furion.DynamicApiController;
+using Furion.ViewEngine;
+
+namespace Furion.Application
+{
+    public class ViewEngineService : IDynamicApiController
+    {
+        private readonly IViewEngine _viewEngine;
+
+        public ViewEngineService(IViewEngine viewEngine)
+        {
+            _viewEngine = viewEngine;
+            var result = _viewEngine.RunCompile("Hello @Model.Name", new { Name = "Furion" });
+        }
+    }
+}
+```
+
+**字串方式：**
+
+```csharp
+var result = "Hello @Model.Name".RunCompile(new { Name = "Furion" });
+```
+
+### 17.3.3 弱型別範本
+
+```csharp
+var result = _viewEngine.RunCompile("Hello @Model.Name", new { Name = "Furion" });
+// 結果：Hello Furion
+```
+
+> 支援非同步 `RunCompileAsync`。
+
+### 17.3.4 強型別範本
+
+```csharp
+namespace YourProject;  // Furion 4.8.4.16+ 支援無命名空間寫法
+
+public class TestModel
+{
+    public string Name { get; set; }
+    public int[] Items { get; set; }
+}
+```
+
+```csharp
+var result = _viewEngine.RunCompile(@"
+Hello @Model.Name
+@foreach(var item in Model.Items)
+{
+    <p>@item</p>
+}
+", new TestModel  // Furion 4.8.4.16+ 支援匿名型別
+{
+    Name = "Furion",
+    Items = new[] { 3, 1, 2 }
+});
+// 結果：Hello Furion <p>3</p> <p>1</p> <p>2</p>
+```
+
+> 支援非同步 `RunCompileAsync`。
+
+### 17.3.5 高效能範本快取 🥇
+
+由於範本編譯需要消耗大量的效能，建議使用帶 `FromCached` 結尾的 `RunCompileFromCached` 替代。呼叫該方法後會自動將範本編譯成 `.dll` 以便下次使用，減少第二次之後使用範本的效能損耗。
+
+```csharp
+var result = _viewEngine.RunCompileFromCached(@"
+Hello @Model.Name
+@foreach(var item in Model.Items)
+{
+    <p>@item</p>
+}
+", new TestModel
+{
+    Name = "Furion",
+    Items = new[] { 3, 1, 2 }
+});
+```
+
+呼叫 `RunCompileFromCached` 方法之後將會使用 MD5 加密範本並產生 `.dll` 存放在網站根目錄下的 `templates` 目錄中。只要範本內容不變，資料發生改變也不會重新編譯範本，大幅提升首次之後的效能。
+
+---
+
+## 17.4 進階用法
+
+進階用法支援將特定程式集、特定命名空間、特定型別引入到範本中使用。
+
+### 17.4.1 新增程式集
+
+```csharp
+var result = _viewEngine.RunCompileFromCached(
+    @"<div>@System.IO.Path.Combine(""Furion"", ""ViewEngine"")</div>",
+    builderAction: builder =>
+    {
+        builder.AddAssemblyReferenceByName("System.IO");
+    });
+// 結果：<div>Furion\\ViewEngine</div>
+```
+
+多種方式載入程式集：
+
+```csharp
+builder.AddAssemblyReferenceByName("System.Security"); // 透過名稱
+builder.AddAssemblyReference(typeof(System.IO.File));   // 透過型別
+builder.AddAssemblyReference(Assembly.Load("source"));  // 透過中繼資料參考
+```
+
+### 17.4.2 新增命名空間
+
+```csharp
+var result = _viewEngine.RunCompileFromCached(
+    @"<div>@Path.Combine(""Furion"", ""ViewEngine"")</div>",
+    builderAction: builder =>
+    {
+        builder.AddUsing("System.IO");
+        builder.AddAssemblyReferenceByName("System.IO");
+    });
+```
+
+也支援加入多個 `using`：
+
+```csharp
+builder.AddUsing("System.IO");
+builder.AddUsing("Furion");
+```
+
+### 17.4.3 定義範本方法
+
+```csharp
+var result = _viewEngine.RunCompileFromCached(@"
+<area>
+    @{ RecursionTest(3); }
+</area>
+
+@{
+  void RecursionTest(int level)
+  {
+    if (level <= 0) return;
+
+    <div>LEVEL: @level</div>
+    @{ RecursionTest(level - 1); }
+  }
+}
+");
+// 結果：
+// <div>LEVEL: 3</div>
+// <div>LEVEL: 2</div>
+// <div>LEVEL: 1</div>
+```
+
+### 17.4.4 呼叫類別方法
+
+定義 `CustomModel` 類別並繼承 `ViewEngineModel` 基底類別：
+
+```csharp
+public class CustomModel : ViewEngineModel
+{
+    public int A { get; set; }
+    public string B { get; set; }
+
+    public string Decorator(object value)
+    {
+        return "-=" + value + "=-";
+    }
+}
+```
+
+在範本中呼叫 `Decorator(value)` 方法：
+
+```csharp
+var content = @"Hello @A, @B, @Decorator(123)";
+
+var template = _viewEngine.Compile<CustomModel>(content);
+
+var result = template.Run(instance =>
+{
+    instance.A = 10;
+    instance.B = "Alex";
+});
+// 結果：Hello 10, Alex, -=123=-
+```
+
+---
+
+## 17.5 特殊字元處理
+
+如有特殊符號如 `<`、`<>`、`&` 等，可透過 `@("<")` 或 `@('<')` 進行原樣輸出：
+
+```csharp
+var str = "bool value = 1 @('<') 2";  // 源字串為：bool value = 1 < 2;
+```
+
+---
+
+## 17.6 字串範本替換引擎
+
+Furion 除了內建檢視引擎之外，還支援以下幾種範本替換：
+
+```csharp
+// 提供資料範本方式
+var str = "我叫{name}".Render(new Dictionary{ {"name", "Furion"} });
+var str = "我叫{Name}".Render(new { Name = "Furion" });
+var str = "我叫{Detail.Name}".Render(new { Detail = new { Name = "Furion" } });
+
+// 從設定讀取方式
+var str = "我叫#(Furion:Address)".Render();
+```
+
+對應設定檔：
+
+```json
+{
+  "Furion": {
+    "Address": "https://furion.net"
+  }
+}
+```
+
+---
+
+## 17.7 格式化規範範本
+
+在 Furion v3.5.3+ 新增了 `TP.Wrapper(...)` 規範範本：
+
+```csharp
+var template = TP.Wrapper("Furion 框架", "讓 .NET 開發更簡單，更通用，更流行。",
+    "##作者## 百小僧",
+    "##當前版本## v3.5.3",
+    "##文件位址## https://furion.net",
+    "##Copyright## 百小僧及百簽科技（廣東）有限公司");
+
+Console.WriteLine(template);
+```
+
+輸出：
+
+```
+┏━━━━━━━━━━━  Furion 框架 ━━━━━━━━━━━
+┣ 讓 .NET 開發更簡單，更通用，更流行。
+┣
+┣ 作者：        百小僧
+┣ 當前版本：     v3.5.3
+┣ 文件位址：     https://furion.net
+┣ Copyright：   百小僧及百簽科技（廣東）有限公司
+┗━━━━━━━━━━━  Furion 框架 ━━━━━━━━━━━
+```
+
+> **關於屬性產生**：如果列表項以 `##屬性名##` 開頭，自動產生 `屬性名：` 作為行首且自動等寬對齊。Furion 3.9.1 之前版本使用 `[屬性名]` 開頭。
+
+---
+
+## 17.8 產生矩形日誌範本
+
+> **版本說明**：僅限 Furion 4.8.8.25+ 版本使用。
+
+```csharp
+var template = TP.WrapperRectangle(new[] {
+    "百小僧",
+    "讓 .NET 開發更簡單，更通用，更流行。",
+    "一個應用程式框架，您可以將它整合到任何 .NET/C# 應用程式中。"
+});
+
+Console.WriteLine(template);
+```
+
+輸出：
+
+```
++-----------------------------------------------------------------------------+
+|                                   百小僧                                    |
+|                    讓 .NET 開發更簡單，更通用，更流行。                      |
+|         一個應用程式框架，您可以將它整合到任何 .NET/C# 應用程式中。           |
++-----------------------------------------------------------------------------+
+```
+
+還可以設定對齊方式：
+
+```csharp
+// 左對齊
+var template = TP.WrapperRectangle(texts, -1);
+
+// 置中對齊（預設）
+var template = TP.WrapperRectangle(texts, 0);
+
+// 右對齊
+var template = TP.WrapperRectangle(texts, 1);
+
+// 設定最長字串的追加長度
+var template = TP.WrapperRectangle(texts, 1, 20); // 最長字串長度 + 20
+```