ASP.NET Core – ViewComponent

前言

以前写过 , 这篇作为翻新版.

参考

Docs – View components in ASP.NET Core 

介绍

View Component 是 Partial View 的升级版本. 区别就是它多了一个 .cs 可以写逻辑.

Overview

View Component 是由一个 class (.cs) 和一个 View (.cshtml) 组成的.

Component 有名字, View 也有名字, 在某个 Page/View 中想使用 Component 就通过名字召唤它

然后 Component 又会去找寻它的 View 做渲染.

ASP.NET Core 有一套命名机制去声明是否一个 class 属于 View Component, 也有一套机制去寻找 Component 的 View.

我呢是很讨厌这些机制的, 因为它们设计的不直观. 经常莫名其妙的找不到, 需要死背它那不直观的设计才能用好. 但幸好我们可以通过一些 best practice 去规定使用的方式, 这样就不会老是搞错了.

Create View Component Class

两个点需要注意,

第一点是如果告诉 ASP.NET Core 这个 class 是一个 ViewComponent 

第二点是这个 Component 的名字是什么.

第一种: 继承 ViewComponent class

public class CallToAction : ViewComponent

class name CallToAction 自动成为 component name, 如果 class name ends with "ViewComponent" 则会被忽略

比如: CallToActionViewComponent 最终的 component name 依然是 CallToAction.

第二种: class name ends with "ViewComponent"

public class CallToActionViewComponent

component name = CallToAction

例外

由于第二种方式是通过命名, 这就导致会出现一些例外. 比如

[NonViewComponent]
public class ReviewComponent

这时需要通过 NonViewComponentAttribute 声明这不是一个 ViewComponent

第三种: 通过 ViewComponentAttribute

[ViewComponent(Name = "CallToAction")]
public class CallToAction

这也是唯一一个自定义 component name 的方式, 如果没有定义, 那么它依然是通过 class name auto become component name.

如果 Name = "CallToActionViewComponent" 那么最终就是 "CallToActionViewComponent" ViewComponent 只有在 class name auto become component name 时会被忽视.

Best Practice

上面这些方式是可以混用的哦, 但是搞那么多方除了乱以外没有任何好处.

我的建议:

1. 通过继承 ViewComponent 来让 ASP.NET Core 知道这个 class 是 View Component, 继承的好处是可以用 build-in 的功能, 比如 return View()

2. class name 命名规范最好是 CallToActionViewComponent, 最终 component name 是 CallToAction

Implement Invoke Method

ViewComponent class 必须实现 Invoke 或 InvokeAsync 方法, 不然会报错

很奇葩的地方是它并不是 interface of ViewComponent class 哦, 所以不是 override method, 它就是一个你要自己知道的方法. 也只有在 runtime 会报错. 设计的真烂.

public class CallToActionViewComponent : ViewComponent
{
    public IViewComponentResult Invoke()
    {
        return View();
    }
}

View (.cshtml) 查询

下面 3 个是默认查询的地方.

Component name 上面提到了, view name 默认是 "Default" (不要问我为什么不是 Index)

所以上面 Component 对应的 View Localtion 是

Views/Shared/Components/CallToAction/Default.cshtml

可以通过 options 添加更多匹配的路径.

{0} 就是最终的 view name 

查看 ViewViewComponentResult.cs 源码, 可以看到它 hardcore 了 format "Components/{0}/{1}", 0 = component name, 1 = view name.

然后通过 viewEngine 去找. 而 Options 的 ViewLocationFormats 是添加给 viewEngine 用的. 但是无论如何你都避不开它 hardcode 的 "Components/{0}/{1}"

viewEngine 的所有 format 可以通过 RazorViewEngineOptions 查看

var razorViewEngineOptions = app.Services.GetRequiredService>().Value;

下面是 MVC, RazorPages 的所有默认 format

它的玩法是定义一些 format, 然后 viewEngine.FindView 的时候会把 parameter 丢进去成为最终的路径.

ViewLocationExpanders 是一个动态 generate format 的方式. 几年前有写过, 大概长这样:

context 可以看到什么 Page 调用了这个 Component, 然后 viewName 就是 hardcode 的 component format.

viewLocations 是默认的 3 个 formats.

虽然 ViewLocationExpanders 比 ViewLocationFormats dynamic 多一些, 但是很多时候还是不够用的, 因为它也拿不到 component 的 physical file path.

比如, 我的 folder 结构是 MyViewComponent > MyViewComponent.cs + Index.cshtml

同一个 folder 里面有 component class 和 view

由于我拿不到 component 的 physical 路径, 也就没有办法设定成 "{MyViewComponent.cs 路径}Index.cshtml"

MVC 其实也是同样的局限. Router 找到 Controller 以后, Controller 也只能通过 ControllerName 找到 View 没办法依据 physical file path.

Best Practice

我的建议是直接写绝对路径, 或者固定好 component 的 folder 位置. 然后写一个 ViewLocationExpanders 去扩展它.

public class PageTitleSectionComponent : ViewComponent
{
    public IViewComponentResult Invoke(PageTitleSectionComponentViewModel viewModel)
    {
        return View(
            $"~/Web/Shared/Component/PageTitleSection/Index.cshtml", viewModel
        );
    }
}

调用

有 3 种调用方式

@await Component.InvokeAsync("CallToAction", new { myName = "test1" })
@await Component.InvokeAsync(typeof(CallToActionViewComponent)) 
<vc:call-to-action my-name="test2">vc:call-to-action>

一个通过 component name (string), 一个用 type, 一个用 tag helper (记得要 @addTagHelper 哦)

也是一样, 搞一堆来乱而已. 我个人的建议是使用 Type 的方式. 这样可以避开 PascalCase convert kebab-case 的问题.

想传入 parameter 就通过匿名对象, 它这个方式也是很烂, 类型在 compile 时无法检测.

public IViewComponentResult Invoke(string myName = "abc")

想 passing html 内容也是可以, 类似 Angular 的 ng-content

定义 Templated Razor delegates

@{
  Func<string, object> content =
        @<div>
          <p>@itemp>
        div>
  ;
}
@await Component.InvokeAsync(typeof(CallToActionViewComponent), new { content = content })

Func string 是 @item 的类型.

把委托当普通参数传进去 View Component.

public class CallToActionViewComponent : ViewComponent
{
    public IViewComponentResult Invoke(Func<string, object> content)
    {
        return View(content);
    }
}

在通过 ViewModel 传给 View.

最后在 View 执行就可以了

@model Func<string, object>

@Model("item1")
<h1>Hello Worldh1>

注: Templated Razor delegates 只能一个 tag, 如果想传入多个 tag 可以用 List> 来装, 然后传进去, 虽然很麻烦但是勉强能用. 有个相关的 Issue 但没有理了