更新记录

1.0.0（2026-09-09） 下载此版本

1. 首次发布：快捷功能导航组件（图标 + 文字入口）
2. 超过一屏数量自动横向滚动，项宽按容器宽度与 maxPerRow 动态计算，保证一屏刚好展示 maxPerRow 个
3. 可配置：每屏数量、图标宽高与 mode、文案颜色字号、项间距、是否显示滚动条
4. 支持 #icon / #item 插槽自定义内容，支持 click 事件回传项数据与索引

平台兼容性

uni-app(5.24)

其他

Quick Nav 快捷功能导航

一款基于 uni-app（Vue3）的快捷功能导航组件（图标 + 文字入口）。功能项较少时等分布局，超过一屏数量时自动横向滚动，项宽动态计算保证一屏刚好展示指定个数，开箱即用。

🚀 功能特性

• ✅ 自动横向滚动：项数超过 maxPerRow 时自动切换为横向滚动，项宽按容器实测宽度动态计算，保证一屏刚好展示 maxPerRow 个，第 maxPerRow + 1 个在屏幕外
• ✅ 可配置项丰富：每屏数量（maxPerRow）、图标宽高与 mode（iconSize / iconMode）、文案颜色字号（nameColor / nameFontSize）、项间距（gap）、是否显示滚动条（showScrollbar）
• ✅ 字段可自定义：通过 nameKey / iconKey 指定从数据项中取文案与图标的字段，默认兼容 { name, icon } 结构
• ✅ 插槽自由：#icon 可单独替换图标，#item 可完全自定义每一项内容
• ✅ 交互回传：点击项通过 click 事件回传该项数据与索引，跳转逻辑由业务侧处理
• ✅ 多端适配：纯 view/text + scroll-view 实现，适配 H5 / App-vue / 小程序

📦 安装引入

1. 将 uni_modules/quick-nav 整个目录复制到项目的 uni_modules 目录下；
2. 开启 easycom 时可直接使用 <quick-nav> 标签，无需手动引入；
3. 若未开启 easycom，可在页面中手动引入：

<script setup>
import QuickNav from "@/uni_modules/quick-nav/components/quick-nav/quick-nav.vue";
</script>

🚀 快速开始

<template>
  <view>
    <!-- 一屏最多 4 个，超过则横向滚动 -->
    <quick-nav :list="funcs" :max-per-row="4" @click="goPath" />
  </view>
</template>

<script setup>
import icon1 from "@/static/func-1.png";
import icon2 from "@/static/func-2.png";

const funcs = [
  { name: "A交易", icon: icon1, url: "/pages/trade/trade" },
  { name: "B交易", icon: icon2, url: "/pages/trade/trade?tab=MARGIN" },
  // ... 超过 4 个自动横向滚动
];

const goPath = (item) => {
  uni.navigateTo({ url: item.url });
};
</script>

业务中常需要携带额外参数（如跳转前切换 Tab、路由参数），把这些字段放进数据项里，在 click 回调中读取即可。

🔧 Props 属性配置

📡 事件

🎨 插槽

<quick-nav :list="funcs" @click="goPath">
  <template #icon="{ item }">
    <image :src="item.icon" style="width: 64rpx; height: 64rpx" mode="aspectFit" />
  </template>
</quick-nav>

🎨 样式自定义

组件内部类可在外部覆盖（scoped 样式需 :deep() 穿透）：

⚠️ 使用注意事项

1. 项宽自动测量：可滚动时组件会实测容器宽度来计算每项宽度，因此「一屏几个」在不同页面内边距下均准确；个别无法测量到的场景会回退为按「屏幕宽度 − 64rpx（容器左右内边距）」估算
2. 空列表自动隐藏：list 为空时不渲染任何内容
3. 避免与组件标签同名：页面（<script setup>）内不要定义与标签同名的局部变量（如 quickNav），否则 <quick-nav> 会被解析成该局部变量而非组件
4. 数据更新：list 数量变化触发重新测量；图标/文案字段变化直接响应式更新

📞 更新日志

见 changelog.md。

祝您使用愉快！ 🎉