组件：气泡提示框

气泡提示框（Tooltip）组件用于在用户悬停、聚焦或点击某个元素时，在该元素附近弹出一个包含提示信息的气泡卡片。它支持四个方向（上、下、左、右）弹出，可自定义标题、内容、背景色、文本颜色、延迟时间等，适用于表单提示、操作说明、帮助信息、图标释义等场景。

典型使用场景：

表单字段的辅助说明（如密码格式提示）
图标按钮的功能释义（如“删除”、“编辑”）
数据展示的额外信息（如悬停显示完整内容）
新手引导中的操作提示

📌 继承自视图的成员速查

本组件继承自 视图 类，可直接使用以下属性和方法：

属性： ID、左边、顶边、右边、底边、宽度、高度、背景、背景颜色、背景图像、文本、文本颜色、字体、字体大小、字体粗细、行高、边框、边框圆角、边框宽度、光标样式、显示模式、透明度、外边距、外边距底、外边距左、外边距右、外边距顶、最大高度、最大宽度、最小高度、最小宽度、内边距、内边距底、内边距左、内边距右、内边距顶、定位、CLASS、InnerHTML、OuterHTML、内容水平对齐方式、首行缩进、可视、显示层级、内联样式、禁用

方法： 追加内联样式(样式文本)、置内联样式(名称,值)、取内联样式值(名称)、取Style对象()、添加事件(事件名称, 回调函数)、删除事件(事件名称, 回调函数)、获取焦点()、清除焦点()、添加样式类(类名称)、移除样式类(类名称)、取样式类列表()、取样式类()、执行单击()、取属性值(属性名)、取属性节点(属性名)、取布局参数()、取渲染宽度()、取渲染高度()、取渲染顶边()、取渲染左边()、左侧对齐到(目标组件,偏移量)、右侧对齐到(目标组件,偏移量)、顶边对齐到(目标组件,偏移量)、底边对齐到(目标组件,偏移量)、右侧对齐到左(目标组件, 偏移量)、左侧对齐到右(目标组件, 偏移量)、底边对齐到顶(目标组件, 偏移量)、顶边对齐到底(目标组件, 偏移量)、有指定属性(属性名)、有属性()、内容可编辑()、包含CSS类(类名)、取命名空间()、取下个节点()、取下个元素()、取节点名称()、取节点类型()、取父节点()、取父元素()、取上个节点()、取上个元素()、销毁()、删除属性(属性名)、删除属性节点(属性名)、置属性值(属性名, 属性值)、置属性节点(属性节点)、取标签名()、移动(左边顶边, 宽度, 高度)、取原生对象()、置被单击回调(回调函数)、置被双击回调(回调函数)、置鼠标被进入回调(回调函数)、置鼠标被移出回调(回调函数)、置鼠标被移动回调(回调函数)、置鼠标被按下回调(回调函数)、置鼠标被抬起回调(回调函数)、置鼠标滚轮被滚动回调(回调函数)、置键盘被按下回调(回调函数)、置按键被抬起回调(回调函数)、置按键被压下回调(回调函数)、置被失去焦点回调(回调函数)、置被获得焦点回调(回调函数)

事件： 被单击(源对象,事件源)、被双击(源对象,事件源)、鼠标被进入(源对象,事件源)、鼠标被移出(源对象,事件源)、鼠标被移动(源对象,事件源)、鼠标被按下(源对象,事件源)、鼠标被抬起(源对象,事件源)、鼠标滚轮被滚动(源对象,事件源)、键盘被按下(源对象,事件源)、按键被抬起(源对象,事件源)、按键被压下(源对象,事件源)、被失去焦点(源对象,事件源)、被获得焦点(源对象,事件源)

💡 完整成员列表及详细说明请参考：视图 类

常用操作速查

操作	属性/方法	示例
设置气泡标题	`标题`	`气泡提示框1.标题 = "提示"`
设置气泡内容	`内容`	`气泡提示框1.内容 = "这里是说明"`
设置弹出方向	`弹出位置`	`气泡提示框1.弹出位置 = "bottom"`
设置触发方式	`触发方式`	`气泡提示框1.触发方式 = "click"`
设置背景色	`背景颜色`	`气泡提示框1.背景颜色 = "#ffffff"`
设置文本颜色	`文本颜色`	`气泡提示框1.文本颜色 = "#333"`
设置显示延迟（毫秒）	`显示延迟`	`气泡提示框1.显示延迟 = 200`
设置隐藏延迟（毫秒）	`隐藏延迟`	`气泡提示框1.隐藏延迟 = 150`
绑定目标元素	`附加到视图(元素)`	`气泡提示框1.附加到视图(按钮1)`
解除绑定	`取消附加()`	`气泡提示框1.取消附加()`
销毁组件	`销毁()`	`气泡提示框1.销毁()`

