p-uni-ui 组件库文档

基于 uni-app + Vue3 + TypeScript 的小程序 UI 组件库

目录

• p-icon — 图标
• p-page — 页面容器
• p-page-loading — 页面加载遮罩
• p-paging — 分页列表
• p-preview-image — 图片预览

p-icon

通用图标组件，基于 iconfont 字体图标渲染。

基础用法

<p-icon name="back" size="48" color="#333333" />

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | name | string | — | 必填，图标名称，对应 iconfont class icon-{name} | | size | string \| number | 24 | 图标大小，单位 rpx | | color | string | #333333 | 图标颜色 | | fontStyle | object | {} | 额外的内联样式，会合并到图标元素上 |

Events

| 事件名 | 说明 | |--------|------| | click | 图标点击事件 |

示例

<p-icon name="home" size="56" color="#6a6af5" @click="onIconClick" />

p-page

页面容器组件，封装了状态栏、导航头部、可滚动主体、底部插槽及页面加载遮罩，适合作为每个页面的根容器使用。

基础用法

<p-page title="页面标题" :page-loading="loading">
  <template #body>
    <!-- 页面主体内容 -->
  </template>
</p-page>

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | title | string | '' | 页面标题（使用默认 header 时显示） | | pageLoading | boolean | false | 是否显示页面加载遮罩 | | hasHeader | boolean | true | 是否显示头部 | | hasScrollBody | boolean | true | 页面主体是否可滚动 | | pageBackgroundColor | string | #ffffff | 页面背景色 | | headerBackgroundColor | string | rgba(0,0,0,0) | 头部背景色 | | bodyBackgroundColor | string | rgba(0,0,0,0) | 主体背景色 | | footerBackgroundColor | string | rgba(0,0,0,0) | 底部背景色 | | titleColor | string | #272727 | 标题及返回按钮颜色 | | titleWeight | number | 500 | 标题字重 | | showBack | boolean | true | 是否显示返回按钮（多页面栈时生效） | | showHome | boolean | false | 是否显示 Home 按钮 | | backDelta | number | 1 | 返回的页面层数 | | checkSafeBottom | boolean | true | 是否开启底部安全距离 | | isTabBarPage | boolean | false | 是否为 TabBar 页面（影响高度计算和导航按钮） | | refresh | Function | — | 传入后开启下拉刷新，触发时调用此函数 |

Events

| 事件名 | 说明 | |--------|------| | refresh | 下拉刷新触发 | | lodeMore | 加载更多触发 | | pageRenderOk | 页面渲染完成 | | authClose | 授权弹窗关闭 |

Slots

| 插槽名 | 说明 | |--------|------| | header | 自定义头部内容，替换默认的标题区域（返回按钮仍保留） | | body | 页面主体内容（必填） | | footer | 底部内容，自动附加底部安全距离 | | pendant | 悬浮层，脱离文档流，常用于悬浮按钮 |

示例

<!-- 自定义头部 -->
<p-page :page-loading="isLoading" header-background-color="#f5f5f5">
  <template #header>
    <text style="font-size: 32rpx; font-weight: bold;">自定义标题</text>
  </template>

  <template #body>
    <view>页面内容</view>
  </template>

  <template #footer>
    <button>提交</button>
  </template>
</p-page>

p-page-loading

页面加载遮罩组件，显示时以全屏白色蒙层覆盖内容，隐藏时带 500ms 淡出动画。

基础用法

<p-page-loading :visible="isLoading" />

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | visible | boolean | false | 必填，是否显示加载遮罩 |

Slots

| 插槽名 | 说明 | |--------|------| | custom | 自定义加载内容，不传则展示默认的三点弹跳动画 |

动画行为

| 行为 | 描述 | |------|------| | 显示 | visible 变为 true 时立即挂载，无过渡 | | 隐藏 | visible 变为 false 时触发 500ms 淡出，动画结束后卸载 DOM |

示例

<!-- 默认三点弹跳动画 -->
<p-page-loading :visible="loading" />

<!-- 自定义加载内容 -->
<p-page-loading :visible="loading">
  <template #custom>
    <view>加载中，请稍候...</view>
  </template>
</p-page-loading>

p-paging

分页列表组件，封装 z-paging，支持普通列表和瀑布流两种布局，内置加载遮罩切换。

基础用法

