mp-components
v0.0.161
Published
wechat mini component
Maintainers
Keywords
Readme
mp-components
微信小程序组件库,提供丰富的 UI 组件和实用工具函数。
目录
安装
npm install mp-components工具函数
| 名称 | 类型 | 描述 | |-------------|----------------------------------|-----------------------| | reachBottom | Function(root, target, callback) | 监听目标元素底部,当到达底部时执行回调函数 | | countDown | Function(fn, seconds) | 倒计时功能 |
组件分类
导航组件
- mp-nav-bar - 导航栏
- mp-nav-bar-home - 带有主页按钮的导航栏
- mp-tab - 标签页
- mp-tab-panel - 标签面板
- mp-tab-panel-item - 标签面板项
布局组件
- mp-box - 盒子容器
- mp-line - 线条
- mp-text-line - 文本行
- mp-safe-bottom - 安全底部区域
- mp-bound-info - 边界信息
展示组件
- mp-ellipsis - 文本省略
- mp-image - 图片
- mp-dots - 点状指示器
- mp-pk-card - PK 卡片
- mp-pk-progress-bar - PK 进度条
- mp-count-down - 倒计时
反馈组件
- mp-popup - 弹出层
- mp-popup-v2 - 弹出层(增强版)
- mp-action-sheet - 动作面板
- mp-toast - 轻提示
- mp-dropdown-menu - 下拉菜单
- mp-dropdown-menu-item - 下拉菜单项
表单组件
- mp-button - 按钮
- mp-button-group - 按钮组
动画组件
- mp-expand - 展开动画
- mp-expand-enhanced - 增强展开动画
- mp-collapse - 折叠动画
- mp-fade - 淡入淡出动画
- mp-fade-slide-up - 淡入上滑动画
- mp-fade-slide-up-v2 - 淡入上滑动画(增强版)
- mp-fade-slide-up-v2-item - 淡入上滑动画项
- mp-slide - 滑动动画
组件详情
mp-nav-bar
导航栏组件,支持自定义左侧、标题和右侧内容。
属性
| 属性名 | 类型 | 默认值 | 描述 | |--------|---------|-------|-------| | bg | String | - | 背景色 | | zIndex | Number | - | 层级 | | custom | Boolean | false | 是否自定义 |
事件
| 事件名 | 描述 | |--------|------------| | height | 导航栏高度变化时触发 |
插槽
| 名称 | 描述 | |---------|------| | left | 左侧内容 | | title | 标题内容 | | default | 默认内容 |
提示:当 custom 属性为 true 时,left 和 title 插槽无效
示例
<mp-nav-bar custom="{{true}}">
<view slot="left">back</view>
<view slot="title">title</view>
<view>custom</view>
</mp-nav-bar>mp-popup-v2
增强版弹出层组件,支持多种弹出方式和动画效果。
属性
| 属性名 | 类型 | 默认值 | 描述 | |---------------|---------|-------------------|-----------------------------------------| | enable | Boolean | true | 是否从页面中脱离出来 | | mask-closable | Boolean | true | 是否点击背景时关闭 | | bg | String | rgba(0, 0, 0, .7) | 背景色 | | duration | Number | 0.2 | 动效时长(秒) | | top | String | 0 | 距离顶部距离 | | bottom | String | 0 | 距离底部距离 | | right | String | 0 | 距离右侧距离 | | left | String | 0 | 距离左侧距离 | | edge | String | bottom | 内容位置 (bottom, top, left, right, center) | | fade | Boolean | false | 是否开启淡入淡出效果 (如果开启,则不会有上、下、左、右滑入滑出效果) |
方法
| 方法名 | 描述 | |--------|---------| | toggle | 关闭、打开弹窗 | | open | 打开弹窗 | | close | 关闭弹窗 |
事件
| 事件名 | 描述 | |------------|---------| | bind:open | 弹窗打开时触发 | | bind:close | 弹窗关闭时触发 |
mp-bound-info
获取元素边界信息的组件。
方法
| 方法名 | 描述 | |----------|-----------------------------------------------------| | getBound | 获取元素的边界信息 (注意: 该方法的调用时机,以免获取值都是初始值;推荐使用 Event 绑定获取) |
事件
| 事件名 | 描述 | |------------|---------------| | bind:bound | 元素边界信息获取成功时触发 |
mp-safe-bottom
安全底部区域组件,用于适配不同机型的底部安全区域。
mp-toast
轻提示组件,用于展示简短的提示信息。
属性
| 属性名 | 类型 | 默认值 | 描述 | |---------------|---------|------------------------|------------------| | duration | Number | 2 | 显示时长(秒) | | speedDuration | Number | 0.1 | 0-1 出现 toast 的时长 | | bg | String | rgba(26, 23, 27, 0.90) | 内容背景色 | | radius | String | 12rpx | 内容圆角 | | message | String | - | 内容 | | top | String | null | 距离顶部距离 | | bottom | String | null | 距离底部距离 | | safe-top | Boolean | false | 是否启用顶部安全区域 | | safe-bottom | Boolean | false | 是否启用底部安全区域 |
方法
| 方法名 | 参数 | 描述 | |-------|------------------------------------------------------------------|----------| | toast | {message: string, duration: number, top: string, bottom: string} | 显示 toast |
mp-ellipsis
文本省略组件,用于处理多行文本的省略显示。
属性
| 属性名 | 类型 | 默认值 | 描述 | |-----------------------|---------|------------------|-----------| | content | String | - | 文本内容 | | contentClass | String | - | 内容类名 | | contentStyle | String | - | 内容样式 | | rows | Number | - | 显示行数 | | size | String | - | 字体大小 | | lineHeight | String | - | 行高 | | ellipsisColor | String | - | 省略符颜色 | | forceShowSlot | Boolean | - | 是否强制显示插槽 | | forceShowSlotPosition | String | 'end' 或 'suffix' | 强制显示插槽的位置 | | isAsync | Boolean | - | 是否异步 | | offset | Number | - | 偏移量 |
插槽
| 名称 | 描述 | |---------|------| | default | 默认内容 |
示例
<mp-ellipsis content="what???" rows="{{2}}">
<view>Slot</view>
</mp-ellipsis>mp-tab
标签页组件,用于在不同内容间切换。
属性
| 属性名 | 类型 | 默认值 | 描述 | |------------------|---------------|-----|----------| | data | Array | - | 数据源 | | labelField | String 或 null | - | 标签字段 | | active | Number | - | 当前激活项 | | height | String | - | 高度 | | gap | String | - | 间距 | | size | String | - | 字体大小 | | activeSize | String | - | 激活状态字体大小 | | color | String | - | 颜色 | | activeColor | String | - | 激活状态颜色 | | activeLineHeight | String | - | 激活线高度 | | activeLineColor | String | - | 激活线颜色 | | border | String | - | 边框 | | borderColor | String | - | 边框颜色 | | justifyBetween | Boolean | - | 是否两端对齐 | | itemStyle | String | - | 项目样式 | | activeItemStyle | String | - | 激活项目样式 | | startSize | Number | - | 起始大小 | | endSize | Number | - | 结束大小 |
事件
| 事件名 | 描述 | |--------|---------| | change | 切换标签时触发 |
示例
<comp data="{{['tab1', 'tab2']}}" height="120rpx" active="{{curTab}}" itemClass="item" catch:change='onChange'></comp>mp-popup
弹出层组件,用于展示弹出内容。
属性
| 属性名 | 类型 | 默认值 | 描述 | |--------------|---------|-----|----------| | visible | Boolean | - | 是否可见 | | bg | String | - | 背景色 | | maskClosable | Boolean | - | 点击蒙层是否关闭 | | duration | Number | - | 动画时长 | | type | String | - | 弹出类型 | | contentClass | String | - | 内容类名 |
type 可选值:bottom、top、left、right、center、center-scale
事件
| 事件名 | 描述 | |--------|-----------| | open | 打开时触发 | | opened | 打开动画结束时触发 | | close | 关闭时触发 | | closed | 关闭动画结束时触发 |
插槽
| 名称 | 描述 | |---------|------| | default | 默认内容 |
mp-dropdown-menu
下拉菜单组件,用于展示下拉选项。
属性
| 属性名 | 类型 | 默认值 | 描述 | |--------------|---------|-----|----------| | duration | Number | - | 动画时长 | | bg | String | - | 背景色 | | maskClosable | Boolean | - | 点击蒙层是否关闭 |
事件
| 事件名 | 描述 | |--------|-----------| | open | 打开时触发 | | opened | 打开动画结束时触发 | | close | 关闭时触发 | | closed | 关闭动画结束时触发 | | change | 选项变化时触发 |
方法
| 方法名 | 描述 | |-------|--------| | close | 关闭下拉菜单 |
插槽
| 名称 | 描述 | |---------|------| | default | 默认内容 |
mp-dropdown-menu-item
下拉菜单项组件,与 mp-dropdown-menu 配合使用。
插槽
| 名称 | 描述 | |---------|------| | default | 默认内容 | | title | 标题内容 |
示例
<mp-dropdown-menu maskClosable="{{true}}" catch:change="onMenuChange" catch:close="close" catch:closed="closed"
catch:open="open" catch:opened="opened">
<mp-dropdown-menu-item>
<view slot="title" class="menu-item">One</view>
<view style="background: #ffffff;">Content</view>
</mp-dropdown-menu-item>
<mp-dropdown-menu-item>
<view slot="title" class="menu-item">Two</view>
<view style="background: #ffffff;">Content2</view>
</mp-dropdown-menu-item>
<mp-dropdown-menu-item>
<view slot="title" class="menu-item">Three</view>
<view style="background: #ffffff;">Content3</view>
</mp-dropdown-menu-item>
</mp-dropdown-menu>.menu-item {
width: 100%;
padding: 20rpx 0;
}mp-dots
点状指示器组件,常用于轮播图等场景的指示。
属性
| 属性名 | 类型 | 默认值 | 描述 | |-------------|--------|-----|--------| | count | Number | - | 点的数量 | | current | Number | - | 当前激活点 | | radius | String | - | 圆角 | | gap | String | - | 间距 | | color | String | - | 颜色 | | activeColor | String | - | 激活状态颜色 | | activeWidth | String | - | 激活状态宽度 | | width | String | - | 宽度 | | height | String | - | 高度 |
事件
| 事件名 | 描述 | |--------|--------| | change | 切换点时触发 |
mp-pk-card
PK 卡片组件,用于展示对比内容。
属性
| 属性名 | 类型 | 默认值 | 描述 | |-----------|---------------|-----|-------| | bg | String | - | 背景色 | | bgOpacity | Number | - | 背景透明度 | | images | Array | - | 图片数组 | | gap | String | - | 间距 | | deg | Number | - | 角度 | | pLeft | String | - | 左侧内边距 |
插槽
| 名称 | 描述 | |-------|------| | left | 左侧内容 | | right | 右侧内容 |
事件
| 事件名 | 描述 | |--------|-------| | offset | 偏移时触发 |
示例
<view style="height: 500rpx;">
<mp-pk-card deg="{{-10}}">
<view slot="left" style="height: 100%; width: 100%; color: red; display: flex; align-items: flex-end;">
Left
</view>
<view slot="right"
style="height: 100%; width: 100%; color: red; display: flex; align-items: flex-end; justify-content: flex-end;">
Right
</view>
</mp-pk-card>
</view>mp-pk-progress-bar
PK 进度条组件,用于展示对比进度。
属性
| 属性名 | 类型 | 默认值 | 描述 | |------------|--------|-----|-----| | height | String | - | 高度 | | radius | String | - | 圆角 | | bg | String | - | 背景色 | | chunkWidth | String | - | 块宽度 | | value | String | - | 值 | | left | String | - | 左侧值 | | right | String | - | 右侧值 | | deg | Number | - | 角度 |
mp-image
图片组件,增强版的图片展示。
属性
| 属性名 | 类型 | 默认值 | 描述 | |--------|---------|-----|--------| | src | String | - | 图片源 | | lazy | Boolean | - | 是否懒加载 | | mode | String | - | 图片裁剪模式 | | radius | String | - | 圆角 | | bg | String | - | 背景色 |
mp-nav-bar-home
带有主页按钮的导航栏组件。
属性
| 属性名 | 类型 | 默认值 | 描述 | |------------------|---------|-----------------------------------------------------------------------------|----------------| | bg | String | rgba(255, 255, 255, 1) | 背景色 | | iconStyle | String | margin-left: 32rpx; | 图标样式 | | backStyle | String | width: 56rpx; height: 56rpx; | 返回按钮样式 | | homeStyle | String | width: 40rpx; height: 40rpx; | 主页按钮样式 | | backIcon | String | https://source-1259320891.cos.ap-shanghai.myqcloud.com/medias/nav-back.png | 返回图标 | | homeIcon | String | https://source-1259320891.cos.ap-shanghai.myqcloud.com/medias/home-icon.png | 主页图标 | | homePath | String | - | 主页路径 | | homePathIsTabBar | Boolean | true | 主页路径是否为 TabBar | | duration | Number | 400 | 动画时长 | | customBackEvent | Boolean | - | 是否自定义返回事件 | | placeholder | Boolean | - | 是否使用占位符 |
事件
| 事件名 | 描述 | |--------|-----------| | height | 高度变化时触发 | | back | 返回按钮点击时触发 |
示例
<!-- 基本用法 -->
<mp-nav-bar-home>
<view>Title</view>
</mp-nav-bar-home>
<!-- 带自定义参数 -->
<mp-nav-bar-home
bg="rgba(255, 255, 255, 1)"
iconStyle="margin-left: 32rpx;"
backStyle="width: 56rpx; height: 56rpx;"
homeStyle="width: 40rpx; height: 40rpx;"
backIcon="https://source-1259320891.cos.ap-shanghai.myqcloud.com/medias/nav-back.png"
homeIcon="https://source-1259320891.cos.ap-shanghai.myqcloud.com/medias/home-icon.png"
homePath=""
homePathIsTabBar="{{true}}"
duration="{{400}}"
>
<view>Title</view>
</mp-nav-bar-home>mp-line
线条组件,用于绘制边框线。
属性
| 属性名 | 类型 | 默认值 | 描述 | |--------|---------|-----|---------| | top | Boolean | - | 是否显示顶部线 | | right | Boolean | - | 是否显示右侧线 | | bottom | Boolean | - | 是否显示底部线 | | left | Boolean | - | 是否显示左侧线 | | radius | String | - | 圆角 | | color | String | - | 颜色 | | shadow | String | - | 阴影 |
示例
<mp-line top right bottom left color="blue" shadow="0 8rpx 16rpx 0 blue" radius="8rpx">
<mp-box>
<view>内容</view>
</mp-box>
</mp-line>mp-text-line
文本行组件,用于显示多行文本。
属性
| 属性名 | 类型 | 默认值 | 描述 | |------|--------|-----|------| | line | Number | - | 行数 | | text | String | - | 文本内容 |
mp-tab-panel、mp-tab-panel-item
标签面板组件,用于左右切换页面,不支持手势切换。
属性
| 属性名 | 类型 | 默认值 | 描述 | |----------|--------|-----|------| | height | String | - | 高度 | | current | Number | - | 当前项 | | duration | Number | - | 动画时长 |
示例
<mp-tab-panel current="{{current}}">
<mp-tab-panel-item>One</mp-tab-panel-item>
<mp-tab-panel-item>Two</mp-tab-panel-item>
<mp-tab-panel-item>Three</mp-tab-panel-item>
</mp-tab-panel>mp-expand
展开动画组件,用于实现展开/收起效果。
属性
| 属性名 | 类型 | 默认值 | 描述 | |-----------|---------|-------|----------------------------------------| | custom | Boolean | false | 是否自定义默认显示内容 | | direction | String | "top" | 展开方向,可选值:"top"、"bottom"、"left"、"right" | | duration | Number | 300 | 动画时长(ms) | | iconBg | String | - | 图标背景色 | | bg | String | - | 背景色 |
事件
| 事件名 | 描述 | |--------|--------------| | toggle | 切换展开/收起状态时触发 |
插槽
| 名称 | 描述 | |---------|------------------------------------------------| | default | 默认显示的内容 | | custom | 自定义显示的内容 (properties 传入 custom="{{true}}" 时生效) |
示例
<view class="add-feed-box">
<mp-expand catch:toggle="toggle">
<view class="add-feed-icon-2 {{expandVisible ? 'expand' : ''}}">
<image class="icon-item" mode="aspectFill"
src="https://sit-app-h5-1306106726.cos.ap-shanghai.myqcloud.com/prod/feed-image-icon.png"></image>
<image class="icon-item" mode="aspectFill"
src="https://sit-app-h5-1306106726.cos.ap-shanghai.myqcloud.com/prod/feed-video-icon.png"></image>
<view class="icon-item"></view>
</view>
</mp-expand>
</view>Page({
data: {
expandVisible: false,
},
toggle({ detail }) {
this.setData({ expandVisible: detail.visible })
},
}).add-feed-icon-2 {
width: 100rpx;
height: 100rpx;
border-radius: 50rpx;
transition: height 0.3s ease;
background-color: rgba(0, 0, 0, 0.32);
overflow: hidden;
}
.add-feed-icon-2.expand {
height: 364rpx;
}
.icon-item {
width: 100rpx;
height: 100rpx;
border-radius: 50rpx;
margin-bottom: 32rpx;
}mp-action-sheet
动作面板组件,用于展示底部弹出的操作菜单。
属性
| 属性名 | 类型 | 默认值 | 描述 | |----------|--------|-----|-------| | zIndex | Number | - | 层级 | | topBg | String | - | 顶部背景色 | | bottomBg | String | - | 底部背景色 | | gap | String | - | 间距 |
插槽
| 名称 | 描述 | |--------|------| | top | 顶部内容 | | bottom | 底部内容 |
示例
<mp-action-sheet>
<view slot="top" class="initial">
<view style="padding: 40rpx 0 0 0; display: flex; align-items: center; justify-content: space-between;">
<view>
<block wx:if="{{visible}}">
<text>微信用户昵称:杨苏州</text>
</block>
</view>
<image style="width: 56rpx; height: 56rpx;"
src="https://sit-app-h5-1306106726.cos.ap-shanghai.myqcloud.com/prod/clear-screen-icon.png"
bind:tap="toggle2"></image>
</view>
<mp-collapse visible="{{visible}}">
<mp-expand-enhanced style="color: #ffffff;" text="{{text}}" expand="{{expand}}" initialLine="2">
<view slot="left">
<button>话题</button>
<button>地址</button>
</view>
<view slot="right" style="background: #6E1013; padding: 4rpx 2rpx;" bind:tap="toggle">
{{expand ? '收起' : '展开'}}
</view>
</mp-expand-enhanced>
</mp-collapse>
</view>
<view slot="bottom" class="initial">
<Inp/>
</view>
</mp-action-sheet>mp-expand-enhanced
增强版展开动画组件,提供更多自定义选项。
属性
| 属性名 | 类型 | 默认值 | 描述 | |-------------------|---------|-------|-------------------------------| | expand | Boolean | - | 是否展开 | | text | String | - | 文本内容 | | initialLine | Number | - | 初始行数 | | gap | String | - | 间距 | | position | String | "end" | 位置,可选值:"start"、"center"、"end" | | initExpandVisible | Boolean | - | 初始展开状态是否可见 |
插槽
| 名称 | 描述 | |---------|------| | left | 左侧内容 | | right | 右侧内容 | | default | 默认内容 |
mp-collapse
折叠动画组件,用于实现内容的折叠/展开。
属性
| 属性名 | 类型 | 默认值 | 描述 | |----------|---------|-----|------| | visible | Boolean | - | 是否可见 | | duration | Number | - | 动画时长 |
插槽
| 名称 | 描述 | |---------|------| | default | 默认内容 |
mp-fade-slide-up
淡入上滑动画组件,用于实现内容的淡入上滑效果。
属性
| 属性名 | 类型 | 默认值 | 描述 | |----------|---------|-----|--------| | absolute | Boolean | - | 是否绝对定位 | | fixed | Boolean | - | 是否固定定位 | | position | String | - | 位置 | | visible | Boolean | - | 是否可见 | | duration | Number | - | 动画时长 | | offset | String | - | 偏移量 | | shadow | String | - | 阴影 | | radius | String | - | 圆角 | | bg | String | - | 背景色 |
插槽
| 名称 | 描述 | |---------|------| | default | 默认内容 |
mp-fade-slide-up-v2
mp-fade-slide-up-v2-item
mp-fade
淡入动画组件,上下滑动组件,用于实现内容的淡入上滑效果。
- mp-fade-slide-up-v2
| 属性名 | 类型 | 默认值 | 描述 | |-----------|---------|-----|-----------------------| | y | Number | - | 垂直偏移量 | | duration | Number | - | 动画时长 | | delay | Number | - | 延迟时间 | | triggered | Boolean | - | 动画键值 (如果是变量,每次都会触发动效) |
- mp-fade
| 属性名 | 类型 | 默认值 | 描述 | |----------|---------|-----|-----------------------| | duration | Number | - | 动画时长 | | key | Number | - | 动画键值 (如果是变量,每次都会触发动效) | | skip | Boolean | - | 是否跳过当前动画 |
mp-slide
滑动组件, 用于实现内容的滑动效果。
| 属性名 | 类型 | 默认值 | 描述 | |----------|---------|-----|-----------------------| | y | Number | - | 垂直偏移量 | | duration | Number | - | 动画时长 | | delay | Number | - | 延迟时间 | | key | Number | - | 动画键值 (如果是变量,每次都会触发动效) | | skip | Boolean | - | 是否跳过当前动画 |
示例
<view bind:tap="changeKey" style="margin-top: 10vh;">Click</view>
<mp-fade id="mp-fade" key="{{key}}" skip="{{key === 3}}">
<swiper current="{{key}}" duration="{{0}}"
style="margin-top: 10vh; width: 94vw; height: 60vh;">
<swiper-item style="width: 100%; height: 60vh;" wx:for="{{sliders}}" wx:key="*this">
<block wx:if="{{index !== 3}}">
<view
style="background: {{item}}; width: 100%;height: 100%; display: flex; flex-direction: column; justify-content: flex-end;">
</view>
</block>
<block wx:else>
<mp-fade-slide-up-v2 duration="{{0.4}}" triggered="{{key === 3}}" y="{{10}}">
<block wx:for="{{sliders}}" wx:key="*this">
<view style="width: 90vw; height: 200rpx; margin-bottom: 40rpx;">
<mp-fade-slide-up-v2-item>
<view style="width: 100%; height: 100%; background: {{item}}"></view>
</mp-fade-slide-up-v2-item>
</view>
</block>
</mp-fade-slide-up-v2>
</block>
</swiper-item>
</swiper>
<view style="width: 100vw; height: 20vh;">
<mp-slide id="mp-slide" key="{{key}}" skip="{{sliders.length - 1 === key}}">
<view style="width: 100%; box-sizing: border-box; padding: 20rpx 40rpx;">
<view style="background: aqua; width: 100%; height: 8vh;"></view>
</view>
</mp-slide>
</view>
</mp-fade>...
key: 0,
sliders
:
[ 'red', 'blue', 'green', 'purple' ]
...
changeKey()
{
const len = this.data.sliders.length
let next = this.data.key + 1
if (next > len - 1) next = 0
if (next < 3) {
this.selectComponent('#mp-fade')?.reset?.() // 慎用,若使用,必须根据自己的skip进行限制
this.selectComponent('#mp-slide')?.reset?.() // 同上
}
setTimeout(() => {
this.setData({ key: next })
}, 60)
}
...
this.selectComponent('#mp-fade')?.initialize?.()
this.selectComponent('#mp-slide')?.initialize?.()
...mp-count-down
倒计时组件,用于显示倒计时。
属性
| 属性名 | 类型 | 默认值 | 描述 | |---------|-----------------|-----|-------| | seconds | Number 或 String | - | 倒计时秒数 |
插槽
| 名称 | 描述 | |---------|--------| | before | 倒计时前内容 | | default | 默认内容 | | after | 倒计时后内容 |
