9.2.3 .net core 通過TagHelper封裝控件

.net core 除了繼續保留.net framework的HtmlHelper的寫法以外，還提供了TagHelper和ViewComponent方式生成控件。

我們本節說的是使用TagHelper來生成控件。不過嚴格的說起來，TagHelper是對客戶端html元素的輔助類，例如渲染、增加服務端特性等。我們可以使用 taghelper 定義自己的標簽或更改已知標簽。使用TagHelper，VS.net編譯環境也可以自動感知，並提供智能提示。因為TagHelper生成的控件，看起來像一個原生的HTML標簽一樣，也更利於美工進行頁面美化。

例如一個lable控件 <label asp-for="Email"></label>，生成的最終html就是這樣：<label for="Email">[e-mail]</label>

 

如果要使用TagHelper，除了在頁面中using 命名空間之外，還需要使用@addTagHelper來使TagHelper可用。由於我們會編寫不止一個TagHelper，且在多個cshtml頁面使用，因此我們將如下代碼

@using MicroStrutLibrary.Presentation.Web.Controls

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

@addTagHelper *, MicroStrutLibrary.Presentation.Web.Controls

寫在視圖文件 Views/_ViewImports.cshtml中。寫在Views/_ViewImports.cshtml的意思是，默認所有的在 Views 和Views下級目錄中的視圖文件都可以使用TagHelper，通配符 ("*") 來指定在特定程序集（Microsoft.AspNetCore.Mvc.TagHelpers和MicroStrutLibrary.Presentation.Web.Controls）中的所有的 TagHelpers 在 Views目錄和子目錄中的視圖文件中都是可用的。第一個程序集是mvc自帶的，第二個是我們自己的控件程序集。具體的說明大家還是看.net core文檔吧。

 

下面，我們仍舊以上一節介紹的多選控件MultiSelect為例，說明下我們的TagHelper封裝過程。

MultiSelect在cshtml中的寫法如下，asp-dataSource傳入的是數據源，select的所有下拉內容都是通過datasource生成的，而asp-value傳入的是選中的項：

@model Dictionary<string, string>
@{ 
    List<string> values = ViewData.Get<List<string>>("Values");
}

<multiSelect id="txtInput0" asp-dataSource="@Model" asp-value="@values"></multiSelect> 

 

Model和values從controller中傳過來的，具體如下：

        public IActionResult MultiSelect()
        {
            Dictionary<string, string> data = new Dictionary<string, string>();
            data.Add("1", "Aaaaa");
            data.Add("2", "Aaron");
            data.Add("3", "Abbott");
            data.Add("4", "Abel");
            data.Add("5", "Abner");
            data.Add("6", "Abraham");
            data.Add("7", "Adair");
            data.Add("8", "Adam");
            data.Add("9", "Addison");

            List<string> value = new List<string>();
            value.Add("2");
            value.Add("7");
            ViewData["Values"] = value;

            return View(data);
        }

 

這樣，最終生成的html代碼和頁面如下：

<div>
  <select id="txtInput0" name="txtInput0" multiple="multiple">
    <option value="1" >Aaaaa</option>
    <option value="2" selected>Aaron</option>
    <option value="3" >Abbott</option>
    <option value="4" >Abel</option>
    <option value="5" >Abner</option>
    <option value="6" >Abraham</option>
    <option value="7" selected>Adair</option>
    <option value="8" >Adam</option>
    <option value="9" >Addison</option>
  </select>
  <script>
    require(['jquery', 'bootstrap', 'multiselect'], function ($) {
      $(function(){
        $("#txtInput0").multiselect({
            nonSelectedText: '請選擇',
            enableFiltering: true,//是否顯示過濾
            filterPlaceholder: '查找',
            includeSelectAllOption: true,//是否顯示全選
            selectAllText: '全選',
            numberDisplayed: 5//顯示條數
        });
          });
    });
  </script>
</div> 

 

MultiSelect在頁面展示如下圖

按照設計，MultiSelect應該能夠傳入：1、數據源，也就是下拉列表的所有數據；2、已選項，已選擇的數據；3、下拉列表的展示條數，以免條數過多，影響頁面；4、是否只讀等屬性，更好的控制控件的展示內容。當然了，還應該包括一個For屬性，這個For屬性的意思是通過頁面的Model綁定，自動生成控件Id和已選擇數據項等內容。

