# XPopup

**Repository Path**: binks_wine/xpopup

## Basic Information

- **Project Name**: XPopup
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2025-07-08
- **Last Updated**: 2025-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

零侵入弹窗XPopup

    一行代码搞定弹窗

+ 无需初始化
+ 无需在根布局配置
+ 可在非UI区域调用
+ 可定制高
+ 多种内置实现

## 安装

```typescript
ohpm i @chinalike/popup
```

## API介绍

以下配置中如果有和[全局配置](#全局配置)一样的名字函数，此次弹窗属性会按照本次配置生效

| 方法                       | 介绍                                                                      |
|:-------------------------|:------------------------------------------------------------------------|
| setDialogOptions         | 设置弹窗基础配置                                                                |
| setMaskRect              | 屏蔽对话框区域。大小不能超过主窗口                                                       |
| setAlignment             | 设置对话框的对齐方式                                                              |
| setOffset                | 对话框偏移量                                                                  |
| setInSubWindow           | 是否在子窗口中显示                                                               |
| setModal                 | 模态对话框                                                                   |
| setDismissOnTouchOutside | 允许用户单击遮罩层退出                                                             |
| setDismissOnBackPressed  | 设置是否支持按返回键关闭弹窗                                                          |
| setTransition            | 打开/关闭自定义对话框的动画参数                                                        |
| setMaskColor             | 设置遮罩层颜色                                                                 |
| setPopupCallback         | 设置弹窗回调                                                                  |
| setWidth                 | 设置Popup宽度，仅限于wrap=true                                                  |
| setHeight                | 设置Popup高度，仅限于wrap=true                                                  |
| setMaxWidth              | 设置Popup最大宽度，仅限于wrap=true                                                |
| setMinWidth              | 设置Popup最小宽度，仅限于wrap=true                                                |
| setMaxHeight             | 设置Popup最大高度，仅限于wrap=true                                                |
| setMinHeight             | 设置Popup最小高度，仅限于wrap=true                                                |
| setBackgroundColor       | 设置Popup背景                                                               |
| setBorderRadius          | 设置Popup圆角                                                               |
| setPopupPadding          | 设置Popup内边距                                                              |
| setpPrimaryColor         | 设置Popup主要颜色，比如确认按钮                                                      |
| setAutoDismiss           | 设置Popup操作完成后是否自动关闭弹窗,默认true,比如点击ConfirmPopup的确认按钮，默认自动关闭；如果为false，则不会关闭 |
| setPopupPosition         | 手动指定弹窗位置，只有Attach、Drawer、PartShadow类型有效，PartShadow类型只支持上下               |
| setWrap                  | 自定义组件时，是否NodeContainer包裹，默认为true                                        |
| setAttachCenter          | 设置依附组件、气泡组件与原始点击组件的相对居中                                                 |
| setAttachMargin          | 设置依附组件、气泡组件距离原始点击组件的距离                                                  |
| setArrowOffset           | 设置箭头偏移量，气泡弹窗有效                                                          |
| setArrowPositionCenter   | 设置箭头是否居中，气泡弹窗有效                                                         |
| setShadowColor           | 设置阴影颜色                                                                  |
| setShadowRadius          | 设置阴影半径，单位：vp                                                            |
| setShadowX               | 阴影X轴，单位：vp                                                              |
| setShadowY               | 阴影Y轴，单位：vp                                                              |
| setArrowTopLeftRadius    | 箭头尖左边弧度，单位：vp，气泡弹窗有效                                                    |
| setArrowTopRightRadius   | 箭头尖右边弧度，单位：vp ，气泡弹窗有效                                                   |
| setArrowDownLeftRadius   | 箭头底部左边弧度，单位：vp，气泡弹窗有效                                                   |
| setArrowDownRightRadius  | 箭头底部右边弧度，单位：vp，气泡弹窗有效                                                   |
| setArrowWidth            | 箭头宽度，单位：vp，气泡弹窗有效                                                       |
| setArrowHeight           | 箭头高度，单位：vp，气泡弹窗有效                                                       |
| setBorderColor           | 边框颜色                                                                    |
| setBorderSize            | 边框大小，单位：vp                                                              |
| setHintFontColor         | 设置Loading文字颜色                                                           |
| setHintFontSize          | 设置Loading文字大小                                                           |
| setLoadingProgressSize   | Loading大小                                                               |
| setLoadingProgressColor  | Loading颜色                                                               |
| setTitleFontSize         | 标题大小                                                                    |
| setTitleFontColor        | 标题颜色                                                                    |
| setTitleFontWeight       | 标题Weight                                                                |
| setTextFontSize          | 内容大小,列表时，列表项文字大小                                                        |
| setTextFontColor         | 内容颜色，列表时，列表项文字颜色                                                        |
| setTextFontWeight        | 内容Weight，列表时，列表项文字Weight                                                |
| setTextTextAlign         | 文本对齐方式，列表时，列表项文字对齐方式                                                    |
| setPlaceholder           | 输入框提醒                                                                   |
| setPlaceholderFont       | 输入框提醒样式                                                                 |
| setPlaceholderFontColor  | 输入框提醒颜色                                                                 |
| setButtonSpace           | 按钮间间距                                                                   |
| atView                   | 依附哪一个组件弹窗的ID,asAttach生效                                                 |
| asCustom                 | 自定义Popup                                                                |
| asCustomPopup            | 自定义Popup，自定义实现类需要继承自指定Popup                                             |
| asLoading                | 内置Loading                                                               |
| asConfirm                | 内置确认Popup                                                               |
| asAttach                 | 内置依附弹窗                                                                  |
| asInputConfirm           | 内置输入弹窗                                                                  |
| asBottomList             | 内置底部列表弹窗                                                                |
| asCenterList             | 内置中间列表弹窗                                                                |
| asDrawer                 | 内置侧滑弹窗，默认右侧侧滑                                                           |
| asPartShadow             | 内置局部遮罩层,需要在之前先调用atView(id)方法                                            |
| asPosition               | 内置指定点弹窗,需要在之前先调用setOffset方法                                             |
| asBubble                 | 内置气泡弹窗                                                                  |
| show                     | 显示弹窗                                                                    |
| dismiss                  | 隐藏弹窗                                                                    |
| dismissDelay             | 延时隐藏弹窗，默认延时300ms，单位毫秒                                                   |
| dismissAll               | 关闭所有弹窗                                                                  |
| dismissTop               | 关闭顶部弹窗                                                                  |

## 全局配置

| 方法                       | 介绍                                                               |
|:-------------------------|:-----------------------------------------------------------------|
| setPopupOptions          | 设置内置弹窗的属性                                                        |
| setBackgroundColor       | 设置内置弹窗的背景                                                        |
| setBorderRadius          | 设置内置弹窗的圆角                                                        |
| setPopupPadding          | 设置内置弹窗的内边距                                                       |
| setPrimaryColor          | 设置内置弹窗的主要颜色，如确认按钮颜色                                              |
| setAutoDismiss           | 操作完成后是否自动关闭弹窗,默认true,比如点击ConfirmPopup的确认按钮，默认自动关闭；如果为false，则不会关闭 |
| setMaskColor             | 设置遮罩层颜色                                                          |
| setModal                 | 模态对话框                                                            |
| setInSubWindow           | 是否在子窗口中显示                                                        |
| setDismissOnTouchOutside | 允许用户单击遮罩层退出                                                      |
| setDismissOnBackPressed  | 设置是否支持按返回键关闭弹窗                                                   |
| setWrap                  | 自定义组件时，是否NodeContainer包裹                                         |

## 使用

支持使用全局配置统一样式，也可以单独配置，全局配置权限最低，局部配置后覆盖全局配置

### Loading使用

```typescript
//默认调用
XPopup.Builder().asLoading().show()
//自定义内容
XPopup.Builder().asLoading("请求中...").show()
//禁止点击外部不可以关闭
XPopup.Builder().setDismissOnTouchOutside(false).asLoading().show()
//禁止侧滑或按返回按钮关闭
XPopup.Builder().setDismissOnBackPressed(false).asLoading().show()
```

### 依附弹窗

+ 实现方案一

  调用asAttach()实现

  ```typescript
  @Builder
  function attachCustomBuilder(data: AttachBean) {
    List({ space: 20 }) {
      ForEach(data.data, (item: string) => {
        CheckListItemComponent({
          text: item
        })
      })
    }.width("50%")
    .backgroundColor(Color.White)
    .borderRadius(10)
    .padding(15)
  }
  ```

  ```typescript
  let data = new AttachBean()
  data.data = ["数据1", "数据2", "数据3", "数据4"]
  XPopup.Builder().atView("attachBottomPopup").asAttach(wrapBuilder(attachCustomBuilder), data).show()
  ```

+ 实现方案二

  继承AttachPopup类调用asCustomPopup()实现
  ```typescript
  /**
   * 自定义依附弹窗
   */
  export class CustomAttachPopup extends BaseAttachPopup<AttachBean> {
    private data = new AttachBean()
  
    constructor() {
      super(wrapBuilder(customPopupBuilder))
      this.data.data = ["价格从高到低", "价格从低到高", "评价从高到低", "评价从低到高"]
      this.data.onCancel = () => {
        this.dismiss()
      }
      this.data.onConfirm = (item: string) => {
        this.dismiss()
        promptAction.showToast({
          message: item
        })
      }
      this.setParams(this.data)
    }
  
  
    borderRadius(): Length | BorderRadiuses | LocalizedBorderRadiuses | undefined {
      return 0
    }
  }
  
  @Builder
  function customPopupBuilder(data: AttachBean) {
    List() {
      ForEach(data.data, (item: string) => {
        ListItem() {
          Text(item).width("100%").padding(10)
        }.onClick(() => {
          data.onConfirm?.(item)
        })
      })
    }
  }
  ```
  ```typescript
  XPopup.Builder().setPopupPosition(PopupPosition.TOP).atView("attachPopupByExtend").asCustomPopup(new CustomAttachPopup()).show()
  ```

### 底部弹窗

+ 实现方案一

  继承BaseBottomPopup类调用asCustomPopup()实现

  ```typescript
  /**
   * 自定义底部弹窗
   */
  export class CustomBottomPopup extends BaseBottomPopup<CenterBean> {
    private data = new CenterBean("底部弹窗", "我是通过继承BaseBottomPopup实现弹窗", "没看明白", "学习了")
  
    constructor() {
      super(wrapBuilder(customPopupBuilder))
      this.setParams(this.data)
      this.data.dismiss = () => {
        this.dismiss()
      }
    }
  }
  
  @Builder
  function customPopupBuilder(data: CenterBean) {
    Column() {
      Text(data.title).fontSize(20).fontColor(Color.Blue).margin({ top: 20 })
      Text(data.content).margin(20)
      Button(data.confirmText).width("100%").onClick(data.dismiss)
      Button(data.cancelText)
        .width("100%")
        .backgroundColor(Color.White)
        .fontColor("#33333333")
        .onClick(() => {
          data.dismiss?.()
        })
    }
  }
  ```

  ```typescript
  XPopup.Builder().asCustomPopup(new CustomBottomPopup()).show()
  ```

### 中间弹窗

+ 实现方案一

  继承BaseCenterPopup类调用asCustomPopup()实现
  ```typescript
  /**
   * 自定义中间弹窗
   */
  export class CustomCenterPopup extends BaseCenterPopup<CenterBean> {
    private data = new CenterBean("中间弹窗", "我是通过继承BaseCenterPopup实现弹窗", "没看明白", "学习了")
  
    constructor() {
      super(wrapBuilder(customPopupBuilder))
      this.setParams(this.data)
      this.data.dismiss = () => {
        this.dismiss()
      }
    }
  }
  
  @Builder
  function customPopupBuilder(data: CenterBean) {
    Column() {
      Text(data.title).fontSize(20).fontColor(Color.Blue).margin({ top: 20 })
      Text(data.content).margin(20)
      Button(data.confirmText).width("100%").onClick(data.dismiss)
      Button(data.cancelText)
        .width("100%")
        .backgroundColor(Color.White)
        .fontColor("#33333333")
        .onClick(() => {
          data.dismiss?.()
        })
    }
  }
  ```
  ```typescript
  XPopup.Builder().asCustomPopup(new CustomCenterPopup()).show()
  ```

### 确认弹窗

```typescript
XPopup.Builder()
  .setPopupCallback({
    onAction: (data?: PopupAction) => {

    }
  })
  .asConfirm("请问您是否关闭弹窗?")
  .show()
```

### 抽屉弹窗

+ 实现方案一

  调用asDrawer()实现

  ```typescript
  XPopup.Builder()
    .asDrawer(wrapBuilder(drawerRightCustomBuilder))
    .show()
  ```

+ 实现方案二

  继承BaseCenterPopup类调用asCustomPopup()实现

  ```typescript
  /**
   * 自定义抽屉弹窗
   */
  export class CustomDrawerPopup extends BaseDrawerPopup<CenterBean> {
    private data = new CenterBean("中间弹窗", "我是通过继承BaseCenterPopup实现弹窗", "没看明白", "学习了")
  
    constructor() {
      super(wrapBuilder(customPopupBuilder))
      this.setParams(this.data)
      this.data.dismiss = () => {
        this.dismiss()
      }
    }
  }
  
  @Builder
  function customPopupBuilder(data: CenterBean) {
    Column() {
      Text(data.title).fontSize(20).fontColor(Color.Blue).margin({ top: 20 })
      Text(data.content).margin(20)
      Button(data.confirmText).width("100%").onClick(data.dismiss)
      Button(data.cancelText)
        .width("100%")
        .backgroundColor(Color.White)
        .fontColor("#33333333")
        .onClick(() => {
          data.dismiss?.()
        })
    }
  }
  ```

  ```typescript
   XPopup.Builder()
      .asCustomPopup(new CustomDrawerPopup())
      .show()
  ```

### 输入框

```typescript
XPopup.Builder()
  .setPopupCallback({
    onAction: (data?: PopupAction) => {
      data?.dismiss()
      promptAction.showToast({ message: "输入内容:" + data?.data })
    }
  })
  .setAutoDismiss(false)
  .asInputConfirm("请输入", "请输入姓名")
  .show()
```

### 局部阴影弹窗

+ 实现方案一

  调用asPartShadow()实现

  ```typescript
  XPopup.Builder()
    .atView("partShadowBottomPopup")
    .asPartShadow(wrapBuilder(partShadowCustomBuilder))
    .show()
  ```

+ 实现方案二

  继承BasePartShadowPopup类调用asCustomPopup()实现

  ```typescript
  /**
   * 自定义局部阴影弹窗
   */
  export class CustomPartShadowPopup extends BasePartShadowPopup<CenterBean> {
    private data = new CenterBean("中间弹窗", "我是通过继承BaseCenterPopup实现弹窗", "没看明白", "学习了")
  
    constructor() {
      super(wrapBuilder(customPopupBuilder))
      this.setParams(this.data)
      this.data.dismiss = () => {
        this.dismiss()
      }
    }
  }
  
  @Builder
  function customPopupBuilder(data: CenterBean) {
    Column() {
      Text(data.title).fontSize(20).fontColor(Color.Blue).margin({ top: 20 })
      Text(data.content).margin(20)
      Button(data.confirmText).width("100%").onClick(data.dismiss)
      Button(data.cancelText)
        .width("100%")
        .backgroundColor(Color.White)
        .fontColor("#33333333")
        .onClick(() => {
          data.dismiss?.()
        })
    }
  }
  ```

  ```typescript
  XPopup.Builder()
    .atView("partShadowPopupByExtend")
    .asCustomPopup(new CustomPartShadowPopup())
    .show()
  ```

### 自由定位弹窗

+ 实现方案一

  调用asPosition()实现

  ```typescript
  XPopup.Builder()
    .setOffset({
      dx: 50,
      dy: 200
    })
    .asPosition(wrapBuilder(positionCustomBuilder))
    .show()
  ```

+ 实现方案二

  继承BasePositionPopup类调用asCustomPopup()实现

  ```typescript
  /**
   * 自定义点位弹窗
   */
  export class CustomPositionPopup extends BasePositionPopup<CenterBean> {
    private data = new CenterBean("中间弹窗", "我是通过继承BaseCenterPopup实现弹窗", "没看明白", "学习了")
  
    constructor() {
      super(wrapBuilder(customPopupBuilder))
      this.setParams(this.data)
      this.data.dismiss = () => {
        this.dismiss()
      }
    }
  }
  
  @Builder
  function customPopupBuilder(data: CenterBean) {
    Column() {
      Text(data.title).fontSize(20).fontColor(Color.Blue).margin({ top: 20 })
      Text(data.content).margin(20)
      Button(data.confirmText).width("100%").onClick(data.dismiss)
      Button(data.cancelText)
        .width("100%")
        .backgroundColor(Color.White)
        .fontColor("#33333333")
        .onClick(() => {
          data.dismiss?.()
        })
    }
  }
  ```

  ```typescript
  XPopup.Builder()
    .asCustomPopup(new CustomPositionPopup())
    .show()
  ```

### 气泡弹窗

+ 实现方案一

  调用asBubble实现

  ```typescript
  XPopup.Builder().atView("bubblePopup").asBubble(wrapBuilder(bubbleBuilder), new BubbleBean()).show()
  ```

+ 实现方案二

  继承BaseBubblePopup类调用asCustomPopup()实现

  ```typescript
  /**
   * 自定义气泡弹窗
   */
  export class CustomBubblePopup extends BaseBubblePopup<BubbleBean> {
  
    private data = new BubbleBean()
  
    constructor() {
      super(wrapBuilder(customPopupBuilder))
      this.data.data = ["编辑", "删除", "更新", "其他"]
      this.setParams(this.data)
    }
  
    beforeShow(): void {
      super.beforeShow()
      this.popupConfig.width = 150
      this.popupConfig.popupPadding = 0
      this.popupConfig.backgroundColor = "#33000000"
    }
  }
  
  @Builder
  function customPopupBuilder(data: BubbleBean) {
    List() {
      ForEach(data.data, (item: string) => {
        ListItem() {
          Text(item).padding(10).textAlign(TextAlign.Center).width("100%")
        }.onClick(() => {
  
        })
      })
    }
    .divider({
      strokeWidth:1,
      color:"#22FFFFFF"
    })
  }
  ```

  ```typescript
  XPopup.Builder()
    .setPopupPosition(PopupPosition.RIGHT)
    .atView("bubblePopupByCustom")
    .asCustomPopup(new CustomBubblePopup())
    .show()
  ```

### 自定义弹窗内容

+ 实现方案一

  调用asCustom实现

  ```typescript
  let bean = new BottomBean()
  let popup =
    XPopup.Builder()
      .setWrap(false)
      .setAlignment(DialogAlignment.Bottom)
      .asCustom(wrapBuilder(bottomBuilder), bean)
  bean.title = "底部弹窗"
  bean.onCancel = () => {
    popup.dismiss()
  }
  bean.onConfirm = () => {
    popup.dismiss()
  }
  popup.show()
  ```

+ 实现方案二

  继承BasePopup类调用asCustomPopup()实现

  ```typescript
  /**
   * 自定义弹窗
   */
  export class CustomPopup extends BasePopup<CustomBean> {
    private data = new CustomBean("顶部弹窗", "通过继承BasePopup类实现自定义弹窗", "没看明白", "学习了")
  
    constructor() {
      super(wrapBuilder(customPopupBuilder))
      this.setParams(this.data)
      this.data.dismiss = () => {
        this.dismiss()
      }
    }
  
    beforeShow(): void {
      super.beforeShow()
      this.dialogOptions.maskColor = "#33FF0000"
      this.dialogOptions.alignment = DialogAlignment.Top
      this.popupConfig.borderRadius = 40
    }
  
    popupWidth(): Length | undefined {
      return "90%"
    }
  
  }
  
  @Builder
  function customPopupBuilder(data: CustomBean) {
    Column() {
      Text(data.title).fontSize(20).fontColor(Color.Blue).margin({ top: 20 })
      Text(data.content).margin(20)
      Button(data.confirmText).width("100%").onClick(data.dismiss)
      Button(data.cancelText)
        .width("100%")
        .backgroundColor(Color.White)
        .fontColor("#33333333")
        .onClick(() => {
          data.dismiss?.()
        })
    }
  }
  ```
  ```typescript
  XPopup.Builder()
    .setOffset({
      dx: 0,
      dy: 40
    })
    .asCustomPopup(new CustomPopup())
    .show()
  ```