coolui-scroller-uni

coolui-scroller 的 uni-app 版本：下拉刷新、上拉加载、长列表分页、下拉二楼、排序筛选等组件库，支持编译到微信/支付宝/百度/字节/QQ 小程序及 H5、App 端。

• 组件 API 与交互效果与原生微信小程序版保持一致，属性与配置项可直接对照原生微信小程序版文档。
• 基于 Vue provide/inject 实现组件通信，替代原生 relations。
• 跨端 API 统一封装在 utils/platform.js，自动适配各端差异。
• 兼容 Vue 2 / Vue 3。

安装

npm i coolui-scroller-uni

引入组件

方式一：全局注册（Vue3）

在 main.js 中：

import { createSSRApp } from 'vue'
import App from './App.vue'
import CooluiScrollerUni from 'coolui-scroller-uni'

export function createApp() {
  const app = createSSRApp(App)
  app.use(CooluiScrollerUni)
  return { app }
}

Vue2 项目使用 Vue.use(CooluiScrollerUni) 即可。

方式二：easycom（推荐，免 import，本仓库 demo 即用此方式）

在 pages.json 中配置：

{
  "easycom": {
    "autoscan": false,
    "custom": {
      "^coolui-scroller(-.*)?$": "coolui-scroller-uni/components/coolui-scroller$1/coolui-scroller$1.vue"
    }
  }
}

配置后模板中直接使用组件标签，无需 import 与 components 注册：

<coolui-scroller :isEmpty="isEmpty" @refresh="refresh" @loadmore="loadmore">
  <template #refresh>
    <coolui-scroller-refresh :config="{ height: 60 }" />
  </template>
  <!-- ... -->
</coolui-scroller>

方式三：页面内局部引入

<script>
import { CooluiScroller } from 'coolui-scroller-uni'
export default {
  components: { CooluiScroller },
}
</script>

基础用法（下拉刷新 + 上拉加载）

<template>
  <view class="page">
    <coolui-scroller
      :isEmpty="isEmpty"
      background="#f2f2f2"
      @refresh="refresh"
      @loadmore="loadmore"
    >
      <template #refresh>
        <coolui-scroller-refresh :config="{ height: 60 }" />
      </template>

      <view v-for="(item, index) in list" :key="index" class="item">
        {{ item }}
      </view>

      <template #loadmore>
        <coolui-scroller-loadmore :status="loadStatus" />
      </template>
    </coolui-scroller>
  </view>
</template>

export default {
  data() {
    return {
      isEmpty: false,
      list: [],
      page: 1,
      loadStatus: 'loading',
    }
  },
  onLoad() {
    this.getList(1)
  },
  methods: {
    getList(page) {
      // 请求数据，返回 promise
      return new Promise((resolve) => {
        setTimeout(() => {
          const start = (page - 1) * 10
          const arr = []
          for (let i = start; i < start + 10; i++) arr.push('数据' + (i + 1))
          this.list = this.list.concat(arr)
          resolve()
        }, 600)
      })
    },
    refresh() {
      this.page = 1
      this.list = []
      this.getList(1).then(() => {
        this.loadStatus = 'loading'
      })
    },
    loadmore() {
      this.page++
      this.getList(this.page).then(() => {
        this.loadStatus = 'loading'
      })
    },
  },
}

组件清单

| 组件 | 说明 | | ---- | ---- | | coolui-scroller | 滚动容器（下拉刷新 / 上拉加载 / 空态 / 回到顶部） | | coolui-scroller-refresh | 下拉刷新动画 | | coolui-scroller-loadmore | 上拉加载更多 | | coolui-scroller-back-to-top | 回到顶部 | | coolui-scroller-empty | 空列表占位 | | coolui-scroller-item | 列表项（水波纹） | | coolui-scroller-page | 长列表分页（旧方案：整页占位） | | coolui-scroller-longlist | 长列表窗口化容器（推荐：窗口外折叠为上下占位块，节点数与总页数无关） | | coolui-scroller-parallax | 下拉视差 | | coolui-scroller-nav | 分类导航 | | coolui-scroller-nav-bar | 顶部导航栏 | | coolui-scroller-nav-pannel | 切换容器 | | coolui-scroller-search | 搜索框 | | coolui-scroller-sort / coolui-scroller-sort-item | 排序筛选 | | coolui-scroller-second-floor / coolui-scroller-second-floor-refresh | 下拉二楼 | | coolui-scroller-handtip | 手势提示 |

TypeScript 支持

组件全部使用 <script setup lang="ts"> 编写：props 用 PropType<T> 精确标注、defineEmits 标注了事件名与参数类型、provide/inject 带上了通信 API 类型，编辑器（Volar / vue-tsc）可获得完整提示。