由於所有的TagHelper都繼承於一個基類TagHelper，我們首先看下TagHelper抽象類：

    //
    // 摘要:
    //     Class used to filter matching HTML elements.
    public abstract class TagHelper : ITagHelper
    {
        protected TagHelper();

        //
        // 備注:
        //     Default order is 0.
        public virtual int Order { get; }

        //
        public virtual void Init(TagHelperContext context);
        //
        // 摘要:
        //     Synchronously executes the Microsoft.AspNetCore.Razor.TagHelpers.TagHelper with
        //     the given context and output.
        //
        // 參數:
        //   context:
        //     Contains information associated with the current HTML tag.
        //
        //   output:
        //     A stateful HTML element used to generate an HTML tag.
        public virtual void Process(TagHelperContext context, TagHelperOutput output);
        //
        // 摘要:
        //     Asynchronously executes the Microsoft.AspNetCore.Razor.TagHelpers.TagHelper with
        //     the given context and output.
        //
        // 參數:
        //   context:
        //     Contains information associated with the current HTML tag.
        //
        //   output:
        //     A stateful HTML element used to generate an HTML tag.
        //
        // 返回結果:
        //     A System.Threading.Tasks.Task that on completion updates the output.
        //
        // 備注:
        //     By default this calls into Microsoft.AspNetCore.Razor.TagHelpers.TagHelper.Process(Microsoft.AspNetCore.Razor.TagHelpers.TagHelperContext,Microsoft.AspNetCore.Razor.TagHelpers.TagHelperOutput).
        public virtual Task ProcessAsync(TagHelperContext context, TagHelperOutput output);
    }

 

這里最重要的就是Process方法和ProcessAsync方法。這兩個方法，一個是同步，一個是異步，作用都是輸出頁面html代碼。

我們再來看封裝后的MultiSelectTagHelper的代碼：

    [HtmlTargetElement("multiSelect", Attributes = ForAttributeName)]
    [HtmlTargetElement("multiSelect", Attributes = ValueAttributeName)]
    [HtmlTargetElement("multiSelect", Attributes = ShowItemCountAttributeName)]
    [HtmlTargetElement("multiSelect", Attributes = DataSourceAttributeName)]
    [HtmlTargetElement("multiSelect", Attributes = ReadonlyAttributeName)]
    public class MultiSelectTagHelper : TagHelper
    {
        private readonly IHtmlGenerator generator;

        public MultiSelectTagHelper(IHtmlGenerator generator)
        {
            this.generator = generator;
        }

        private const string ForAttributeName = "asp-for";
        private const string ValueAttributeName = "asp-value";
        private const string ShowItemCountAttributeName = "asp-showItemCount";
        private const string DataSourceAttributeName = "asp-dataSource";
        private const string ReadonlyAttributeName = "asp-readonly";

        [HtmlAttributeNotBound]
        [ViewContext]
        public ViewContext ViewContext { get; set; }

        [HtmlAttributeName(ForAttributeName)]
        public ModelExpression For { get; set; }

        [HtmlAttributeName(ValueAttributeName)]
        public List<string> Value { get; set; }

        [HtmlAttributeName(ShowItemCountAttributeName)]
        public int ShowItemCount { get; set; } = 5;

        [HtmlAttributeName(DataSourceAttributeName)]
        public Dictionary<string, string> DataSource { get; set; }

        [HtmlAttributeName(ReadonlyAttributeName)]
        public bool Readonly { get; set; }

        public override void Process(TagHelperContext context, TagHelperOutput output)
        {
            MicroStrutLibraryExceptionHelper.IsNull(context, this.GetType().FullName, LogLevel.Error, "context參數值為空");
            MicroStrutLibraryExceptionHelper.IsNull(output, this.GetType().FullName, LogLevel.Error, "output");

            output.TagName = "div";
            //output.Attributes.Add("class", "multiselect-drop");

            MultiSelectList selectList = new MultiSelectList(this.DataSource, "Key", "Value", this.Value);

            HtmlContentBuilder builder = new HtmlContentBuilder();

            string id;
            if (For == null)
            {
                id = output.Attributes["id"].Value.ToString();
                output.Attributes.Remove(output.Attributes["id"]);

                string options = string.Empty;
                foreach (SelectListItem item in selectList)
                {
                    options += $"<option value=\"{item.Value}\" {(item.Selected ? "selected" : "")}>{item.Text}</option>";
                }

                builder.AppendHtml($"<select id=\"{id}\" name=\"{id}\" multiple=\"multiple\">{options}</select>");
            }
            else
            {
                id = For.Name;

                TagBuilder dropDown = generator.GenerateSelect(ViewContext, For.ModelExplorer, For.Name, string.Empty, selectList, true, null);
                builder.AppendHtml(dropDown);
            }

            string readOnly = "";
            if (this.Readonly)
            {
                readOnly = $"$('#{id} +div > button').attr('disabled', true);";
            }
            string script = string.Format(@"
<script>
require(['jquery', 'bootstrap', 'multiselect'], function ($) {{
    $(function(){{
        $(""#{0}"").multiselect({{
            nonSelectedText: '請選擇',
            enableFiltering: true,//是否顯示過濾
            filterPlaceholder: '查找',
            includeSelectAllOption: true,//是否顯示全選
            selectAllText: '全選',
            numberDisplayed: {1}//顯示條數
        }});
        {2}
    }});
}});
</script>
", id, this.ShowItemCount, readOnly);

            builder.AppendHtml(script);

            output.Content.AppendHtml(builder);

            base.Process(context, output);
        }
    }

 

