yymini-pop-list

一款轻量级、无额外依赖、开箱即用的抖音/微信小程序底部列表弹出框自定义组件, 自定义列表数据源等核心功能，适用于底部列表选择、数据展示、参数配置等业务场景。

特性

• 跨平台兼容：无缝适配微信小程序与抖音小程序，无需额外适配开发
• 高度可定制：弹窗高度、标题、按钮文本、背景图、返回按钮显示状态
• 灵活交互控制：支持遮罩点击关闭，弹窗主体点击防穿透

安装

1. 执行 npm 安装

npm install yymini-pop-list --save
or
yarn add yymini-pop-list

2. 小程序构建 npm
   • 微信小程序：打开开发者工具 → 工具 → 构建 npm → 勾选「使用 npm 模块」
   • 抖音小程序：打开开发者工具 → 工具 → 构建 npm

快速使用

1. 配置组件

在需要使用弹窗的页面或组件的 json 文件中声明组件引用：

{
  "usingComponents": {
    "pop-list": "/miniprogram_npm/yymini-pop-list/pop-list"
  }
}

2. 页面中使用

在 ttml、wxml 中添加组件标签，绑定属性与事件：

<!-- 页面 wxml -->

<pop-list
  visible="{{isVisible}}"
  title="参数列表"
  isBackLeft="{{true}}"
  btnText="关闭"
  height="{{80}}"
  bgSrc="/images/bg-list.png"
  maskClosable="{{true}}"
  dataList="{{dataList}}"
  bind:close="onClose"
>
</pop-list>

在 js 中控制弹窗显示与事件处理：

Page({
  data: {
    isVisible: false,
    dataList: [
      { key: 'width', value: '80rpx' },
      { key: 'height', value: '60rpx' },
      { key: 'top', value: '150rpx' }
    ]
  },
  // 打开弹窗
  openPopup() {
    this.setData({ isVisible: true });
  },
  // 弹窗关闭事件（遮罩/关闭按钮触发）
  onClose(e) {
    console.log("弹窗关闭，触发类型：", e.detail.type);
    this.setData({ isVisible: false });
  }
})

组件属性

| 属性名 | 类型 | 默认值 | 说明 | |---------------- |---------|-------------- |---------------------------------------------------------------------- | | visible | Boolean | false | 【必填】控制弹窗的显示/隐藏 | | zindex | Number | 999 | 弹窗及遮罩层层级，默认999，可根据页面元素层级调整，避免被遮挡 | | isBackLeft | Boolean | true | 是否显示左侧返回按钮，默认显示 | | title | String | null | 弹窗顶部标题，为null时不显示标题区域 | | height | Number | 85 | 弹窗高度，单位为百分比（%），默认占屏幕高度的85% | | btnText | String | '取消' | 关闭按钮文本，可自定义文案（如“关闭”“返回”等） | | maskClosable | Boolean | true | 点击遮罩层是否关闭弹窗，默认关闭 | | bgSrc | String | "bgSrc.png" | 弹窗背景图片地址，默认值为"bgSrc.png"，需确保项目中存在该图片或自定义替换 | | dataList | Array | [] | 列表数据源，格式为[{key: 'xxx', value: 'xxx'}, ...]，用于初始化列表数据 |

组件事件

| 事件名 | 触发时机 | 事件参数 | 说明 | |----------------|--------------------------------------------|---------------------------|----------------------------------------------------------------------| | bind:close | 点击遮罩层或关闭按钮时触发 | { type: String } | type取值：mask（遮罩）、close（关闭按钮），用于区分关闭来源 |

效果预览

效果预览地址

注意事项

1. 平台适配：组件兼容微信小程序与抖音小程序
2. 数据源格式：dataList需传入数组格式，数组内每个元素需包含key和value字段，否则列表可能无法正常渲染
3. 背景图配置：默认背景图地址为“bgSrc.png”，若项目中无该图片，需通过bgSrc属性自定义替换，否则可能显示空白背景
4. 尺寸单位说明：height属性值为百分比，无需手动添加“%”符号
5. 防穿透设计：弹窗主体区域点击不会穿透到遮罩层，已通过stopPropagation方法阻止事件冒泡
6. 层级调整建议：若弹窗被其他页面元素遮挡，可增大zindex属性值（建议不超过9999，避免与系统层级冲突）