用 EasyAdminBlazor.Cms 快速开发前台内容页面
EasyAdminBlazor.Cms是面向开发人员的前台快速开发扩展:开发者用 Razor 写页面并用[CmsPage]/[CmsDataType]声明内容结构,即可获得自动生成的后台内容管理;内容编辑人员无需改代码,也能管理数据、分类、页面元素、SEO 和评论审核。 目标:写一个 Razor 页面,打一个注解,用公共方法取数,页面元素用<vc:textblock>标记,运行即可。后台菜单、数据表、字段、分类、SEO、Live Edit 都由扩展自动生成。
1. 安装并注册 CMS 扩展
先引用 CMS 扩展包:
<PackageReference Include="EasyAdminBlazor.Cms" Version="2.5.0" />
在 Program.cs 的 EasyAdminBlazor 扩展链中注册:
builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions { ... })
// …你现有的扩展链…
.AddEasyAdminBlazorCms(o => o.EnableComments = true);
AddEasyAdminBlazorCms() 会注册 CMS 数据服务、页面收集器、元素缓存、SEO 过滤器和启动初始化器。启动时会自动同步 CMS 表结构、扫描 [CmsPage] / [CmsDataType]、生成后台菜单并同步自定义字段;不需要手写实体、迁移或后台管理页面。
评论是可选功能,EnableComments 默认 false:开启后才会建 cms_comment 表、在后台 CMS 下挂「评论审核」菜单,前台 ICmsCommentService.AddAsync 才会接收提交;关闭时「评论审核」菜单自动隐藏(已有的菜单行不删除,重新开启即恢复),评论表与数据保留。
接着在宿主项目的根组件(通常是 Components/App.razor)的 <body> 末尾引入 Live Edit 脚本,放在 blazor.web.js 之后:
<script src="@Assets["_content/EasyAdminBlazor.Cms/cms-inline-edit.js"]"></script>
这个脚本提供 window.cmsInlineEdit,后台“元素”页签的 Live Edit 依赖它。宿主项目漏加时,页面预览虽然能打开,但无法点击内容进行编辑和保存。
2. 定义内容类型常量
在宿主项目的内容类型常量文件里加一项,页面注解和服务调用共用它。
public static class CmsContentTypes
{
public const string Case = "case";
}
3. 写页面和 PageModel
在 PageModel 上打 [CmsPage]。这是模块唯一需要手写的配置。
[CmsPage(
PageName = "客户案例", // 后台菜单名
Kind = CmsPageKind.DataListWithCategory, // 页面类型,决定后台 Tab
ContentType = CmsContentTypes.Case,
Sort = 55, // 后台菜单排序
HasSeo = true, // 是否显示内容级 SEO 字段
Fields = new[] // 自定义字段
{
$"client:客户名称:{CmsFieldTypes.Text}",
$"industry:行业:{CmsFieldTypes.Text}",
$"result:项目成果:{CmsFieldTypes.Textarea}"
},
HiddenFields = new[] // 后台不需要显示的内置字段
{
CmsFieldNames.Slug,
CmsFieldNames.Summary
})]
public class CasesModel : PageModel
{
private readonly ICmsContentService _cms;
public CasesModel(ICmsContentService cms) => _cms = cms;
public CmsItemPage Items { get; set; } = new();
public CmsCategoryView Category { get; set; }
public List<CmsCategoryView> Categories { get; set; } = new();
public async Task OnGet(string category, int pageIndex = 1)
{
Categories = await _cms.GetCategoriesAsync(CmsContentTypes.Case);
Category = Categories.FirstOrDefault(x => x.Slug == category);
Items = await _cms.GetItemsPageAsync(
CmsContentTypes.Case,
Category?.Id,
pageIndex: pageIndex,
pageSize: 12,
onlyAudit: true);
}
}
列表与详情页
一个模块通常由列表页和详情页组成:内容数据在列表页管理,详情页只负责展示同一条内容和编辑自己的元素。列表项用 Slug 链接到详情页,不把详情页当作第二个数据管理入口。
[CmsPage(
PageName = "新闻",
Kind = CmsPageKind.DataListWithCategory,
Route = "/News",
ContentType = CmsContentTypes.News,
HasSeo = true,
Fields = new[]
{
$"commentable:允许评论:{CmsFieldTypes.Bool}"
})]
public class NewsModel(ICmsContentService cms) : PageModel
{
public List<CmsItemView> Items { get; set; } = [];
public CmsItemPage Data { get; set; } = new();
public async Task OnGet(long? categoryId, int pageIndex = 1)
{
Data = await cms.GetItemsPageAsync(
CmsContentTypes.News,
categoryId,
pageIndex,
pageSize: 10,
onlyAudit: true);
Items = Data.Items;
}
}
// 只有详情页需要编辑元素时才加 [CmsPage];只展示内容、没有可编辑元素时可以不加。
[CmsPage(
PageName = "新闻详情",
Kind = CmsPageKind.DataDetail,
Route = "/News/{slug}",
ContentType = CmsContentTypes.News)]
public class NewsDetailModel(ICmsContentService cms) : PageModel
{
public CmsItemView? Article { get; set; }
public async Task<IActionResult> OnGet(string slug)
{
Article = await cms.GetItemAsync(CmsContentTypes.News, slug);
return Article == null ? NotFound() : Page();
}
}
列表页输出详情链接,取 Slug 打开详情:
@foreach (var item in Model.Items) {
<a asp-page="/NewsDetail" asp-route-slug="@item.Slug">@item.Title</a>
}
详情页只读取当前内容。<vc:textblock> 只用于静态内容,不要用它包动态标题或正文:
<vc:textblock code="news-banner">
<h1>新闻详情</h1>
</vc:textblock>
<div>@Html.Raw(Model.Article?.Content)</div>
详情页的元素内容类型由页面 Key 自动决定(例如 news-slug),不需要手写 content-type,也不会和列表页的 news 元素混在一起。
详情页后台菜单只在声明了 [CmsPage] 且 Kind = CmsPageKind.DataDetail 时生成,只包含“元素”页签,不显示“数据”“分类”“SEO”。详情页元素按页面 Key 单独存储,正文、分类、审核状态和 SEO 都在列表页管理。
后台预览会从已审核、已启用内容中自动取一条带 slug 的记录,打开 /News/{slug} 编辑元素;没有可预览内容,或路由不是只包含一个 {slug} 参数时,会显示提示,请从列表页进入具体详情。
详情页 SEO 使用列表数据中的
seoTitle、seoKeyword、seoDescription,不在详情页单独配置;详情页没有需要编辑的元素时,不需要加[CmsPage]。
自定义字段格式
格式为 key:名称:类型[:选项1|选项2]。类型使用 CmsFieldTypes 中的常量:
$"department:招聘部门:{CmsFieldTypes.Text}",
$"headcount:招聘人数:{CmsFieldTypes.Number}",
$"requirements:任职要求:{CmsFieldTypes.Textarea}",
$"status:状态:{CmsFieldTypes.Select}:启用|停用",
$"recommend:推荐:{CmsFieldTypes.Bool}"
可用类型:text、textarea、number、select、image、bool。
定义非法时启动会直接报错,并给出页面名、字段定义和可选类型。select 类型必须提供选项。
4. 前台取数
列表、分页、详情、分类、上下篇、相关都走 ICmsContentService,不要直接查 Db.CmsData。
var page = await _cms.GetItemsPageAsync(CmsContentTypes.Case, pageIndex: 1);
var item = await _cms.GetItemAsync(CmsContentTypes.Case, slug);
var byId = await _cms.GetItemAsync(CmsContentTypes.Case, 123); // 兼容旧链接
var categories = await _cms.GetCategoriesAsync(CmsContentTypes.Case);
var (prev, next) = await _cms.GetNeighborsAsync(CmsContentTypes.Case, item.CategoryId, item.PublishTime.Value, item.Id);
var related = await _cms.GetRelatedAsync(CmsContentTypes.Case, item.Get("keywords"), item.Id);
评论是独立的 cms_comment 表,不进入 cms_data,请用 ICmsCommentService(参考 Demo 的 Pages/NewsDetail.cshtml.cs 和 Pages/News.cshtml.cs):
// NewsDetail:读取已审核、非垃圾的评论
var comments = await _comments.GetApprovedAsync(CmsContentTypes.News, item.Id, take: 20);
// NewsDetail:提交评论,AddAsync 会把新评论置为待审核
await _comments.AddAsync(new CmsComment
{
ContentType = CmsContentTypes.News,
ContentId = item.Id,
AuthorName = input.Name,
Content = input.Text
});
// News:一次批量统计列表项的已审核评论数
var counts = await _comments.CountApprovedByContentIdsAsync(
CmsContentTypes.News,
items.Select(x => x.Id));
GetApprovedAsync 只返回已审核且非垃圾的评论,适合直接展示在详情页;AddAsync 提交的评论默认待审核,审核通过后才展示;CountApprovedByContentIdsAsync 适合列表页批量统计评论数。提交表单还应结合 commentable 标记和验证码做业务限制,Demo 的 NewsDetail 已展示这套用法。不要在页面里直接读写 CmsComment 或 cms_data。
按自定义字段在数据库层筛选:
// 单个字段精确匹配
var articles = await _cms.GetItemsByFieldAsync(
CmsContentTypes.News, "recommend", "true", take: 3, onlyAudit: true);
// 多个字段 AND 组合,contains: true 表示模糊包含
var list = await _cms.GetItemsByFieldsAsync(CmsContentTypes.News, new[]
{
new CmsFieldFilter("recommend", "true"),
new CmsFieldFilter("source", "格利特", contains: true)
});
读取自定义字段:
@item.Get("client") @item.GetBool("recommend") @item.GetInt("viewHits")
@item.GetDecimal("price")
5. 页面元素
先在 Pages/_ViewImports.cshtml 注册标签助手:
@addTagHelper *, EasyAdminBlazor.Cms
然后用 <vc:textblock> 标记可编辑元素。按“视觉区块”划分,不要把标题、副标题、说明拆成多个 code;Live Edit 支持整块 HTML 编辑:
<vc:textblock code="CASE_PAGE_HERO">
<p>CASES</p>
<h1>客户案例</h1>
<p>看看我们如何帮助客户落地项目。</p>
</vc:textblock>
元素按 (ContentType, Code) 唯一,建议用模块前缀避免跨模块重名。后台在元素 Tab 的 Live Edit 里可以直接点击页面修改整块内容。
Pages/Shared 下的布局或局部视图中的元素会自动作为共享元素(空 ContentType)处理;其他位置如果需要共享,可以显式加 shared="true":
<vc:textblock code="SITE_NOTICE" shared="true">
<p>全站公告</p>
</vc:textblock>
6. 多语言
CMS 后台界面(数据、分类、元素、评论审核、SEO)已内置中英文,语言包位于 Extensions/EasyAdminBlazor.Cms/Locales/zh.json 和 en.json 的 EasyAdminBlazor.Common 块。注册扩展时这些文件会被自动合并进 CommonLocalizer,无需额外配置。
新增语言时,复制 zh.json 为 {culture}.json 并翻译即可;csproj 已用通配符嵌入 Locales/*.json,不用改代码。页面自己的 PageName、Fields 文案属于宿主项目,按宿主的语言包(EasyAdminBlazor.Common 或实体块)翻译。
7. 运行
启动网站后扩展会自动完成:
- 同步
cms_data、cms_category、cms_field、cms_element、cms_page_seo表结构 - 根据
Fields同步字段定义,非法定义直接报错 - 为声明了
[CmsPage]的页面生成后台菜单;有业务数据的页面再生成增删改按钮 - 列表页按
Kind生成 Tab:数据 → 分类 → 元素 → SEO,SEO 始终最后 DataDetail页面只生成“元素”Tab;详情页没有可编辑元素时不要加[CmsPage]- 根据
HasSeo决定列表内容是否显示内容级 SEO 输入框;详情页 SEO 使用列表数据中的 SEO 字段
不需要做的事
- 不需要写实体类、DbContext、迁移脚本
- 不需要写后台管理页面
- 不需要为每个模块写 View 类
- 不需要在菜单表里手工加记录
需要额外处理的情况
- 页面没有前台入口时,用
[CmsDataType]代替[CmsPage] - 详情页只展示内容、没有可编辑元素时,不需要加
[CmsPage] - 需要按自定义字段组合做更复杂的查询时,在
ICmsContentService里补方法