<p-paging :get-data-func="fetchList">
  <template #body="{ item }">
    <view>{{ item.name }}</view>
  </template>
</p-paging>

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | getDataFunc | (p: number, pc: number) => Promise<Result> | — | 必填，数据请求函数，p 为当前页，pc 为每页数量 | | layout | 'column' \| 'waterfall' | 'column' | 列表布局模式 | | gap | string \| number | 24 | 列表项间距，单位 rpx | | borderSplitStyle | string | 'none' | 列表项分割线样式，如 '1px solid #eee' | | loadingMoreNoMoreText | string | '没有更多了哦~' | 无更多数据提示文案 | | swicthLoadingMask | boolean | false | 刷新第一页时是否显示切换加载遮罩 | | columns | number | 2 | 瀑布流列数（仅 layout='waterfall' 时有效） | | selectorId | string | 'p-paging' | 唯一选择器 ID，页面多实例时需区分 |

getDataFunc 返回值类型

{
  data: any[];
  count: number;
  pages: { now: number; total: number };
}

Events

| 事件名 | 说明 | |--------|------| | refresh | 下拉刷新触发时 |

Slots

| 插槽名 | 参数 | 说明 | |--------|------|------| | top | — | 列表顶部固定区域 | | body | { item } | 列表每一项的内容 | | empty | — | 数据为空时展示的内容 |

暴露方法（defineExpose）

| 方法 | 参数 | 说明 | |------|------|------| | refresh() | — | 刷新列表，重置到第一页 | | removeData(condition) | (item) => boolean | 按条件删除列表中的某一项 | | getData() | — | 获取当前列表数据 |

示例

<template>
  <p-paging ref="pagingRef" :get-data-func="fetchList" layout="waterfall" :columns="2">
    <template #top>
      <view class="filter-bar">筛选区域</view>
    </template>

    <template #body="{ item }">
      <view class="card">
        <image :src="item.cover" mode="widthFix" />
        <text>{{ item.title }}</text>
      </view>
    </template>

    <template #empty>
      <view>暂无数据</view>
    </template>
  </p-paging>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const pagingRef = ref();

const fetchList = async (p: number, pc: number) => {
  const res = await api.getList({ page: p, pageSize: pc });
  return { data: res.list, count: res.total, pages: { now: p, total: res.pages } };
};

// 手动刷新
const handleRefresh = () => pagingRef.value.refresh();
</script>

p-preview-image

图片预览组件，支持多图切换、手势缩放（1x ~ 4x）及长按保存。采用注册模式，需在根页面挂载组件，通过 RegisterPPreviewImage 全局调用。

安装：根页面挂载组件

<!-- App.vue 或页面根组件 -->
<template>
  <p-preview-image
    v-model:visible="RegisterPPreviewImage.visible.value"
    v-model:current="RegisterPPreviewImage.current.value"
    :urls="RegisterPPreviewImage.urls.value"
  />
</template>

<script setup lang="ts">
import { RegisterPPreviewImage } from 'p-uni-ui';
import PPreviewImage from 'p-uni-ui/components/p-preview-image/p-preview-image.vue';
</script>

调用预览

import { RegisterPPreviewImage } from 'p-uni-ui';

// 打开预览，currentIndex 为初始显示的图片索引
await RegisterPPreviewImage.open(imageUrls, 0);

Props（p-preview-image 组件）

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | urls | string[] | — | 必填，图片 URL 数组 | | current | number | 0 | 当前显示的图片索引，支持 v-model:current | | visible | boolean | false | 是否显示预览，支持 v-model:visible |

RegisterPPreviewImage API

| 属性 / 方法 | 类型 | 说明 | |-------------|------|------| | visible | Ref<boolean> | 预览显示状态 | | urls | Ref<string[]> | 图片 URL 列表 | | current | Ref<number> | 当前图片索引 | | open(pics, index) | Promise<boolean> | 打开预览，返回 Promise（关闭时 resolve false） | | cancel() | void | 主动关闭预览 |

交互说明

| 操作 | 行为 | |------|------| | 单击背景 | 关闭预览 | | 左右滑动 | 切换图片 | | 双指捏合 | 缩放图片（1x ~ 4x） | | 长按图片 | 触发 longpress 事件（可扩展保存图片等） |

更新日志

| 版本 | 说明 | |------|------| | 初始版本 | p-icon、p-page、p-page-loading、p-paging、p-preview-image |