ng-zorro-antd Carousel 轮播切换箭头（nzArrows）实战指南：从示例到源码原理

本篇指南聚焦 ng-zorro-antd 的 Carousel（轮播）组件中"切换箭头"这一功能，对应官方示例 components/carousel/demo/arrow.md（切换箭头 / Arrows for switching）。文章以该示例为骨架，完整给出可运行代码，并结合 carousel.component.ts、carousel.spec.ts 与 style/index.less 逐层拆解 nzArrows 输入属性的模板渲染、边界禁用逻辑、点击导航链路与样式定制方法，读完即可在自己的 Angular 项目中直接落地使用。

一、功能速览：什么是轮播切换箭头

轮播（Carousel）常用于展示同一层级的一组图片或卡片。默认情况下，nz-carousel 只提供底部的指示点（dots）和拖拽/滑动切换；而在轮播容器左右两侧显示"上一张 / 下一张"的箭头按钮，就是本示例演示的"切换箭头"能力。

该功能由 nzArrows 布尔型输入属性控制，在 组件文档 API 表 中登记如下：

属性	说明	类型	默认值	全局配置	版本
[nzArrows]	是否显示箭头按钮	boolean	false	-	20.3.0

注意两点关键事实：

• 默认关闭：nzArrows 默认值为 false，必须显式开启；
• 不支持全局配置：与 nzAutoPlay、nzDots、nzEffect 等属性不同，nzArrows 没有标注"Global Config ✅"，即无法通过 NzConfigService 对 carousel 模块做全局统一配置，只能逐组件设置（这一差异可在 carousel.component.ts 的输入属性声明中确认——其他属性带 @WithConfig()，而 nzArrows 仅使用 booleanAttribute 转换）。

二、示例核心代码：开启箭头并组装轮播内容

示例完整代码位于 components/carousel/demo/arrow.ts，其模板与组件类如下：

import { Component } from '@angular/core';

import { NzCarouselModule } from 'ng-zorro-antd/carousel';

@Component({
  selector: 'nz-demo-carousel-arrow',
  imports: [NzCarouselModule],
  template: ` <nz-carousel [nzEffect]="effect" nzArrows>
    @for (index of array; track index) {
      <div nz-carousel-content>
        <h3>{{ index }}</h3>
      </div>
    }
  </nz-carousel>`,
  styles: `
    [nz-carousel-content] {
      text-align: center;
      height: 160px;
      line-height: 160px;
      background: #364d79;
      color: #fff;
      overflow: hidden;
    }

    h3 {
      color: #fff;
      margin-bottom: 0;
      user-select: none;
    }
  `
})
export class NzDemoCarouselArrowComponent {
  array = [1, 2, 3, 4];
  effect = 'scrollx';
}

代码要点逐条说明：

