# hptdialog
**Repository Path**: fish_in_the_desert/gancao-hptdialog
## Basic Information
- **Project Name**: hptdialog
- **Description**: `hptdialog` 一款极简的弹框库，基于自定义弹框`CustomDialog`进行封装，并简化了其调用方式，帮助开发者快速实现自定义的弹框效果，目前包含
`hptdialog` 和 `hptBottomSheet`
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 3
- **Created**: 2025-07-10
- **Last Updated**: 2025-07-10
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# HPTDialog
# 简介
`HPTDialog` 一款极简的弹框库，基于自定义弹框`CustomDialog`进行封装，并简化了其调用方式（在任何地方只需要调用`show()`方法即可），帮助开发者快速实现自定义的弹框效果，目前包含
`HPTDialog` 和 `HPTBottomSheet` 以及 `HPTLoading`
# 效果展示
___
# 下载安装
`ohpm install @gancao/hptdialog`
# 接口与参数说明
- ## `HPTPopup`
**一个自定义的组件，需要在启动页作为底层组件**
- ## `HPTDialogUtil`
**用于弹出确认类型的弹框**
#### 接口
| **方法名** | **入参** | **描述** |
|--------------------------------------|-----------------------------------------------------------------------------------------------------------------|-------------|
| HPTDialogUtil.show | info: DialogInfo 显示的内容包括title、message等
config?: DialogConfig 弹框的样式配置 | 显示一个弹框 |
| HPTDialogUtil.showWithComponent | component: Object 当前所属页面的this
info: DialogInfo 显示的内容包括title、message等
config?: DialogConfig 弹框的样式配置 | 显示一个弹框 |
| HPTDialogUtil.showInput | info: DialogInputInfo 显示的内容包括title、text等
config?: DialogConfig 弹框的样式配置 | 显示一个带输入框的弹框 |
| HPTDialogUtil.showInputWithComponent | component: Object 当前所属页面的this
info: DialogInputInfo 显示的内容包括title、text等
config?: DialogConfig 弹框的样式配置 | 显示一个带输入框的弹框 |
#### `DialogInfo` 属性（描述弹框的内容）
| 属性名 | 类型 | 描述 |
|-------------------------------|-------------------------------------------|--------------------------------------------------------------------|
| `title` | `ResourceStr` | 弹框标题，可选 |
| `message` | `ResourceStr` | 弹框消息内容，可选 |
| `customMessage` | `CustomBuilder` | 自定义中间内容，用于覆盖`message`字段。注意：`messagePadding`对此字段无效 |
| `buttons` | `DialogButton[]` | 当需要多个按钮时使用，可以覆盖默认的取消和确认按钮；
DialogButton 类型见 DialogButton 参数说明 |
| `cancel` | `ResourceStr` | 取消按钮文字，默认为“取消” |
| `confirm` | `ResourceStr` | 确认按钮文字，默认为“确定” |
| `cancelOnClick` | `(controller?: DialogController) => void` | 取消按钮点击回调函数，通过`controller`可以控制是否关闭弹框 |
| `confirmOnClick` | `(controller?: DialogController) => void` | 确认按钮点击回调函数，同上，根据`controller`控制关闭逻辑 |
| `disableClickButtonAutoClose` | `boolean` | 是否禁止点击按钮后自动关闭弹框，默认自动关闭 |
#### `DialogInputInfo`
| 属性名 | 类型 | 默认值 | 描述 |
|-----------------|---------------------------|---------------------|------------------------------|
| `placeholder` | `ResourceStr` | - | 输入框提示文案 |
| `text` | `string` | - | 初始化内容 |
| `errorMsg` | `string` | - | 错误提示信息 |
| `defaultFocus` | `boolean` | `true` | 是否默认聚焦 |
| `inputType` | `InputType` | `Normal` | 输入类型，默认为普通文本输入 |
| `enterKeyType` | `EnterKeyType` | `EnterKeyType.Done` | 回车键类型，默认为完成（Done） |
| `maxLength` | `number` | - | 文本最大输入字符数，未指定则无限制 |
| `textAlign` | `TextAlign` | `TextAlign.Start` | 文本对齐方式，默认左对齐 |
| `showUnderline` | `boolean` | `false` | 是否显示下划线 |
| `maxLines` | `number` | `3` | 设置内联输入风格编辑态时文本可显示的最大行数。默认值：3 |
| `selectAll` | `boolean` | `false` | 初始状态，是否全选文本。默认值：false |
| `onChange` | `(value: string) => void` | - | 编辑回调，文本变化时触发的函数 |
| `enable` | `boolean` | `true` | 是否可用 |
#### `DialogConfig` 属性（描述弹框的样式）
| 属性名 | 类型 | 描述 |
|---------------------------------|---------------------------------|---------------------------------------------------------|
| `margin` | `Margin` | 距屏幕的间距 |
| `padding` | `Padding` | 内间距 |
| `border` | `BorderOptions` | 边框（圆角） |
| `backgroundColor` | `ResourceColor` | 内容背景颜色 |
| `fontSize` | `number 或 string 或 Resource` | 标题字体大小 |
| `fontColor` | `ResourceColor` | 标题字体颜色 |
| `fontWeight` | `number 或 FontWeight 或 string` | 字体粗细 |
| `titlePadding` | `Padding` | 标题区域的内边距 |
| `messageFontSize` | `number 或 string 或 Resource` | 内容字体大小 |
| `messageFontColor` | `ResourceColor` | 内容字体颜色 |
| `messageFontWeight` | `number 或 FontWeight 或 string` | 内容字体粗细 |
| `messagePadding` | `Padding` | 内容区域的内边距 |
| `buttonsUseVerticalLayoutCount` | `number` | 按钮改为垂直布局时的数量，默认小于此数量时，采用Row横向布局，如果大于等于此数量时，换成Column纵向布局 |
| `buttonVerticalSpacing` | `string 或 number` | 按钮垂直间距 |
| `buttonHorizontalSpacing` | `string 或 number` | 按钮水平间距 |
| `inputFontSize` | `number 或 string 或 Resource` | 输入框文字大小 |
| `inputFontColor` | `ResourceColor` | 输入框文字颜色 |
| `inputFontWeight` | `number 或 FontWeight 或 string` | 输入框字体粗细 |
| `placeholderFont` | `Font` | 提示文案字体样式 |
| `placeholderFontColor` | `ResourceColor` | 提示文案颜色 |
| `inputHeight` | `Length` | 输入框高度 |
| `inputBackgroundColor` | `ResourceColor` | 输入框背景色 |
| `selectedBackgroundColor` | `ResourceColor` | 文本选中时的底板颜色 |
| `inputBorder` | `BorderOptions` | 输入框边框样式 |
| `caretColor` | `ResourceColor` | 输入框光标颜色 |
| `inputPadding` | `Padding` | 输入框内边距 |
| `inputMargin` | `Padding` | 输入框外边距 |
| `customKeyboard` | `CustomBuilder` | 自定义键盘 |
| `cancelButtonStyle` | `CancelButtonStyle` | 清除按钮显示状态 |
| `cancelButtonSize` | `Length` | 清除按钮大小 |
| `cancelButtonIconColor` | `ResourceColor` | 清除按钮颜色 |
#### `DialogButton` 属性（弹框按钮）
| 属性名 | 类型 | 描述 |
|------------|-------------------------------------------|------------------------------------|
| `name` | `string` | 按钮的文本名称 |
| `style?` | `DialogButtonStyle` | 按钮的样式配置，可选 |
| `onClick?` | `(controller?: DialogController) => void` | 按钮点击时触发的回调函数，可接收一个自定义对话框控制器作为参数，可选 |
#### `DialogButtonStyle` 属性（弹框按钮样式）
| 属性名 | 类型 | 描述 |
|-------------------|--------------------------------|-----------------------|
| `height` | `Length` | 按钮的高度设置 |
| `fontSize` | `number 或 string 或 Resource` | 文本的字体大小，支持数字、字符串或资源引用 |
| `fontColor` | `ResourceColor` | 文本的颜色，通过资源定义 |
| `fontWeight` | `number 或 FontWeight 或 string` | 文本的字体粗细 |
| `backgroundColor` | `ResourceColor` | 按钮的背景颜色 |
| `border` | `BorderOptions` | 按钮边框的样式设置 |
- ## `HPTBottomSheetUtil`
#### 接口
| **方法名** | **入参** | **描述** |
|--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|----------|
| HPTBottomSheetUtil.show | info: BottomSheetInfo 显示的内容包括title、contentList等
config?: BottomSheetConfig 弹框的样式配置 | 显示一个底部弹框 |
| HPTBottomSheetUtil.showWithComponent | component: Object 当前所属页面的this
info: BottomSheetInfo 显示的内容包括title、contentList等
config?: BottomSheetConfig 弹框的样式配置 | 显示一个底部弹框 |
#### `BottomSheetInfo` 属性（描述弹框的内容）
| 属性名 | 类型 | 描述 |
|-------------------------------|--------------------------------|--------------------------------------------------------------------|
| `title` | `ResourceStr` | 底部弹窗的标题 |
| `contentList` | `ResourceStr[]` | 以列表形式展示的内容，默认不提供 |
| `selectedIndex` | `number` | 默认选中的行索引 |
| `customContent` | `CustomBuilder` | 自定义内容，用于覆盖`contentList`字段 |
| `cancel` | `ResourceStr` | 取消按钮的文字，默认为“取消” |
| `disableShowCancel` | `boolean` | 是否禁止显示取消按钮，默认不禁止 |
| `cancelOnClick` | `(controller?) => void` | 取消按钮点击回调函数，接收一个可选的`DialogController`参数，用于控制弹窗关闭逻辑 |
| `confirmOnClick` | `(index, controller?) => void` | 选中行的回调函数，接收行的索引`index`和一个可选的`DialogController`参数，用于执行相应操作并控制弹窗关闭逻辑 |
| `disableClickButtonAutoClose` | `boolean` | 是否禁止点击按钮后自动关闭弹窗，默认自动关闭 |
#### `BottomSheetConfig` 属性（描述弹框的样式）
| 属性名 | 类型 | 描述 |
|-------------------------------|--------------------------------|-------------------|
| `backgroundColor` | `ResourceColor` | 弹窗的背景颜色 |
| `borderRadius` | `number` | 底部弹窗的圆角大小 |
| `maxListHeight` | `number` | 列表选项模式下，弹窗的最大显示高度 |
| `itemHeight` | `number` | 每个列表项的高度 |
| `itemBackgroundColor` | `ResourceColor` | 列表项的背景颜色 |
| `itemSelectedBackgroundColor` | `ResourceColor` | 选中列表项的背景颜色 |
| `dividerColor` | `ResourceColor` | 分割线颜色 |
| `dividerHeight` | `Length` | 分割线高度 |
| `cancelSpace` | `Length` | 取消按钮与其它元素之间的间距 |
| `cancelHeight` | `Length` | 取消按钮的高度 |
| `titleAlign` | `TextAlign` | 标题的对齐方式 |
| `titlePadding` | `Padding` | 标题区域的内边距 |
| `titleFontSize` | `number 或 string 或 Resource` | 标题的字体大小 |
| `titleFontColor` | `ResourceColor` | 标题的字体颜色 |
| `titleFontWeight` | `number 或 FontWeight 或 string` | 标题的字体粗细 |
| `fontSize` | `number 或 string 或 Resource` | 文字的字体大小 |
| `fontColor` | `ResourceColor` | 文字的颜色 |
| `fontWeight` | `number 或 FontWeight 或 string` | 文字的字体粗细 |
- ## `HPTLoadingUtil`
#### 接口
| **方法名** | **入参** | **描述** |
|----------------------------------|-----------------------------------------------------------------------------------------------------|----------|
| HPTLoadingUtil.show | info: LoadingInfo 显示内容
config?: LoadingConfig Loading的样式配置 | 显示一个底部弹框 |
| HPTLoadingUtil.showWithComponent | component: Object 当前所属页面的this
info: LoadingInfo 显示内容
config?: LoadingConfig Loading的样式配置 | 显示一个底部弹框 |
#### `LoadingInfo` 属性（描述Loading的内容）
| 属性名 | 类型 | 描述 |
|---------|---------------|---------------|
| `title` | `ResourceStr` | 在Loading下显示文案 |
#### `LoadingConfig` 属性（描述弹框的样式）
| 属性名 | 类型 | 描述 |
|-------------------|-------------------------------------------|------------------------------------------------------|
| `maskColor` | `ResourceColor` | 底部遮罩层颜色，默认为透明。 |
| `padding` | `Padding` | 内部边距，默认为 `left: 16, right: 16, top: 16, bottom: 16`。 |
| `backgroundColor` | `ResourceColor` | 内容背景色，默认为透明。 |
| `border` | `BorderOptions` | 内容背景样式，默认圆角为6。 |
| `customLoading` | `CustomBuilder` | 支持传入自定义加载组件。 |
| `loadingWidth` | `Length` | 加载图标宽度。 |
| `loadingHeight` | `Length` | 加载图标高度。 |
| `styleType` | `LoadingStyleType` | 加载动画类型，默认为系统样式。 |
| `loadingColor` | `ResourceColor` | 加载图标颜色，仅当 `styleType` 为 `System` 时生效。 |
| `offset` | `Position` | 图标下文案的偏移量。 |
| `fontSize` | `number 或 string 或 Resource` | 图标下文案的字体大小。 |
| `fontColor` | `ResourceColor` | 图标下文案的字体颜色。 |
| `fontWeight` | `number 或 FontWeight 或 string` | 图标下文案的字体粗细。 |
- ## `PopupController`
| **方法名** | **入参** | **描述** |
|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|----------|
| close | void | 关闭弹框 |
- ## `PopupTextInputController`
| **方法名** | **入参** | **描述** |
|----------------|--------------------------------------------|--------|
| addListener | (text?: string, errorMsg?: string) => void | 添加监听 |
| removeListener | (text?: string, errorMsg?: string) => void | 关闭弹框 |
| get text | void | 获取输入内容 |
| set text | string? | 设置输入内容 |
| get errorMsg | void | 获取错误内容 |
| set errorMsg | string? | 设置错误 |
# 修改全局默认配置
```typescript
第一种设置默认配置方式:
// HPTDialog
HPTDialogUtil.defaultConfig.titlePadding = { bottom: 24 }
HPTDialogUtil.defaultConfig.fontSize = $r("app.float.h3")
HPTDialogUtil.defaultConfig.fontColor = $r("app.color.mainText")
HPTDialogUtil.defaultConfig.messageFontSize = $r("app.float.b4")
HPTDialogUtil.defaultConfig.messageFontColor = $r("app.color.promptText")
// HPTBottomSheet
HPTBottomSheetUtil.defaultConfig.itemSelectedBackgroundColor = $r("app.color.primary")
// HPTLoading
HPTLoadingUtil.defaultConfig.loadingColor = $r("app.color.secondary")
HPTLoadingUtil.defaultConfig.styleType = LoadingStyleType.eat
第二种设置默认配置方式:
HPTLoadingUtil.settingConfig((config) => {
config.styleType = LoadingStyleType.search
})
```
# 使用方式
### 1：在EntryAbility 中初始化
```
// 获取应用主窗口
let windowClass: window.Window = windowStage.getMainWindowSync();
// 配置（获取安全区域）
HPTPopup.init(windowClass)
```
### 2：在`@Entry`中使用 `HPTPopup` 作为底层组件
```
build() {
Column() {
HPTPopup() {
Column() {
}
}
}
}
```
### 2: HPTDialogUtil
```typescript
HPTDialogUtil.show({
title: '是否确认退出登录？',
cancel: "取消",
message: "退出说明xxxxx",
confirm: "确认退出",
confirmOnClick: () => {
// 执行退出登录逻辑
}
})
```
### 3：HPTDialogUtil 自定义
```typescript
HPTDialogUtil.show({
title: '是否确认退出登录？',
cancel: "取消",
confirm: "确认退出",
customMessage: () => this.buildItem("退出说明xxxxx", () => {
}),
confirmOnClick: () => {
}
})
// 显示输入
let inputController = HPTDialogUtil.showInput({
title: "请输入金额",
text: "2000",
placeholder: "1-1000",
inputType: InputType.Number,
disableClickButtonAutoClose: true,
confirmOnClick: async (_) => {
// inputController.text = "20"
// inputController.errorMsg = "错误xxxxx"
},
cancelOnClick: (_) => {
inputController.close()
// inputController.errorMsg = "错误xxxxx"
}
})
```
### 4：HPTBottomSheetUtil
```typescript
HPTBottomSheetUtil.show({
contentList: ['代煎', '不代煎', '每次手动选择'],
disableShowTitle: true
})
HPTBottomSheetUtil.show({
title: '选择方式',
contentInfoList: [
{
'name': '微信',
'fontColor': Color.Orange,
'fontSize': 40
},
{
'name': 'QQ',
},
{
'name': '微博',
'fontColor': Color.Red
}
],
confirmOnClick: (index, _) => {
console.log("选择" + index)
},
onWillDismiss: (dismissAction) => {
console.log("onWillDismiss")
dismissAction.dismiss()
}
}, {
titleFontColor: Color.Green
})
HPTBottomSheetUtil.showPicker({
range: [
"中国工商银行",
"中国建设银行",
"中国农业银行",
"中国邮政储蓄银行",
"中国银行",
"交通银行",
"招商银行",
"民生银行",
"中信银行",
"光大银行",
"华夏银行",
"兴业银行",
"浦发银行",
"平安银行",
"杭州银行"
],
selected: this.currentPickerSelected,
pickerConfirmOnClick: (value, selected) => {
console.log('选择银行' + value)
this.currentPickerSelected = selected as number
}
})
```
### 5：HPTLoadingUtil
```typescript
// 显示Loading
HPTLoadingUtil.show()
// 隐藏Loading
HPTLoadingUtil.hide()
```
# 注意️⚠️
1. **使用`show`方法之前，务必在`@Entry`中使用 `HPTPopup` 作为底层组件之一**
2. **如果使用`showWithComponent`方法，`component`参数是指当前的`@Component`的实例，如果传入类型错误，可能会抛出异常，导致弹框无法正常弹出**
# 目录结构
```
hptdialog
├── src
│ ├── main
│ │ │── ets
│ │ │ └── components
│ │ │ └── popup
│ │ │ └── HPTBottomSheetUtil.ets
│ │ │ └── HPTDialogUtil.ets
│ │ │ └── HPTLoadingUtil.ets
│ │ │ └── HPTToastUtil.ets
│ │ │ └── Popup.ets
│ │ │ └── PopupController.ets
│ │ │ └── PopupInfo.ets
│ │ │ └── utils
│ │ │ └── CommonUtil
│ │ └── resources
└──
```
# 项目地址
[仓库地址](https://gitee.com/iJianbao/gancao-hptdialog.git)