Banner 展示模块
最后更新: | 浏览次数: 1925|组件调用与开发
Banner 展示模块用于在网站任意位置调用广告图片、视频或轮播内容。详细配置说明请参考《图片轮播组件定制》。
所有 Banner 调用均基于 BannerViewModel 数据模型设计，该模型包含广告管理中的广告数据。
自 4.8.0601 版本开始，不再推荐使用
Cms.Load()方式调用 Banner。
Banner 调用方法
1. 调用广告管理中的 Banner
@Cms.Banner(string identName, string viewPath = null, bool optimizeLcp = true, bool mobileLarge = true)| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| identName | string | - | 广告标识名称。 |
| viewPath | string | null | 自定义组件路径，留空时默认调用 Views/_AdSlide.cshtml。 |
| optimizeLcp | bool | true | 是否启用 LCP 优化。 |
| mobileLarge | bool | true | 是否使用较大的移动端图片尺寸。设置为 true 时，移动端图片宽度默认为 900px；设置为 false |
性能与优化提示
如果 Banner 位于首屏区域，建议开启 optimizeLcp，以优化页面最大内容绘制性能；如果 Banner 位于非首屏区域，建议将其设置为 false，避免产生不必要的资源优先级。
当 Banner 更依赖图片高度展示效果，或需要在移动端保持更清晰的视觉表现时，建议将 mobileLarge 设置为 true。
2. 调用分类绑定的 Banner
@Model.Banner(string viewPath = null, bool optimizeLcp = true)| 参数 | 类型 | 说明 |
|---|---|---|
| viewPath | string | 自定义组件路径,留空时默认调用 Views/_AdSlide.cshtml |
| optimizeLcp | bool | 是否启用 LCP 优化，默认值为 true。 |
两种调用方式的区别
@Cms.Banner() 与 @Model.Banner() 都会生成一个 BannerViewModel 对象供页面组件使用。
| 调用方式 | 适用场景 |
|---|---|
| @Cms.Banner(...) | 可在网站任意位置调用广告管理中的 Banner。 |
| @Model.Banner(...) | 仅能在当前分类、子分类或其所属内容页面中调用对应的分类 Banner。 |
BannerViewModel 对象
BannerViewModel 包含 Banner 的基础配置及广告内容。
| 属性/方法名称 | 返回类型 | 说明 |
|---|---|---|
| Items | ThumbList | Banner 内容项列表。 |
| Ident | string | 唯一标识符，通常用于生成 HTML 元素 ID。 |
| Effect | SlideEffect | 轮播图的过渡效果。 |
| Direction | SlideDirection | Banner 的滚动方向。 |
| Speed | int | 切换速度，通常以毫秒为单位。 |
| AutoPlay | int | 自动播放延迟时间，可用于设置 data-delay 属性。 |
| Parallax | bool | 是否启用视差效果。 |
| Loop | bool | 是否启用循环播放。 |
| Fixed | bool | 是否启用背景固定。 |
| EnablePagination | bool | 是否启用分页控件。 |
| EnableNavigation | bool | 是否启用前进、后退导航按钮。 |
| CurrentCategory | CategoryBase | 当前内容对应的分类对象 |
| Name | string | 当前调用页面的名称 |
| BreaCrumb() | IHtmlString | 面包屑导航 |
提示： 在使用 @Cms.Banner() 调用 Banner 时， CurrentCategory、Name 属性以及 BreadCrumb() 方法均返回空值或空对象。
BannerViewModel中的Items集合对象
BannerViewModel.Items 为 Banner 内容集合，每一项均为一个 PhotoItemModel 对象。
| 属性名称 | 返回类型 | 说明 |
|---|---|---|
| Url | string | 图片或视频的 URL 地址。 |
| Width | int | 图片宽度。 |
| Height | int | 图片高度。 |
| Link | string | 图片点击后的跳转链接。 |
| Caption | string | 标题或说明文字。 |
| Summary | IHtmlString | 图片或视频摘要内容。 |
调用示例
调用广告管理 Banner
@Cms.Banner("home-banner")调用自定义效果组件
@Cms.Banner("home-banner", "modules/custom-adslide.cshtml")读取 Banner 图片地址
@Model.Banner.Items[0].Url自定义组件
系统在 Views 目录中提供了一系列默认 Banner 组件，用于快速完成常见展示效果。
这些组件会随着系统版本更新持续优化和扩展。如需完全自定义展示效果，可在 Modules 目录下创建新的组件文件，并通过 viewPath 参数指定调用路径。
@Cms.Banner(
"home-banner",
"modules/HomeBanner"
)默认组件
默认情况下：
@Cms.Banner("home-banner") 和 @Model.Banner()会自动调用：
Views/_AdSlide.cshtml使用建议
| 场景 | 推荐方式 |
|---|---|
| 全站公共 Banner | @Cms.Banner() |
| 分类页/内容页 Banner | @Model.Banner() |
| 复杂展示效果 | 使用自定义组件。 |
总结
Banner 展示模块提供了灵活的广告调用机制：
- 支持广告管理统一维护 Banner 内容
- 支持分类独立绑定 Banner
- 支持图片与视频资源
- 支持轮播、自动播放、视差、分页等功能
- 支持自定义视图组件扩展
- 支持 LCP 优化，提高页面加载性能
通常推荐：
- 全站公共 Banner 使用
@Cms.Banner() - 分类页面 Banner 使用
@Model.Banner() - 复杂展示需求使用自定义组件实现