样式美化参考

气泡提示框的外观可通过以下属性进行自定义：

整体容器：背景色和文本颜色分别由 背景颜色 和 文本颜色 控制，默认半透明黑色背景搭配白色文字。
方向与箭头：弹出位置 决定气泡相对于目标元素的方向，箭头会自动指向目标。
延迟控制：显示延迟 和 隐藏延迟 可控制提示框出现和消失的速度，避免误触。
边框与圆角：可通过继承的 边框圆角（建议 "6px"）和 边框 属性微调。
内边距：通过 内边距（建议 "8px 12px"）控制内容与边框的距离。

CSS 美化示例（在项目 CSS 文件中定义）：

.my-tooltip {
    border-radius: 6px;
    padding: 8px 12px;
    box-shadow: 0 2px 8px rgba(0,0,0,0.2);
    font-size: 13px;
}

在代码中应用样式类：气泡提示框1.添加样式类("my-tooltip")

基础示例

创建一个按钮，悬停时显示带标题和内容的气泡提示。

变量 气泡提示框1 = 创建 气泡提示框()
气泡提示框1.左边 = 50
气泡提示框1.顶边 = 50
气泡提示框1.标题 = "提示"
气泡提示框1.内容 = "这是一个简单的气泡提示"
气泡提示框1.弹出位置 = "top"
气泡提示框1.触发方式 = "hover"
气泡提示框1.背景颜色 = "rgba(0,0,0,0.75)"
气泡提示框1.文本颜色 = "#ffffff"
气泡提示框1.显示延迟 = 100
气泡提示框1.隐藏延迟 = 100

' 创建目标元素（按钮）
变量 按钮1 = 创建 按钮()
按钮1.文本 = "悬停我"
按钮1.宽度 = 100
按钮1.高度 = 36
' 将气泡绑定到按钮
气泡提示框1.附加到视图(按钮1)

' 先添加按钮到容器
添加组件(按钮1)
' 再添加气泡（气泡组件本身不可见，但需添加到视图树）
添加组件(气泡提示框1)

综合示例：表单字段辅助提示

本示例创建一个登录表单，为用户名和密码输入框分别添加气泡提示，说明输入要求。

' ========== 创建表单容器 ==========
变量 表单容器 = 创建 绝对布局()
表单容器.左边 = 30
表单容器.顶边 = 30
表单容器.宽度 = 360
表单容器.背景颜色 = "#ffffff"
表单容器.边框 = "1px solid #e8e8e8"
表单容器.边框圆角 = "12px"
表单容器.内边距 = "24px"
添加组件(表单容器)

' 标题
变量 标题 = 创建 标签()
标题.文本 = "🔐 登录"
标题.字体大小 = "20px"
标题.字体粗细 = "bold"
标题.内边距 = "0 0 16px 0"
表单容器.添加组件(标题)

' ----- 用户名输入框 -----
变量 用户标签 = 创建 标签()
用户标签.文本 = "用户名"
用户标签.字体大小 = "14px"
用户标签.文本颜色 = "#666"
用户标签.内边距 = "8px 0 4px"
表单容器.添加组件(用户标签)

变量 用户名输入 = 创建 单行输入框()
用户名输入.宽度 = 312
用户名输入.高度 = 36
用户名输入.提示文本 = "请输入用户名"
用户名输入.边框 = "1px solid #d9d9d9"
用户名输入.边框圆角 = "6px"
用户名输入.内边距 = "8px 12px"
表单容器.添加组件(用户名输入)

' 用户名气泡提示
变量 气泡_用户 = 创建 气泡提示框()
气泡_用户.标题 = "用户名要求"
气泡_用户.内容 = "4-16位字母或数字，不能包含特殊字符"
气泡_用户.弹出位置 = "right"
气泡_用户.触发方式 = "focus"  ' 获得焦点时弹出
气泡_用户.背景颜色 = "rgba(0,0,0,0.8)"
气泡_用户.文本颜色 = "#ffffff"
气泡_用户.显示延迟 = 0
气泡_用户.隐藏延迟 = 200
气泡_用户.附加到视图(用户名输入)
添加组件(气泡_用户)

' ----- 密码输入框 -----
变量 密码标签 = 创建 标签()
密码标签.文本 = "密码"
密码标签.字体大小 = "14px"
密码标签.文本颜色 = "#666"
密码标签.内边距 = "12px 0 4px"
表单容器.添加组件(密码标签)

