用 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 里补方法