為了在編寫程序時不會出錯，我們定義了五個常量ForAttributeName 、ValueAttributeName、ShowItemCountAttributeName、DataSourceAttributeName、ReadonlyAttributeName，分別代表MultiSelect標簽的asp-for等Attribute。也就是MultiSelect傳入的數據源、已選項、下拉列表的展示條數、是否只讀等屬性、For屬性。

 

類定義上面[HtmlTargetElement("multiSelect", Attributes = ValueAttributeName)]的作用是在multiSelect標簽上生成ValueAttributeName對應值asp-value的Attribute。

屬性上面

[HtmlAttributeName(ValueAttributeName)]

public List<string> Value { get; set; }

的作用是告訴multiSelect標簽，asp-value傳入的應該是個List<string>類型。這里需要注意的是，在各種文檔、教程中，大多數情況下，Attribute傳入的類型都是一些簡單類型，例如字符串、數字等。其實Attribute是可以傳入復雜的類型的，例如我們這里傳入的List<string>。頁面中也就要如下的使用方式：

@model Dictionary<string, string>
@{ 
    List<string> values = ViewData.Get<List<string>>("Values");
}

<multiSelect id="txtInput0" asp-dataSource="@Model" asp-value="@values"></multiSelect>

 

還有一個屬性ViewContext，這個屬性不是顯式傳入的，而是TagHelper創建時，系統自動賦值的，含義是當前的視圖執行上下文Microsoft.AspNetCore.Mvc.Rendering.ViewContext。

[HtmlAttributeNotBound]

[ViewContext]

public ViewContext ViewContext { get; set; }

 

這里還有一個需要重要說明的是For方式public ModelExpression For { get; set; }。普通方式下，multiSelect的Id、Value都是從頁面傳入的，但是For方式是與Model綁定的，如同HtmlHelper的TextBox、TextBoxFor的區別一樣。例如，一個人可能有多個職責，人的職責屬性是DutyList，所有職責的數據DutyDictionary，在cshtml頁面中就按照如下方式寫multiselect：

@model UserInfo

<multiSelect asp-dataSource="@DutyDictionary" asp-for="DutyList"></multiSelect>

 

MultiSelect構造函數中，傳入了一個IHtmlGenerator參數，這個是通過DI容器自動解析出來的，缺省情況下的實現類是DefaultHtmlGenerator。這個類的主要作用是生成各種html標簽。我們在For方式用到了自動生成select標簽的方法。TagBuilder dropDown = generator.GenerateSelect(ViewContext, For.ModelExplorer, string.Empty, For.Name, selectList, true, null);

 

最后就是重寫Process方法。其實這個方法還是比較簡單的，當For方式時，通過For自動生成select；否則就自己寫select。我們其中還寫了一段腳本，腳本中直接引用了jquery的MultiSelect腳本，