变量 密码输入 = 创建 密码输入框()
密码输入.宽度 = 312
密码输入.高度 = 36
密码输入.占位提示 = "请输入密码"
密码输入.边框 = "1px solid #d9d9d9"
密码输入.边框圆角 = "6px"
密码输入.内边距 = "8px 12px"
密码输入.最大长度 = 20
表单容器.添加组件(密码输入)

' 密码气泡提示
变量 气泡_密码 = 创建 气泡提示框()
气泡_密码.标题 = "密码要求"
气泡_密码.内容 = "至少8位，包含大小写字母和数字"
气泡_密码.弹出位置 = "right"
气泡_密码.触发方式 = "focus"
气泡_密码.背景颜色 = "rgba(0,0,0,0.8)"
气泡_密码.文本颜色 = "#ffffff"
气泡_密码.显示延迟 = 0
气泡_密码.隐藏延迟 = 200
气泡_密码.附加到视图(密码输入)
添加组件(气泡_密码)

' ----- 登录按钮 -----
变量 登录按钮 = 创建 按钮()
登录按钮.文本 = "登 录"
登录按钮.宽度 = 312
登录按钮.高度 = 44
登录按钮.背景颜色 = "#1890ff"
登录按钮.文本颜色 = "#ffffff"
登录按钮.边框圆角 = "6px"
登录按钮.字体大小 = "16px"
表单容器.添加组件(登录按钮)

属性详解

标题

类型： 文本型
说明： 设置或获取气泡的标题文本，以粗体显示在内容上方。若为空，则不显示标题区域。

内容

类型： 文本型
说明： 设置或获取气泡的主体内容文本。支持纯文本或简单的 HTML（如 <br>、<strong> 等），但建议保持简洁。

弹出位置

类型： 文本型
说明： 设置或获取气泡相对于目标元素弹出的方向。可选值：
- "top"（默认）：在目标上方弹出
- "bottom"：在目标下方弹出
- "left"：在目标左侧弹出
- "right"：在目标右侧弹出组件会自动调整位置以确保气泡在可视区域内。

触发方式

类型： 文本型
说明： 设置或获取触发气泡显示的方式。可选值：
- "hover"（默认）：鼠标悬停时显示，移出时隐藏
- "click"：点击目标时切换显示/隐藏
- "focus"：目标元素获得焦点时显示，失去焦点时隐藏（适用于输入框）

背景颜色

类型： 文本型
说明： 设置或获取气泡的背景色，支持 CSS 颜色值。默认 "rgba(0,0,0,0.75)"（半透明黑色）。

文本颜色

类型： 文本型
说明： 设置或获取气泡内文本的颜色，支持 CSS 颜色值。默认 "#ffffff"（白色）。

显示延迟

类型： 数值型
说明： 设置或获取触发条件满足后，气泡显示之前的延迟时间（毫秒），避免误触。默认 100。

隐藏延迟

类型： 数值型
说明： 设置或获取触发条件消失后，气泡隐藏之前的延迟时间（毫秒），给用户留出阅读时间。默认 100。

函数详解

附加到视图(元素)

功能： 将气泡提示框绑定到目标元素上，当目标元素触发指定事件时，气泡会在其附近弹出。
参数： 元素，可以是：
- 视图组件实例（如 按钮1、输入框1）
- 原生 DOM 元素（如 创建元素("div") 返回的对象）
- 选择器字符串（如 "#myButton"）
返回值： 无。
示例： 气泡提示框1.附加到视图(用户名输入)

取消附加()

功能： 解除当前气泡与目标元素的绑定，并立即隐藏气泡（如果正在显示）。
返回值： 无。
示例： 气泡提示框1.取消附加()

销毁()

功能： 完全销毁气泡组件，从 DOM 中移除气泡节点并解除事件监听。调用后组件不可再用。
返回值： 无。
示例： 气泡提示框1.销毁()

⚠️ 注意事项

必须绑定目标元素：气泡本身不会自动显示，必须通过 附加到视图 绑定一个目标元素后才会生效。
父子容器顺序：建议先将目标元素添加到父容器，再将气泡添加到同一父容器，确保气泡的层级正确。
触发方式选择：hover 适合桌面端，click 适合移动端（因为移动端没有悬停状态），focus 适合输入框。
延迟时间：合理设置延迟可提升用户体验，避免过于灵敏或响应迟钝。
内容长度：气泡内容不宜过长，否则可能超出屏幕或被裁剪。若内容较多，可考虑使用更复杂的弹窗组件。
手动控制显示：组件本身不提供手动显示/隐藏的方法，完全由触发方式自动控制。
销毁与内存泄漏：当不再需要气泡时，应调用 销毁() 释放资源，尤其在动态创建/销毁的场景下。
样式覆盖：若自定义样式，注意覆盖默认的背景色和文字颜色，确保可读性。

轻语言网站开发SDK文档