TechUI Docs

简中

EN

简中

EN

主题

滚动图标导航 ​

⭐明星组件
👑首创

RollingNavIcon 是一个用于展示大量图标入口的滚动导航组件。 它底层基于 TechUI 强大的核心滚动引擎 TuiRolling 构建。继承了 TuiRolling 的高性能特性，支持按项(Item)/按页(Page)滚动、无缝无限滚动、自适应布局以及平滑的运动模糊效果。

它非常适合用于工具栏、快捷入口列表或移动端的导航菜单。

核心特性 ​

  • Powered by TuiRolling: 基于核心滚动组件开发，拥有强大的滚动计算能力，支持无缝循环和自适应补齐。
  • 双向布局: 完美支持 水平 (Horizontal) 和 垂直 (Vertical) 两种流向。
  • 视觉定制:
    • 外框形状: 支持圆角 (round)、圆形 (circle) 或无边框 (none)。
    • 运动模糊: 内置 motionBlur，在快速滚动时提供高质量的视觉动态模糊。
    • 尺寸控制: 精确控制图标大小、外框宽高以及自适应的近似宽高。
  • 交互控制:
    • 支持 点击 (Click) 或 悬停 (Hover) 触发选中。
    • 支持 可关闭 (Closeable) 模式，允许用户动态移除导航项。
    • 灵活的 控制栏 (Control Bar) 位置配置（上下左右）。

基础用法 ​

水平滚动 (Horizontal) ​

默认模式。适用于顶部工具栏或通栏菜单。 组件会自动根据 frameWidth 和容器宽度计算每页显示的个数。

html
<script setup>
import { ref } from 'vue';

const activeVal = ref('home');
const navItems = [
  { label: 'Dashboard', value: 'home', icon: 'ti-home' },
  { label: 'Components', value: 'comp', icon: 'ti-package' },
  // ... 更多数据
];
</script>

<template>
  <TuiRollingNavIcon 
    v-model="activeVal" 
    direction="h"
    :frameWidth="100" 
    :iconSize="28"
  >
    <TuiRollingNavIconItem 
      v-for="item in navItems" 
      :key="item.value"
      :value="item.value" 
      :label="item.label" 
      :icon="item.icon" 
    />
  </TuiRollingNavIcon>
</template>

垂直滚动 (Vertical) ​

设置 direction="v" 即可切换为侧边栏模式。 此时控制栏（翻页按钮）会自动适配布局，通常建议配合 controlPosition 调整位置。

html
<template>
  <div style="height: 400px; width: 120px">
    <TuiRollingNavIcon 
      v-model="activeVal" 
      direction="v"
      frameShap="circle"
      controlPosition="bottom"
    >
      <TuiRollingNavIconItem 
        v-for="item in navItems" 
        :key="item.value"
        v-bind="item" 
      />
    </TuiRollingNavIcon>
  </div>
</template>

交互与视觉定制 ​

触发与关闭 ​

  • trigger: 设置为 'hover' 可实现鼠标滑过即选中。
  • closeable: 开启后，鼠标悬停在 Item 上会出现关闭按钮。监听 @remove 事件处理删除逻辑。
html
<template>
  <TuiRollingNavIcon 
    trigger="hover" 
    closeable
    frameShap="round"
  >
    <TuiRollingNavIconItem 
      v-for="(item, index) in list" 
      :key="item.id"
      v-bind="item"
      @remove="handleRemove(index)"
    />
  </TuiRollingNavIcon>
</template>

控制栏位置 ​

通过 controlPosition 可以将翻页控制器放置在 top, bottom, left, right 任意位置，适应不同的 UI 设计。

API 参考 ​

Props ​

属性名类型默认值说明
modelValueString/Number-当前选中的值 (v-model)。
directionString'h'滚动方向。可选：'h' (水平), 'v' (垂直)。
controlPositionString-控制栏位置。可选：top, right, bottom, left。
frameShapString'round'图标外框形状。可选：none, round, circle。
triggerString'click'激活方式。可选：click, hover。
closeableBooleanfalse是否开启删除功能。
motionBlurBooleantrue是否开启滚动时的运动模糊特效。
iconSizeNumber24图标尺寸 (px)。
frameWidthNumber100单个 Item 的外框宽度。
frameHeightNumber80单个 Item 的外框高度。
itemApproxWidthNumber140自适应计算时的近似宽度（用于预估分页）。
itemApproxHeightNumber80自适应计算时的近似高度。
controlTypeString-控制栏样式类型。可选：base, enhanced。
durationNumber-滚动动画时长。
resizeObserverString'global'尺寸监听策略：self, global, none。

Emits ​

事件名说明回调参数
update:modelValue选中值改变时触发。(value)
change选中项改变时触发。(value, index)
start开始滚动时触发。-
rolling滚动过程中持续触发。(offset)

Slots ​

插槽名说明
default这里应当放置 <TuiRollingNavIconItem> 组件列表。