zljx-waterfall

zljx-waterfall

浙里金消 uni-app 瀑布流组件，支持 地图 / 商品 / 看点 / 活动 四种卡片类型，开箱即用：安装后传入 tabs 即可，无需自行对接接口。

特性

• 双列瀑布流布局（矮列优先、测高定位），tab 栏 CSS position: sticky 吸顶
• 四种卡片类型：地图门店（含定位距离）、商品（国补/积分/本地生活标签）、看点（点赞）、活动
• 选中 tab 角标图标：内置 9 个名称-图标映射，传入同名 tab 选中时显示角标，也可 icon 显式覆盖
• 请求自带 token 注入（读取 USER_ZLJX_LOGINKEY）、json-bigint 大整数解析
• 域名/跳转前缀/腾讯地图 key 全部可配置，默认正式环境开箱即用
• 源码包发布，保留 #ifdef 条件编译，H5/小程序多端兼容
• 零第三方 UI 依赖：吸顶/加载动画/图标均已内置实现（CSS + 内嵌 SVG），无需安装 uv-ui、sass

环境前提

• Vue 3 + uni-app（vite 编译）项目

注意：吸顶依赖页面级滚动，宿主页面的父级容器不能设置 overflow: hidden，否则 sticky 失效。

安装

pnpm add zljx-waterfall

使用

<script lang="ts" setup>
import { ref } from 'vue'
import { onReachBottom } from '@dcloudio/uni-app'
import Waterfall from 'zljx-waterfall'
import type { WaterfallTab } from 'zljx-waterfall'

// tab 名称、类型、接口参数均由页面自定义传入
const tabs: WaterfallTab[] = [
  // 消费地图位置分页列表，lat/lng 为定位经纬度，distance 距离（米），mapPositiontype 位置类型
  { name: '附近门店', type: '地图', params: { lat: 29.091377, lng: 119.625352, distance: 10000, mapPositiontype: 1 } },
  // 个性化推荐，不传 businessType 搜索全部业务类型
  { name: '猜你喜欢', type: '商品', params: {} },
  // 看点列表
  { name: '每日看点', type: '看点', params: { SystemType: 1, IDList: [0] } },
  // 主题活动列表，Status: 2 进行中，可选 ActivityAreaNo 按区域筛选
  { name: '主题活动', type: '活动', params: { Status: 2 } }
]

const waterfallRef = ref<InstanceType<typeof Waterfall> | null>(null)

// 页面触底时加载下一页（页面生命周期只能在页面中监听，组件内监听无效）
onReachBottom(() => {
  waterfallRef.value?.loadMore()
})

const onTabChange = (tab: WaterfallTab) => {
  console.log('切换到 tab：', tab.name, tab.type)
}
</script>

<template>
  <Waterfall ref="waterfallRef" :tabs="tabs" :page-size="20" @tab-change="onTabChange" />
</template>

内置选中 tab 角标图标（仅选中的 tab 显示，名称相同才命中）

图标域名：https://static.zljx.top/public/icon/waterfall/。仅当前选中的 tab 显示角标；名称未配置时不显示；WaterfallTab.icon 显式传入优先于内置映射。

全局配置（可选）

import { setZljxWaterfallConfig } from 'zljx-waterfall'

setZljxWaterfallConfig({
  // 接口域名（解析优先级见下方「环境判断」，此处显式传入优先级最高）
  searchApi: 'https://testgateway.zljx.top/zljx/searchapi',
  highlightApi: 'https://testgateway.zljx.top/zljx/subjectapi',
  mapApi: 'https://testgateway.zljx.top/zljx/mapapi',
  // H5 跳转前缀
  dailyhighlightsH5: 'https://kandian.zljx.top',
  mainSitePzxfH5: 'https://m.zljx.me',
  mainSiteAIH5: 'https://map.zljx.top',
  qqMapKey: 'xxx',
  // 宿主项目内商品详情页路径
  goodsDetailPath: '/subpackages/goodsDetail/goodsDetail',
  // 自定义 token 获取（默认读 storage 的 USER_ZLJX_LOGINKEY）
  getToken: () => 'xxx',
  // 401 回调（宿主接自己的登录跳转）
  onUnauthorized: () => {},
  // 请求日志上报
  onReport: (log) => {}
})

环境判断

域名按以下优先级解析（环境判断方案参考 kandian-ad-sdk）：

1. setZljxWaterfallConfig 显式传入（最高优先级）
2. 宿主项目环境变量 VITE_SEARCHAPI / VITE_HIGHLIGHTAPI / VITE_APP_MAPAPI / VITE_APP_dailyhighlights_H5 / VITE_APP_mainSitePzxf_H5 / VITE_APP_mainSiteAI_H5 / VITE_QQ_MAP_KEY
3. 运行时环境自动判断：
   • H5：location.hostname 为 localhost / 127.0.0.1 / 192.168.* / 10.*，或包含 test、yiuxiu.com（测试站点域名）→ 测试环境
   • 小程序：无 window，按编译期 import.meta.env.DEV 判断
4. 兜底正式环境地址

即：本地开发 / 测试环境自动请求测试域名（testgateway.zljx.top 等），生产构建自动请求正式域名（gateway.zljx.top 等），无需任何配置。可用 isTestEnvironment() 查询当前判定结果。

API

Waterfall 组件 Props

组件事件与实例方法

• @tab-change(tab: WaterfallTab)：tab 切换回调
• ref.loadMore()：加载下一页（页面触底时调用）
• ref.reset()：重置并重新加载当前 tab
• ref.switchTab(index)：切换 tab

WaterfallTab

interface WaterfallTab {
  /** tab 显示名称（与内置图标配置同名时，选中该 tab 显示角标图标） */
  name: string
  /** 角标图标地址（可选，显式传入优先，仅选中显示） */
  icon?: string
  /** 卡片类型：'地图' | '商品' | '看点' | '活动' */
  type: WaterfallType
  /** 接口自定义参数（分页参数组件内部维护） */
  params?: Record<string, any>
}

发布

# 版本号修改后执行
cd packages/zljx-waterfall
npm publish