公共类型集中在 types.d.ts，可直接引入复用：

import type {
  CooluiScrollerProps,
  CooluiScrollerRefreshProps,
  CooluiRefreshConfig,
  CooluiSortOption,
} from 'coolui-scroller-uni/types'

• 组件内部通过 import type { Xxx } from '../../types' 复用这些类型；类型导入在构建时会被抹除，不产生运行时代码。
• utils/platform.js、utils/longlist.js 保持 JS 实现（便于直接发布源码供小程序构建），类型由同目录 *.d.ts 提供。
• 本包自带 tsconfig.json 与类型检查脚本：

cd packages/uniapp
pnpm type-check   # vue-tsc --noEmit

为保证运行时行为与原生版完全一致（type: String/Number/Array 的类型转换、Boolean 隐式转换等），props 采用运行时声明 + PropType<T> 标注，而不是 defineProps<泛型>()（后者会让编译产物丢失运行时 type）。 组件内部实现由历史 JS 迁移而来，tsconfig 暂未开启 strict；公共 API 类型已精确，内部类型可后续逐步收紧。

组件通信

原生微信小程序版通过 relations 关联父子组件，uni-app 版改为 Vue provide/inject：

• coolui-scroller → coolui-scroller-refresh / coolui-scroller-back-to-top
• coolui-scroller-refresh → coolui-scroller-parallax
• coolui-scroller-nav-pannel → coolui-scroller
• coolui-scroller-sort → coolui-scroller-sort-item
• coolui-scroller-second-floor → coolui-scroller-second-floor-refresh / coolui-scroller-nav-bar

使用时保持组件的嵌套层级与文档一致即可，无需手动配置。

与原生微信小程序版的差异

• 保留字属性改名：原生微信小程序版的 key 在 Vue 中为保留字，search 组件改用 keyword，通过 @update:keyword 同步。
• 事件命名：原生微信小程序版的 bind:xxx 对应 Vue 的 @xxx（如 bind:refresh → @refresh）；受控属性通过 @update:propName 同步（如 sort-item 的 @update:value）。

示例工程

仓库内提供 demo/uniapp 示例工程（Vue3 + Vite，编译到微信小程序）：

pnpm install
pnpm --filter demo-uniapp build:mp-weixin   # 编译到微信小程序
pnpm --filter demo-uniapp dev:mp-weixin     # 开发模式（watch）

用微信开发者工具打开 demo/uniapp/dist/build/mp-weixin 即可预览。

示例工程已配置 easycom（组件免 import）与 unplugin-auto-import（Vue API 免 import），页面内不出现任何组件或 ref 之类的 import，可直接作为接入参考。

目录结构

packages/uniapp/
├── components/
│   ├── coolui-scroller/          # 滚动容器
│   ├── coolui-scroller-refresh/  # 下拉刷新
│   └── ...                       # 其余组件
├── utils/
│   ├── platform.js               # 跨端 API 封装
│   ├── platform.d.ts             # 类型声明
│   ├── longlist.js               # 长列表分页工具
│   └── longlist.d.ts             # 类型声明
├── types.d.ts                    # 公共类型（props / emits / 组件间通信）
├── shims.d.ts                    # uni-app 内置组件声明
├── tsconfig.json                 # 类型检查配置
└── index.js                      # 入口（install 插件 + 组件导出）

AI 助手支持

组件库为 AI 编码助手（Cursor / Claude Code / GitHub Copilot 等）准备了分层文档，装到项目里也能读到。

1. 随包发布（安装后直接可读）

node_modules/coolui-scroller-uni/AGENTS.md   # 组件心智模型、最小可用示例、高频坑
node_modules/coolui-scroller-uni/llms.txt    # 该包的文档索引与关键事实

2. 线上全量文档（内容最全，推荐）

• 索引：https://wzs28150.github.io/coolui-scroller/v4/llms.txt
• 单文件全文（全部组件 API + 示例）：https://wzs28150.github.io/coolui-scroller/v4/llms-full.txt

3. 让 AI 自动找到它

把下面这段放进你自己项目的 AGENTS.md（或 Cursor 的 Rules、.cursor/rules/*.mdc）：

## coolui-scroller-uni

使用 coolui-scroller-uni 组件前，先读 node_modules/coolui-scroller-uni/AGENTS.md；
需要完整组件 API 与示例时，读 https://wzs28150.github.io/coolui-scroller/v4/llms-full.txt

本包内的 AGENTS.md、llms.txt 由 pnpm docs:llms 依据 doc/ 下的文档自动生成，请勿手工编辑。

使用文档

各组件详细属性与配置见 coolui-scroller 官方文档。