1. 属性简写开启箭头：模板中直接写 nzArrows（等价于 [nzArrows]="true"）。得益于 @Input({ transform: booleanAttribute }) 的属性转换，任何非空写法都会被转为 true；
2. nzEffect 绑定效果：<a href="https://link.gitcode.com/i/86f048788653984ec42a3e517cb4ef03" target="_blank">nzEffect]="effect" 绑定值为 'scrollx'（横向滚动），这是 Carousel 的默认效果类型（NzCarouselEffects = 'fade' | 'scrollx' | string，见 [typings.ts）；'fade' 为淡入淡出效果；
3. @for 渲染内容：使用 Angular 新控制流语法 @for (index of array; track index) 循环渲染 4 张幻灯片，每张都通过 nz-carousel-content 指令标记为轮播项，该指令会给元素加上 slick-slide 类（见 carousel-content.directive.ts）；
4. 内容样式：[nz-carousel-content] 选择器设置每张幻灯片为 160px 高、#364d79 深蓝色背景、白色居中文字；user-select: none 避免文字在拖拽切换时被选中；
5. 模块导入：组件通过 imports: [NzCarouselModule]（standalone 方式）引入 Carousel 模块，即可使用 nz-carousel 组件与 nz-carousel-content 指令。

三、源码解析：箭头按钮如何渲染与工作

开启 nzArrows 后，箭头按钮由 carousel.component.ts 的组件模板直接渲染。模板中相关的核心片段如下（为便于阅读做了精简）：

<div class="slick-initialized slick-slider">
  @if (nzArrows) {
    <button
      type="button"
      aria-label="prev"
      class="slick-prev slick-arrow"
      [class.slick-disabled]="this.activeIndex === 0"
      (click)="pre()"
    ></button>
  }
  <div #slickList class="slick-list" ...>
    <div class="slick-track" #slickTrack>
      <ng-content />
    </div>
  </div>
  @if (nzArrows) {
    <button
      type="button"
      aria-label="next"
      class="slick-next slick-arrow"
      [class.slick-disabled]="this.activeIndex === this.carouselContents.length - 1"
      (click)="next()"
    ></button>
  }
</div>

由此可以提炼出实现层面的几个关键事实：

1. 纯 CSS 绘制箭头，无图标依赖

两个 <button> 内部没有任何文字或图标，箭头完全由 style/index.less 中的 ::after 伪元素用边框旋转绘制：先画出一个 11.3px × 11.3px 的 L 形边框（border-inline-start-width: 2px 与 border-block-start-width: 2px），再通过 transform: rotate(-45deg)（prev）或 rotate(135deg)（next）旋转成指向左右两边的箭头。font-size: 0 保证按钮内无残留文字。

2. 边界禁用状态与循环模式

• slick-prev 在 activeIndex === 0 时加上 slick-disabled 类；
• slick-next 在 activeIndex === carouselContents.length - 1（最后一张）时加上 slick-disabled 类；
• 样式层面对 .slick-disabled 直接 display: none 隐藏按钮（见 style/index.less）。

需要特别说明：禁用逻辑与 nzLoop 联动。nzLoop 默认值为 true（循环模式），此时第一张的"上一张"会回绕到最后一张、最后一张的"下一张"会回到第一张，因此正常循环场景下箭头基本不会出现禁用态；只有显式设置 [nzLoop]="false" 后，首尾边界才会真正禁用对应的箭头。

3. 点击导航调用链

箭头点击最终走的是 pre() / next() → goTo() 的调用链（carousel.component.ts）：

• next() 等价于 goTo(activeIndex + 1)，pre() 等价于 goTo(activeIndex - 1)；
• goTo(index) 内部会先做边界守卫：nzLoop 为真，或目标索引在 [0, length) 范围内才允许切换；切换目标索引通过 (index + length) % length 取模得到，实现循环回绕；
• 切换过程中会先后派发 nzBeforeChange（携带 { from, to }）与 nzAfterChange（携带目标索引）两个事件，供外部监听。

4. 键盘与 RTL 细节

• 除了点击箭头，slick-list 上还监听了键盘 LEFT_ARROW / RIGHT_ARROW，左右方向键同样会触发 pre() / next()（见 carousel.component.ts），实现键盘可访问性；
• 箭头定位使用 inset-inline-start / inset-inline-end（style/index.less），在 RTL 环境下箭头位置会自动镜像翻转，与 ant-carousel-rtl 类配合良好。

四、测试用例佐证：箭头行为有据可查

Carousel 的单元测试 carousel.spec.ts 中有专门的 "carousel arrows" 用例组，验证了三条核心行为：

1. 渲染断言：nzArrows 为 true 时，组件 DOM 中能查询到 .slick-prev 与 .slick-next 两个按钮；
2. 导航断言：初始第一张带 slick-active，点击 .slick-next 后第二张变为 slick-active，再点 .slick-prev 回到第一张；
3. 边界断言：nzLoop 设为 false 后，第一张时 .slick-prev 带 slick-disabled；连点 .slick-next 到达最后一张后 .slick-next 也带 slick-disabled，且继续点击 next 不会越过最后一张。

测试中构造的组件 NzTestCarouselArrowsComponent 使用 <nz-carousel [nzArrows]="true" [nzLoop]="loop()" [nzTransitionSpeed]="10"> 这种写法，也印证了 nzArrows 与 nzLoop、nzTransitionSpeed 的组合使用方式（nzTransitionSpeed 为切换动画时长，测试中调小以加速稳定）。

五、样式定制：调整箭头外观

如果默认箭头不符合设计需求，可通过覆盖 slick-prev / slick-next 的样式实现定制。默认样式关键变量定义在 style/index.less：

Less 变量	默认值	作用
@carousel-arrow-size	16px	箭头按钮尺寸
@carousel-arrow-offset	12px	箭头距容器边缘的距离
@carousel-arrow-bg	fade(#000, 20%)	箭头背景色（默认透明）
@carousel-arrow-bg-hover	fade(#000, 30%)	悬停背景色
@carousel-arrow-color	@white	箭头颜色

其他可见样式行为包括：按钮默认 opacity: 0.3，hover / focus 时变为 1（style/index.less）；当 nzDotPosition 为 left / right（垂直布局）时，箭头会移动到容器顶部与底部的水平居中位置，并旋转为指向上下的箭头（style/index.less）。

在业务代码中可直接覆写：

nz-carousel .slick-prev,
nz-carousel .slick-next {
  width: 24px;
  height: 24px;
  opacity: 0.8;
}

六、组合使用建议与最佳实践

结合 组件文档 中 nz-carousel 的完整 API，箭头功能通常与其他属性搭配使用，常用组合如下：

组合场景	推荐配置
仅箭头手动切换	nzArrows + [nzEffect]="'scrollx'"（本示例）
箭头 + 自动播放	nzArrows + [nzAutoPlay]="true" + [nzAutoPlaySpeed]="3000"
非循环相册	nzArrows + [nzLoop]="false"（首尾箭头自动隐藏）
淡入淡出切换	nzArrows + [nzEffect]="'fade'"
垂直轮播	nzArrows + [nzDotPosition]="'left' | 'right'"（箭头转向上/下）

补充说明两点：

• nzArrows 仅在 nz-carousel 组件实例上生效，无法通过全局 nzConfigService 开启（见第一节），如需全站统一开启，可封装自己的轮播包装组件；
• 箭头按钮本身带 aria-label="prev" / aria-label="next"，屏幕阅读器可正常识别，是开箱即用的无障碍实现，无需额外处理。

七、小结

"切换箭头"虽只是一个布尔开关，但其背后串联了 booleanAttribute 输入转换、模板条件渲染、slick-disabled 边界类、pre/next/goTo 导航调用链、CSS 伪元素绘制箭头以及键盘/循环模式等一整套机制。通过官方示例 arrow.ts 起步，再对照 carousel.component.ts 与 carousel.spec.ts 阅读，即可完整掌握从"显示箭头"到"自定义箭头行为与样式"的每一层细节，并在真实项目中放心使用。