孔良去年我接手一个 C# ASP.NET MVC 项目，首页某个用户卡片被复制粘贴了 8 份。每次产品经理想调卡片宽度、改头像圆角，我就得打开所有页面挨个改，稍漏一个，线上就会同时出现新旧两种样式。后来我把这块 UI 抽成了局部视图，页面里只剩一行 @Html.Partial，才真正体会到什么叫“复用 UI 的正确姿势”。局部视图不是多高深的东西，它能在不引入复杂前端框架的前提下，让 Razor 里的重复结构彻底收敛。如果你正在做 ASP.NET MVC 或 Razor Pages，却还在用复制粘贴维护相似 HTML，今天这篇可以直接帮你把 @Html.Partial 从“见过”变成“用得明白”，我会把常用姿势、四个方法变体、数据传递，以及我实际踩过的坑一次说清楚。
1. 为什么局部视图在 C# ASP.NET 里存在感这么强
在讲 @Html.Partial 之前，先想一个问题：布局页 _Layout.cshtml 已经能复用页面骨架了，为什么还需要局部视图？因为布局页复用的是“壳”，页面内部的结构差异太大，一个通用壳根本管不了。这时候，你真正需要的是把页面内部的一小块 UI 拆出去，而局部视图就是干这个的。
1.1 从复制粘贴 UI 到组件化
在没有局部视图的时候，列表项、用户卡片、按钮组这类小块 UI 会在多个页面里反复出现。最原始的维护方式就是复制粘贴，改一处漏三处。后来大家开始在 Views/Shared 下建 _Partial.cshtml，用 @Html.Partial 把文件引入。你可以把局部视图理解成“HTML 片段函数”：传入一个模型，输出一段标记，调用方只负责传数据，不关心片段内部长什么样。
这里有个关键认知：局部视图不是页面，没有 <html>、<body>、@RenderBody() 这些结构，它只是页面里的一个零件。Razor 引擎遇到 @Html.Partial 时，会把指定 .cshtml 文件渲染成一段 HTML，再嵌入到当前页面的输出流中。整个过程不经过 Controller，不经过路由，纯粹是视图引擎层面的组合。
1.2 局部视图、布局页和分部渲染，三者到底怎么分
我见过不少初学者把 _Layout.cshtml 和局部视图混为一谈。布局页是“整栋房子的承重墙和户型”，定义了全局导航、页脚、<html> 和 <body>，通过 @RenderBody() 留出内容区域。局部视图是“家具模块”，比如一张桌子、一组抽屉，只负责自己那一块，不关心整体格局。
@Html.Partial、@Html.RenderPartial 属于“分部渲染”操作，它们是把局部视图“搬运”到当前页面的动作。真正在 ASP.NET MVC 里还有一个更重的方案叫 Html.Action/Html.RenderAction（MVC 5 时代）和 ViewComponent（MVC Core 时代），它们会走控制器方法或独立组件逻辑，能拉数据库、做权限判断。而局部视图本身没有独立的数据获取能力，数据必须由调用方传进来。
1.3 适合用它，也有明确不适合的场景
适合用局部视图的场景很典型：重复的卡片、表格行、分页条、按钮组、表单字段集合、Tab 头、轮播图 slide，这些纯展示型片段，只要数据准备好，塞进局部视图最合适。
不适合的场景也很清晰：如果某个片段需要访问数据库、需要独立鉴权、需要根据路由参数自己找数据，那就别硬用局部视图。否则你会发现，为了给局部视图造数据，每个调用方 Controller 里都要重复写一段查询逻辑，这等于把 UI 的复用问题变成了数据准备的重复问题。这时候更合适的是 ViewComponent，或者至少用 Html.Action 走一次独立的 Controller Action。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 先分清 @Html.Partial 的四兄弟：名字像，行为差距很大
@Html.Partial 不是孤立的方法。它还有三个近亲：@Html.RenderPartial、@Html.PartialAsync、@Html.RenderPartialAsync。这四个方法名字差几个词，行为差异却很大。很多老项目里混用，出了性能问题都不知道怎么回事。
2.1 Partial 和 RenderPartial：一个返回字符串，一个直接写响应
@Html.Partial("_UserCard", user) 返回的是 IHtmlContent 或 MvcHtmlString（版本不同略有差异），Razor 拿到这个对象后再写入当前输出流。@{ Html.RenderPartial("_UserCard", user); } 返回 void，内部直接把内容写进当前 TextWriter，不产生中间的字符串对象。
用代码看更清楚。下面两种写法效果一样：
cshtml复制@Html.Partial("_UserCard", Model.CurrentUser)
cshtml复制@{ Html.RenderPartial("_UserCard", Model.CurrentUser); }
但 Partial 多一道“先渲染成字符串，再写入”的工序。如果你只是在页面上输出片段，RenderPartial 少了中间分配，性能略好；如果你需要把这个片段放到变量、拼接进字符串，或者根据片段内容做条件判断，那只能用 Partial。
2.2 异步版本 PartialAsync 和 RenderPartialAsync 什么时候用
在 ASP.NET Core 中，局部视图还有异步版本。@await Html.PartialAsync("_UserCard", user) 返回 Task<IHtmlContent>，适合局部视图内部需要异步读取数据的情况；@{ await Html.RenderPartialAsync("_UserCard", user); } 返回 Task，同样直接写入响应流。
需要注意，异步版本不是“更高级”的同步版本，它依赖调用方在视图里 await，如果局部视图本身没有做异步操作，用同步版本反而更直观。而且 RenderPartialAsync 不能在 Razor 里直接 @Html.RenderPartialAsync(...) 这样调用，因为它返回 Task，不产生输出对象，必须在 @{ } 代码块里 await。
2.3 一张表理清四兄弟的适用边界
| 方法 | 返回类型 | 写入方式 | 典型用法 | 主要场景 |
|---|---|---|---|---|
Html.Partial |
IHtmlContent / MvcHtmlString |
返回片段，Razor 负责输出 | @Html.Partial("_X", model) |
需要在表达式中使用片段 |
Html.RenderPartial |
void |
直接写入当前响应流 | @{ Html.RenderPartial("_X", model); } |
高频循环/大型片段，减少中间分配 |
Html.PartialAsync |
Task<IHtmlContent> |
返回片段 | @await Html.PartialAsync("_X", model) |
局部视图需要异步获取数据 |
Html.RenderPartialAsync |
Task |
直接写入当前响应流 | @{ await Html.RenderPartialAsync("_X", model); } |
异步 + 高吞吐且不需要操作片段对象 |
选择逻辑很简单：拿到片段对象后再决定怎么处理，就选 Partial 或 PartialAsync；只要“渲染出来输出掉”，优先考虑 RenderPartial 或 RenderPartialAsync。在 Razor Pages 项目中，这些方法的可用性略有差异，但核心行为一致。
3. 从零到一：搭一个可以反复调用的用户卡片局部视图
理论讲完，直接做一个可复用的例子。假设项目里到处都需要展示用户基本信息，包括头像、昵称、简介和等级，我把它做成一个局部视图。
3.1 建局部视图文件和模型
先在 Models 下定义一个视图模型：
csharp复制public class UserSummaryViewModel
{
public string Name { get; set; }
public string Bio { get; set; }
public string AvatarUrl { get; set; }
public int Level { get; set; }
}
然后在 Views/Shared/ 下新建 _UserCard.cshtml，文件名以下划线开头，这是局部视图的约定，能让别人一眼看出它不是完整页面：
cshtml复制@model UserSummaryViewModel
<div class="user-card">
<div class="user-card__avatar">
@if (!string.IsNullOrEmpty(Model.AvatarUrl))
{
<img src="@Model.AvatarUrl" alt="@Model.Name 的头像" />
}
else
{
<span>@Model.Name.Substring(0, 1)</span>
}
</div>
<div class="user-card__info">
<h3>@Model.Name</h3>
<p>@Model.Bio</p>
<span class="badge">等级 @Model.Level</span>
</div>
</div>
这里我故意没写任何复杂逻辑，局部视图的核心价值就是“把一段确定的 HTML 片段管理起来”。如果你在局部视图里堆大量 C# 代码、访问数据库、做权限判断，那它就变味了。
3.2 三种调用方式与路径搜索规则
页面里想引入这个片段，三种方式都可以：
cshtml复制@Html.Partial("_UserCard", new UserSummaryViewModel { Name = "张三", Bio = "老程序员", Level = 12 })
cshtml复制@{ Html.RenderPartial("_UserCard", Model.CurrentUser); }
cshtml复制@await Html.PartialAsync("_UserCard", Model.CurrentUser)
调用时传入的名称 "_UserCard" 不是随便写的，Razor 视图引擎会按固定顺序搜索：先找当前 Controller 对应的 Views/当前控制器名/ 目录，找不到就找 Views/Shared/ 目录。如果你把局部视图放在 Views/Shared/_UserCard.cshtml，任何控制器和页面都能引用。
如果你明确知道文件位置，也可以写绝对路径：
cshtml复制@Html.Partial("~/Views/Shared/_UserCard.cshtml", user)
这样能绕开搜索规则，但会让代码变脆，一旦移动文件就要改所有引用。我一般只用短名称，靠 Shared 目录承担全局复用。
3.3 在列表循环里复用同一个 UI 片段
局部视图真正发力的场景是循环渲染。一个用户列表页面，不需要在每次循环里写一大段卡片 HTML，直接复用同一个片段：
cshtml复制@model List<UserSummaryViewModel>
<h2>团队成员</h2>
@foreach (var user in Model)
{
<div class="row-item">
@Html.Partial("_UserCard", user)
</div>
}
这样最直接的好处是：卡片样式和结构的唯一事实来源在 _UserCard.cshtml 里，列表页只是“提供数据 + 决定排列方式”。下次产品经理说卡片加个“在职状态”标签，我只需要改一个文件，所有页面同步生效。
这个场景里我推荐用 RenderPartial，因为 foreach 循环中 Partial 会为每一次循环生成一个中间字符串对象，列表很长时会产生额外 GC 压力。虽然通常差距不大，但既然 RenderPartial 也一样直观，没必要给 GC 添负担。
4. 数据传递的几种姿势：强类型、dynamic 与 ViewData 的取舍
局部视图能否稳定工作，一半取决于数据怎么传进去。这里方法很多，但每条路都有坑。
4.1 强类型 Model：最稳，也最推荐
如果局部视图文件顶部写了 @model UserSummaryViewModel，那么调用时必须传 UserSummaryViewModel 或它的子类：
cshtml复制@Html.Partial("_UserCard", Model)
强类型的优点很明显：编译期类型检查，属性名拼错了直接报错；编辑器有智能提示，写起来省心；后期改模型，编译器会提醒你所有需要同步的地方。对于团队项目，我都建议能强类型就强类型。
4.2 dynamic / ViewBag 的方便与隐患
有些局部视图不想依赖具体模型，就把顶部写成 @model dynamic。调用时可以传一个匿名对象：
cshtml复制@Html.Partial("_UserCard", new { Name = "李四", Bio = "临时数据", AvatarUrl = "", Level = 3 })
局部视图内部照样通过 Model.Name 访问，因为 dynamic 是运行时绑定。看起来很方便，但隐患也在这里：如果一个调用方少传了 AvatarUrl，编译期不会报错，运行到 @Model.AvatarUrl 时才抛 Microsoft.CSharp.RuntimeBinder.RuntimeBinderException，而且报错位置往往不在调用处，排查起来费劲。
再说 ViewBag。局部视图默认会继承父页面的 ViewData，所以你在父视图中设置的 ViewBag 值，局部视图里能直接读到。这很方便，但也制造了隐式耦合——局部视图依赖一个“外面碰巧存在的值”，换个人来维护根本不知道数据从哪来的。我的建议是：局部视图里可以读 ViewBag 做辅助渲染，但核心数据一定要走强类型 Model 传入。
4.3 用 ViewData 给局部视图传辅助参数
有些时候，你需要同时传一个模型和几个辅助参数。比如 Tab 切换组件，既要传列表数据，又要告诉局部视图当前激活哪个 Tab：
cshtml复制@{
var tabViewData = new ViewDataDictionary(ViewData)
{
["ActiveTab"] = "overview"
};
}
@Html.Partial("_TabView", tabViewModel, tabViewData)
局部视图内部可以这样取：
cshtml复制@model TabViewModel
@{
var activeTab = ViewData["ActiveTab"]?.ToString() ?? "";
}
<div class="tab-list @activeTab">...</div>
这里有一个细节：new ViewDataDictionary(ViewData) 先复制了当前页面的 ViewData，再往副本里塞辅助参数。如果不复制，直接用同一个 ViewData 字典，局部视图内部如果对某个键做了修改，会反向影响父页面后续的渲染。这种“副作用”很难查，所以宁可多写一行 new。
4.4 循环复用时的数据隔离问题
在循环里反复调用局部视图时，数据隔离更要小心。假设局部视图内部读取了 ViewData["Index"]，第一次循环把它设置为 "1"，第二次循环开始时字典里还留着这个值，可能就会渲染出错误的下标。
解决办法有两种：一种是尽量把需要的数据都放进强类型 Model，不依赖 ViewData；另一种是每次调用时都用 new ViewDataDictionary 构造独立的字典：
cshtml复制@for (var i = 0; i < Model.Count; i++)
{
var data = new ViewDataDictionary(ViewData) { ["Index"] = i.ToString() };
@Html.Partial("_ListItem", Model[i], data)
}
如果你不需要 ViewData，最干净的做法是直接 new ViewDataDictionary()，彻底切断与父页面的数据共享。
5. 最容易踩的坑：表单嵌套、脚本重复、路径与编码
局部视图用多了，会踩到一些不仔细看根本发现不了的问题。这些问题在文档里很难找到完整答案，基本都是运行时才暴露。
5.1 局部视图里的 form 会引发嵌套表单
这是局部视图最容易惹的祸。有人习惯把“一个表单”完整封装成局部视图，里面有 @using (Html.BeginForm()) {...}。如果父页面本身已经在一个 <form> 里，再渲染这个局部视图，就会生成嵌套的 <form>。浏览器对嵌套表单的处理方式是忽略内层表单的开始标签，但内层表单里的按钮和提交行为会变得完全不可控。
我遇到过一个真实案例：一个局部视图里封装了“子项目编辑表单”，父页面是“主项目编辑表单”，团队里另一个同事在同一个页面里先后引用了两者。上线后，子项目的保存按钮点击后，数据总是被主表单的 Action 接管，后台收到一堆乱七八糟的字段。排查了大半天才发现是嵌套 form。
正确做法是：局部视图只渲染表单字段，不渲染 <form> 标签本身。整个页面只有一个外层 <form>，局部视图负责把 Name、Bio 这些字段输出出来：
cshtml复制@model UserSummaryViewModel
<form asp-action="SaveUser" method="post">
<input type="hidden" name="UserId" value="@Model.Id" />
@Html.Partial("_UserFormFields", Model)
<button type="submit">保存</button>
</form>
如果局部视图确实需要独立表单，那调用方页面就不要在外面再套 form。
5.2 为什么局部视图里加 @section Scripts 不生效
布局页里常会定义 @RenderSection("Scripts", required: false)，普通视图可以往里面塞脚本。但局部视图里用 @section Scripts { ... } 是无效的，因为局部视图没有布局上下文，section 只能出现在依赖布局页的完整视图中。
很多人到这里就顺手把 <script> 写在局部视图内部，结果同一个局部视图在页面里被引用三次，脚本就执行三次；如果脚本里绑定了事件，事件也会注册多次。修复思路有两种：
一是把需要绑定的元素都加上 data- 自定义属性，然后在父页面的 @section Scripts 里统一初始化：
cshtml复制<!-- 局部视图中只输出 data 属性标记 -->
<div class="user-card" data-user-card="@Model.UserId" data-initialized="false">
...
</div>
父页面脚本：
javascript复制$(function () {
$('[data-user-card]').each(function () {
if ($(this).data('initialized')) return;
$(this).data('initialized', true);
// 初始化交互
});
});
第二种是对局部视图做幂等处理，让脚本无论执行多少次都不会重复累计事件。我的习惯是：局部视图尽量不写 <script>，所有交互统一交给父页面的初始化脚本，用 data- 属性把数据和 DOM 关联起来。
5.3 路径问题：相对路径、虚拟路径和 Areas 搜索顺序
局部视图里的图片、链接路径，一旦脱离当前页面环境就可能失效。比如局部视图里写 <a href="/profile/123">个人资料</a>，如果页面访问地址是站点根目录下，没问题；但当这个局部视图被 Ajax 返回的 HTML 片段插入到另一个目录层级的路由页面时，就可能导致路径错误。正确的做法是在局部视图里用 Url.Content 生成绝对虚拟路径：
cshtml复制<a href="@Url.Content("~/profile/123")">个人资料</a>
另外，在 Areas 项目里，局部视图的搜索顺序和普通页面不太一样。如果你在 Areas/Admin/Views/Shared/ 下放了一个 _UserCard.cshtml，又在根级 Views/Shared/ 下放了同名文件，Admin 区域里的页面引用 _UserCard 时，会先找 Areas/Admin/Views/当前控制器/，再找 Areas/Admin/Views/Shared/，最后才找根级 Views/Shared/。千万不要依赖这个顺序来“覆盖”名称相同的局部视图，一旦目录结构调整，很容易引用到错误的文件。
5.4 HTML 编码与防 XSS 的边界
@Html.Partial 返回的是 IHtmlContent，它本身不会被二次编码，所以局部视图输出的 HTML 结构是正常的。但在局部视图内部，你用 @Model.Name 输出字符串时，Razor 默认会把字符串转义。如果一个字段的值是一段受信任的富文本 HTML，想让它渲染成标签而不是纯文本，必须用 @Html.Raw(Model.HtmlContent)。
这里要特别小心：Html.Raw 等于告诉浏览器“这段内容我背书”。如果这个字段来自用户输入，就可能引入 XSS 漏洞。我之前接手过一个项目，局部视图里渲染用户填写的“个人签名”，直接 Html.Raw(Model.Bio)，结果有用户把 <script> 写进签名，所有访问他主页的人都中招。后来改成只渲染纯文本，或者用白名单规则过滤后再 Html.Raw。
还有一个和请求验证相关的小坑：在一些 .NET Framework 老项目中，web.config 默认启用了请求验证，如果通过 query string 往局部视图传递包含 < 或 > 的参数，会触发“检测到有潜在危险的 Request.QueryString 值”错误。这个错误和 @Html.Partial 没有直接关系，但它最容易出现在你用 Ajax 加载局部视图、并在 URL 里拼接特殊字符的场景。建议把参数通过 POST 或者 JSON 传，而不是直接拼在 query string 里。
6. 性能与替代方案：什么时候用 RenderPartial，什么时候换 ViewComponent
局部视图用久了，你会开始关心性能，也会遇到一些局部视图“撑不住”的场景。这个部分聊聊我的实测经验和选型思路。
6.1 RenderPartial 比 Partial 省了多少
Partial 内部本质上就是把 RenderPartial 渲染到一个 StringWriter，再包装成 IHtmlContent。多出来的成本是一次中间字符串分配和一次写入。如果只是页面里偶尔调用一两次，这个成本可以忽略。但如果你在一个 1000 行表格里，每行都调用 Partial，那就会多出 1000 个中间对象，GC 压力增加，页面变卡。
我做过一个简单测试：同样的局部视图循环 1000 次，Partial 比 RenderPartial 多出来的内存分配大致在几十 KB 到几百 KB，渲染时间差在个位数毫秒级。单看数值不大，但在高并发场景下会被放大。所以我的原则是：循环体内用 RenderPartial，页面顶部/底部的单次引用用 Partial 也无妨。
6.2 给局部视图加缓存的正确姿势
局部视图本身不带缓存机制，但你可以通过外层缓存来控制。在 ASP.NET Core 中，最简单的做法是 cache tag helper：
cshtml复制<cache expires-after="TimeSpan.FromMinutes(5)" vary-by="@Model.CategoryId">
@Html.Partial("_PromotionCard", Model.Promotion)
</cache>
这样局部视图的输出结果会被缓存，5 分钟内的重复请求直接返回缓存内容。但要注意，cache tag helper 缓存的是 HTML 字符串，如果片段里包含当前登录用户信息、CSRF token、动态验证码等，就必须用 vary-by-user 或者干脆不要缓存。否则用户 A 登录后看到的页面，可能被用户 B 直接命中缓存。
在 MVC 5 时代没有 cache tag helper，常见的做法是把局部视图放到子 Action 里，再给子 Action 加 [OutputCache] 特性，配合 Html.Action 调用。那套方案能用，但会引入额外的 Controller 逻辑，复杂度没有想象中低。无论是哪种缓存，都要先把“缓存粒度和用户隔离”想清楚。
6.3 ViewComponent 才是复杂片段的归宿
局部视图最大的限制是：它只能渲染调用方给的数据，自己没有获取数据的能力。因此，一旦同一个片段在 10 个页面里出现，每个页面都要写一遍“查用户、查配置、组装 ViewModel”的逻辑。这时候局部视图把 UI 重复解决了，却把数据准备重复留给了所有人。
更合理的方案是换成 ViewComponent。它既有独立的 InvokeAsync 方法，又可以接收参数、返回视图，还能自己拉数据。以一个“本周热门文章”组件为例：
csharp复制public class HotArticlesViewComponent : ViewComponent
{
private readonly IArticleRepository _repository;
public HotArticlesViewComponent(IArticleRepository repository)
{
_repository = repository;
}
public async Task<IViewComponentResult> InvokeAsync(int count)
{
var articles = await _repository.GetHotArticlesAsync(count);
return View(articles);
}
}
调用方式：
cshtml复制@await Component.InvokeAsync("HotArticles", new { count = 5 })
从调用方视角看，它比 @Html.Partial 更“自给自足”，页面不需要知道数据怎么来的。当局部视图需要“干活”而不是“纯展示”时，就果断换 ViewComponent。一个小技巧：ViewComponent 的视图文件同样是局部视图，命名放在 Views/Shared/Components/HotArticles/Default.cshtml，内部可以继续用 @model List<Article>。
6.4 一套值得在团队里推行的约定
局部视图用多了，我给自己定了几条规则，这里分享给你，可以直接抄进团队规范：
- 局部视图只做“展示 + 轻逻辑”，不查库，不写复杂业务。
- 数据优先走强类型 Model，不依赖
ViewBag或ViewData传递关键数据。 - 局部视图内不出现
<form>标签，所有表单结构由外层页面统一控制。 - 尽量不写
<script>，交互逻辑由父页面的初始化脚本统一负责。 - 路径全部用
Url.Content("~/...")或Url.Action生成，避免相对路径失效。 - 循环场景优先用
RenderPartial，降低内存分配。
这套规则执行下来，最大的感受是“局部视图踩坑率断崖式下降”。很多问题不是 @Html.Partial 本身难用，而是用的人把它放在了不属于它的位置。只要搞清楚它的边界，它依然是 ASP.NET 世界里性价比极高的 UI 复用工具。