提示
當使用者將滑鼠游標移至目標元素上或輕觸目標元素時,工具提示會顯示說明文字。
工具提示可以定位在任何元素周圍,且元素內部可以包含任何 HTML 內容。
工具提示配置
工具提示是僅限 JavaScript 的元件,它沒有任何 HTML 配置。
工具提示應用程式方法
我們需要建立/初始化工具提示。讓我們看看相關的應用程式方法,以使用工具提示
app.tooltip.create(parameters)- 建立工具提示執行個體
- parameters - 物件。包含工具提示參數的物件
方法會傳回已建立的工具提示執行個體
app.tooltip.destroy(targetEl)- 銷毀工具提示執行個體
- targetEl - HTMLElement 或 字串(包含 CSS 選擇器)或 物件(執行個體)。要銷毀的工具提示元素或工具提示執行個體。
app.tooltip.get(targetEl)- 透過其目標 HTML 元素取得工具提示執行個體
- targetEl - HTMLElement 或 字串(包含 CSS 選擇器)。工具提示目標元素。
方法會傳回工具提示執行個體
app.tooltip.show(targetEl)- 顯示工具提示
- targetEl - HTMLElement 或 字串(包含 CSS 選擇器)。工具提示目標元素。
方法會傳回工具提示執行個體
app.tooltip.hide(targetEl)- 隱藏工具提示
- targetEl - HTMLElement 或 字串(包含 CSS 選擇器)。工具提示目標元素。
方法會傳回工具提示執行個體
app.tooltip.setText(targetEl, text)- 變更工具提示文字
- targetEl - HTMLElement 或 字串(包含 CSS 選擇器)。工具提示目標元素。
- text - 字串 - 要設定在指定工具提示中的新文字。
方法會傳回工具提示執行個體
工具提示參數
現在讓我們看看建立工具提示所需的可用參數清單
參數 | 類型 | 預設值 | 說明 |
---|---|---|---|
targetEl | HTMLElement 字串 | 工具提示目標元素。工具提示會顯示在此元素周圍。工具提示目標元素的 HTMLElement 或包含 CSS 選擇器的字串 | |
text | 字串 | 工具提示文字或 HTML 內容 | |
offset | 數字 | 0 | 工具提示位置的額外偏移量(以像素為單位) |
trigger | 字串 | hover | 定義如何觸發(開啟)工具提示。可以是 hover 、click 或 manual 。如果為 如果為 |
cssClass | 字串 | 額外的 css class 會新增到 Tooltip 元素中。可用於額外的 tooltip 造型 | |
render | function (tooltip) | 用於呈現 tooltip 元素的函式,必須傳回完整的 tooltip HTML 版面字串 | |
containerEl | HTMLElement 字串 | 用於掛載 Tooltip 的元素。(預設為 app 根元素 app.el ) | |
delegated | 布林值 | false | 啟用委派 tooltip。如果你需要為多個元素顯示相同的 tooltip,這會很有用。在這種情況下,targetEl 必須指定為 CSS 選擇器字串,並且相同的 tooltip 將會重複用於指定的元素。 |
on | 物件 | 包含事件處理常式的物件。例如
|
Tooltip 方法和屬性
因此,若要建立 Tooltip,我們必須呼叫
var tooltip = app.tooltip.create({ /* parameters */ })
之後,我們會取得其初始化的執行個體(例如上方範例中的 tooltip
變數),其中包含有用的方法和屬性
屬性 | |
---|---|
tooltip.app | 連結至全域 app 執行個體 |
tooltip.targetEl | Tooltip 目標 HTML 元素 |
tooltip.$targetEl | 包含 tooltip 目標 HTML 元素的 Dom7 執行個體 |
tooltip.el | Tooltip 本身的 HTML 元素 |
tooltip.$el | 包含 tooltip HTML 元素的 Dom7 執行個體 |
tooltip.text | Tooltip 文字/內容 |
tooltip.opened | 布林值屬性,表示它是否已開啟/顯示 |
tooltip.params | Tooltip 參數 |
方法 | |
tooltip.show(targetEl) | 在 targetEl 元素周圍顯示 tooltip。如果未指定 targetEl ,則會使用初始化時在參數中傳遞的 targetEl |
tooltip.hide() | 隱藏 tooltip |
tooltip.setText(text) | 將 tooltip 文字或 HTML 內容變更為新的 |
tooltip.setTargetEl(targetEl) | 將 tooltip 的目標元素變更為指定的元素 |
tooltip.destroy() | 銷毀 tooltip 執行個體 |
tooltip.on(event, handler) | 新增事件處理常式 |
tooltip.once(event, handler) | 新增事件處理常式,在觸發後會移除 |
tooltip.off(event, handler) | 移除事件處理常式 |
tooltip.off(event) | 移除指定事件的所有處理常式 |
tooltip.emit(event, ...args) | 在執行個體上觸發事件 |
Tooltip 事件
Tooltip 會在 tooltip 元素上觸發下列 DOM 事件,以及在 app 和 tooltip 執行個體上觸發事件
DOM 事件
事件 | 目標 | 說明 |
---|---|---|
tooltip:show | Tooltip 元素 Tooltip 目標 | Tooltip 可見時觸發事件 |
tooltip:hide | Tooltip 元素 Tooltip 目標 | Tooltip 隱藏時觸發事件 |
tooltip:beforedestroy | Tooltip 元素 Tooltip 目標 | Tooltip 執行個體即將被銷毀前觸發事件 |
應用程式和 Tooltip 執行個體事件
Tooltip 執行個體在自身執行個體和應用程式執行個體上發出事件。應用程式執行個體事件具有相同名稱,但前面加上 tooltip
。
事件 | 參數 | 目標 | 說明 |
---|---|---|---|
show | (tooltip) | tooltip | Tooltip 可見時觸發事件。事件處理常式接收 Tooltip 執行個體作為參數 |
tooltipShow | (tooltip) | app | |
hide | (tooltip) | tooltip | Tooltip 隱藏時觸發事件。事件處理常式接收 Tooltip 執行個體作為參數 |
tooltipHide | (tooltip) | app | |
beforeDestroy | (tooltip) | tooltip | Tooltip 執行個體即將被銷毀前觸發事件。事件處理常式接收 Tooltip 執行個體作為參數 |
tooltipBeforeDestroy | (tooltip) | app |
Tooltip 自動初始化
如果您不需要使用 Tooltip API,而且您的 Tooltip 目標元素位於頁面內部,並在頁面初始化時顯示在 DOM 中,則只需將 tooltip-init
類別新增至目標元素,並在其 data-tooltip
屬性中指定 tooltip 文字,即可自動初始化。
<!-- Add tooltip-init class and specify tooltip text in data-tooltip attribute -->
<a href="/profile/" class="link tooltip-init profile-link" data-tooltip="Profile settings">
<i class="profile-icon"></i>
</a>
在這種情況下,如果您需要存取已建立的 Tooltip 執行個體,可以使用 app.tooltip.get
應用程式方法
var tooltip = app.tooltip.get('.profile-link');
// change tooltip text
tooltip.setText('Profile');
CSS 變數
以下是相關 CSS 變數 (CSS 自訂屬性) 清單。
:root {
--f7-tooltip-padding: 8px 16px;
--f7-tooltip-font-size: 14px;
--f7-tooltip-font-weight: 500;
--f7-tooltip-desktop-padding: 6px 8px;
--f7-tooltip-desktop-font-size: 12px;
}
.ios {
--f7-tooltip-border-radius: 4px;
--f7-tooltip-bg-color: rgba(0, 0, 0, 0.87);
--f7-tooltip-text-color: #fff;
}
.md {
--f7-tooltip-border-radius: 8px;
}
.md,
.md .dark,
.md [class*='color-'] {
--f7-tooltip-bg-color: var(--f7-md-secondary);
--f7-tooltip-text-color: var(--f7-md-on-secondary);
}
範例
<template>
<div class="page">
<div class="navbar">
<div class="navbar-bg"></div>
<div class="navbar-inner sliding">
<div class="title">Tooltip</div>
<div class="right">
<a class="link navbar-tooltip">
<i class="icon f7-icons if-not-md">info_circle_fill</i>
<i class="icon material-icons if-md">info_outline</i>
</a>
</div>
</div>
</div>
<div class="page-content">
<div class="block block-strong inset">
<p>Tooltips display informative text when users hover over, or tap an target element.</p>
<p>Tooltip can be positioned around any element with any HTML content inside.</p>
</div>
<div class="block block-strong inset">
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lacinia augue urna, in tincidunt augue
hendrerit ut. In nulla massa, facilisis non consectetur a, tempus semper ex. Proin eget volutpat nisl. Integer
lacinia maximus nunc molestie viverra. ${tooltipIcon} Etiam ullamcorper ultricies ipsum, ut congue tortor
rutrum at. Vestibulum rutrum risus a orci dictum, in placerat leo finibus. Sed a congue enim, ut dictum felis.
Aliquam erat volutpat. Etiam id nisi in magna egestas malesuada. Sed vitae orci sollicitudin, accumsan nisi a,
bibendum felis. Maecenas risus libero, gravida ut tincidunt auctor, ${tooltipIcon} aliquam non lectus. Nam
laoreet turpis erat, eget bibendum leo suscipit nec.</p>
<p>Vestibulum ${tooltipIcon} gravida dui magna, eget pulvinar ligula molestie hendrerit. Mauris vitae facilisis
justo. Nam velit mi, pharetra sit amet luctus quis, consectetur a tellus. Maecenas ac magna sit amet eros
aliquam rhoncus. Ut dapibus vehicula lectus, ac blandit felis ultricies at. In sollicitudin, lorem eget
volutpat viverra, magna ${tooltipIcon} felis tempus nisl, porta consectetur nunc neque eget risus. Phasellus
vestibulum leo at ante ornare, vel congue justo tincidunt.</p>
<p>Praesent tempus enim id lectus porta, at rutrum purus imperdiet. Donec eget sem vulputate, scelerisque diam
nec, consequat turpis. Ut vel convallis felis. Integer ${tooltipIcon} neque ex, sollicitudin vitae magna
eget, ultrices volutpat dui. Sed placerat odio hendrerit consequat lobortis. Fusce pulvinar facilisis rhoncus.
Sed erat ipsum, consequat molestie suscipit vitae, malesuada a ${tooltipIcon} massa.</p>
</div>
<div class="block-title">Auto Initialization</div>
<div class="block block-strong inset">
<p>For simple cases when you don't need a lot of control over the Tooltip, it can be initialized automatically
with <code>tooltip-init</code> class and <code>data-tooltip</code> attribute: <a style="display: inline-block"
class="button button-round button-outline button-small tooltip-init"
data-tooltip="Button tooltip text">Button with Tooltip</a></p>
</div>
</div>
</div>
</template>
<script>
export default (props, { $f7, $h, $theme, $onMounted, $onBeforeUnmount }) => {
let tooltipIcon = $theme.ios
? $h`<i style="font-size: 20px" class="icon f7-icons icon-tooltip">info_circle_fill</i>`
: $h`<i style="font-size: 20px" class="icon material-icons icon-tooltip">info</i>`;
let iconTooltip;
let navbarTooltip;
$onMounted(() => {
iconTooltip = $f7.tooltip.create({
targetEl: '.icon-tooltip',
text: 'Tooltip text',
});
navbarTooltip = $f7.tooltip.create({
targetEl: '.navbar-tooltip',
text: 'One more tooltip<br />with more text<br /><em>and custom formatting</em>'
});
})
$onBeforeUnmount(() => {
if (iconTooltip) iconTooltip.destroy();
if (navbarTooltip) navbarTooltip.destroy();
})
return $render;
}
</script>