require(['jquery', 'bootstrap', 'multiselect'], function ($) {{…

這里我們使用systemjs這個通用的javascript模塊加載器，其中的jquery、bootstrap、multiselect都是在system.config中定義的。System.config.js的代碼大體如下，至於為什么這么寫，大家還是搜網上幫助吧：

    System.config({
        bundles: {
        },
        paths: {
            "external:": externalUrl+"/"
        },
        map: {
            "jquery": "external:lib/jquery/jquery.min.js",
            "bootstrap": "external:lib/bootstrap/js/bootstrap.min.js",

            //--
            "jquery-ui": "external:lib/jquery/jquery-ui/jquery-ui.bundle.min.js",

            //--Plugins
            "multiselect": "external:lib/plugins/multiselect/js/bootstrap-multiselect.min.js"
            …
},
        meta: {
            '*.css': {
                loader: 'external:lib/system/css-loader/css.js'
            },
            'jquery': {
                format: 'global',
                exports: 'jQuery'
            },
            'bootstrap': {
                format: 'global',
                deps: ['jquery']
            },
            'jquery-ui': {
                format: 'global',
                deps: ['jquery','./jquery-ui.min.css']
            },
            'multiselect': {
                format: 'global',
                deps: ['../css/bootstrap-multiselect.min.css']
            },
…
        },
        packages: {
            '/js': {
                format: 'cjs',
                defaultExtension: 'js'
            },

            //externals
            'external:js': {
                format: 'cjs',
                defaultExtension: 'js'
            }
        }
    });

    //amd require
    window.require = System.amdRequire;

至此，一個基本的Taghelpr就完成了。

在ASP.NET Core MVC中應該使用 TagHelpers 來替換 HtmlHelpers，因為它們更加的簡潔和容易使用。另一個巨大的好處就是依賴注入，在HtmlHelpers中是使用不了的，因為HtmlHelpers 擴展的都是靜態內容。 但TagHelpers是一個公共類，我們可以很容易的在它的構造函數中注入服務。

 

進階：資源性視圖的應用

按照上節的慣例，我們依舊還一個進階，說明下在TagHelper中如何使用cshtml，以及cshtml作為嵌入的資源該如何寫。

我們從上面MultiSelectTagHelper類中將Process方法的頁面代碼拼接程序提取出來，寫成cshtml如下

@{
    string id = ViewData["Id"].ToString();
    int showItemCount = (int)ViewData["ShowItemCount"];
    bool isReadonly = (bool)ViewData["Readonly"];
}

<script>
    require(['jquery', 'bootstrap', 'multiselect'], function ($) {
        $(function(){
            $("#@id").multiselect({
                nonSelectedText: '請選擇',
                enableFiltering: true,//是否顯示過濾
                filterPlaceholder: '查找',
                includeSelectAllOption: true,//是否顯示全選
                numberDisplayed: @(showItemCount),//顯示條數
                selectAllText: '全選'
            });
            @if (isReadonly)
        {
            @:$("#@id +div > button").attr("disabled", true);
                    }
        });
    });
</script>

 

這樣MultiSelectTagHelper類中就簡化成如下：

    [HtmlTargetElement("multiSelect", Attributes = ForAttributeName)]
    [HtmlTargetElement("multiSelect", Attributes = ValueAttributeName)]
    [HtmlTargetElement("multiSelect", Attributes = ShowItemCountAttributeName)]
    [HtmlTargetElement("multiSelect", Attributes = DataSourceAttributeName)]
    [HtmlTargetElement("multiSelect", Attributes = ReadonlyAttributeName)]
    public class MultiSelectTagHelper : TagHelper
    {
        private readonly IHtmlGenerator generator;
        private readonly IUrlHelperFactory factory;
        private readonly IHtmlHelper htmlHelper;

        public MultiSelectTagHelper(IHtmlHelper htmlHelper, IHtmlGenerator generator)
        {
            this.generator = generator;
            this.factory = factory;
            this.htmlHelper = htmlHelper;
        }

        private const string ForAttributeName = "asp-for";
        private const string ValueAttributeName = "asp-value";
        private const string ShowItemCountAttributeName = "asp-showItemCount";
        private const string DataSourceAttributeName = "asp-dataSource";
        private const string ReadonlyAttributeName = "asp-readonly";

        [HtmlAttributeNotBound]
        [ViewContext]
        public ViewContext ViewContext { get; set; }

        [HtmlAttributeName(ForAttributeName)]
        public ModelExpression For { get; set; }

        [HtmlAttributeName(ValueAttributeName)]
        public List<string> Value { get; set; }

        [HtmlAttributeName(ShowItemCountAttributeName)]
        public int ShowItemCount { get; set; } = 5;

        [HtmlAttributeName(DataSourceAttributeName)]
        public Dictionary<string, string> DataSource { get; set; }

        [HtmlAttributeName(ReadonlyAttributeName)]
        public bool Readonly { get; set; }

        public override void Process(TagHelperContext context, TagHelperOutput output)
        {
            MicroStrutLibraryExceptionHelper.IsNull(context, this.GetType().FullName, LogLevel.Error, "context參數值為空");
            MicroStrutLibraryExceptionHelper.IsNull(output, this.GetType().FullName, LogLevel.Error, "output");

            output.TagName = "div";
            //output.Attributes.Add("class", "multiselect-drop");

            MultiSelectList selectList = new MultiSelectList(this.DataSource, "Key", "Value", this.Value);

            HtmlContentBuilder builder = new HtmlContentBuilder();

            string id;
            if (For == null)
            {
                id = output.Attributes["id"].Value.ToString();
                output.Attributes.Remove(output.Attributes["id"]);

                string options = string.Empty;
                foreach (SelectListItem item in selectList)
                {
                    options += $"<option value=\"{item.Value}\" {(item.Selected ? "selected" : "")}>{item.Text}</option>";
                }

                builder.AppendHtml($"<select id=\"{id}\" name=\"{id}\" multiple=\"multiple\">{options}</select>");
            }
            else
            {
                id = For.Name;

                TagBuilder dropDown = generator.GenerateSelect(ViewContext, For.ModelExplorer, null, For.Name, selectList, true, null);
                builder.AppendHtml(dropDown);
            }

            output.Content.AppendHtml(builder);

            //Contextualize the html helper
            (htmlHelper as IViewContextAware).Contextualize(ViewContext);

            ViewDataDictionary data = new ViewDataDictionary(this.ViewContext.ViewData);
            data["Id"] = id;
            data["ShowItemCount"] = this.ShowItemCount;
            data["Readonly"] = this.Readonly;
            
            var content = htmlHelper.Partial("TagHelpers/MultiSelect/MultiSelect", data);
            output.Content.AppendHtml(content);

            base.Process(context, output);
        }
    }
}

 

大家可能注意到構造函數中我們增加了個參數IHtmlHelper htmlHelper。這個參數是之前MVC的HtmlHelper，我們通過DI方式直接獲取到htmlhelper。然而，此時DI獲取的htmlhelper還無法使用，必須通過(htmlHelper as IViewContextAware).Contextualize(ViewContext);將上下文信息傳入HtmlHelper。var content = htmlHelper.Partial("TagHelpers/MultiSelect/MultiSelect", data); output.Content.AppendHtml(content);這兩句話執行cshtml頁面，將最終頁面的內容呈現在TagHelper中。

這里還有一個問題，就是我們將所有的控件都存放到一個應用程序集中，控件的cshtml頁面也會以資源方式打包進應用程序集中。我們控件的項目結構如下：

MultiSelect的內容如下，有2個文件，一個cshtml，一個是taghelper程序。其他目錄的結構也是類似的。

新的.net core的嵌入資源方式需要在project.json中按照如下方式編寫：

"buildOptions": {

"embed": [ "Components/**/*.cshtml", "TagHelpers/**/*.cshtml" ]

}

這里的意思是我們將所有components和taghelpers目錄下的第二級子目錄下的所有cshtml文件以嵌入方式打包進應用程序集中。在.net core中使用應用程序集中嵌入的文件，還算是比較方便。因為.net core已經把許多可擴展的內容開放出來了。

我們這里寫了一個擴展方法，在RazorViewEngineOptions（RazorViewEngine程序方式的配置）中增加一個Razor視圖文件的定位器EmbeddedFileProvider。EmbeddedFileProvider就可以獲取應用程序集中嵌入的cshtml文件，構造函數第一個參數是包含嵌入cshtml文件的應用程序集，第二個參數是命名空間。

    public static class EmbeddedViewServiceCollectionExtensions
    {
        public static IServiceCollection AddEmbeddComponentView(this IServiceCollection services)
        {
            if (services == null)
            {
                throw new ArgumentNullException(nameof(services));
            }

            EmbeddedFileProvider fileProvider = new EmbeddedFileProvider(typeof(EmbeddedViewServiceCollectionExtensions).GetTypeInfo().Assembly, "MicroStrutLibrary.Presentation.Web.Controls");

            services.Configure<RazorViewEngineOptions>(options => {
                options.FileProviders.Add(fileProvider);
            });

            return services;
        }
    }

 

接下來就是在Startup.cs中使用這個擴展方法：

public void ConfigureServices(IServiceCollection services)
{
     services.AddMvc(options =>
        {
            …
        });

    services.AddEmbeddComponentView();
}

 

現在才發現，其實生成select標簽部分也是應該放到csthml中的，而不是在taghelper中生成，就不改了啊:)。

這里主要有幾個小技巧再提示下：

1、cshtml頁面中，Taghelper的Attribute可以傳入各種復雜對象，而不是string\int\bool等簡單類型

2、TagHelper如果使用cshtml，則應該使用IHtmlHelper

3、嵌入資源方式的cshtml，需要使用embeddedfileprovider。

 

面向雲的.net core開發框架