提示

當使用者將滑鼠游標移至目標元素上或輕觸目標元素時,工具提示會顯示說明文字。

工具提示可以定位在任何元素周圍,且元素內部可以包含任何 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 - 字串 - 要設定在指定工具提示中的新文字。

方法會傳回工具提示執行個體

工具提示參數

現在讓我們看看建立工具提示所需的可用參數清單

參數類型預設值說明
targetElHTMLElement
字串
工具提示目標元素。工具提示會顯示在此元素周圍。工具提示目標元素的 HTMLElement 或包含 CSS 選擇器的字串
text字串工具提示文字或 HTML 內容
offset數字0工具提示位置的額外偏移量(以像素為單位)
trigger字串hover定義如何觸發(開啟)工具提示。可以是 hoverclickmanual

如果為 hover - 工具提示會在桌上型電腦上滑鼠游標移入時切換,而在觸控裝置上輕觸並按住時切換

如果為 manual - 工具提示可見性應使用 tooltip.show()tooltip.hide() 方法控制

cssClass字串額外的 css class 會新增到 Tooltip 元素中。可用於額外的 tooltip 造型
renderfunction (tooltip)用於呈現 tooltip 元素的函式,必須傳回完整的 tooltip HTML 版面字串
containerElHTMLElement
字串
用於掛載 Tooltip 的元素。(預設為 app 根元素 app.el
delegated布林值false啟用委派 tooltip。如果你需要為多個元素顯示相同的 tooltip,這會很有用。在這種情況下,targetEl 必須指定為 CSS 選擇器字串,並且相同的 tooltip 將會重複用於指定的元素。
on物件

包含事件處理常式的物件。例如

var tooltip = app.tooltip.create({
  targetEl: '.some-link',
  on: {
    show: function () {
      console.log('Tooltip became visible')
    }
  }
})

Tooltip 方法和屬性

因此,若要建立 Tooltip,我們必須呼叫

var tooltip = app.tooltip.create({ /* parameters */ })

之後,我們會取得其初始化的執行個體(例如上方範例中的 tooltip 變數),其中包含有用的方法和屬性

屬性
tooltip.app連結至全域 app 執行個體
tooltip.targetElTooltip 目標 HTML 元素
tooltip.$targetEl包含 tooltip 目標 HTML 元素的 Dom7 執行個體
tooltip.elTooltip 本身的 HTML 元素
tooltip.$el包含 tooltip HTML 元素的 Dom7 執行個體
tooltip.textTooltip 文字/內容
tooltip.opened布林值屬性,表示它是否已開啟/顯示
tooltip.paramsTooltip 參數
方法
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:showTooltip 元素
Tooltip 目標
Tooltip 可見時觸發事件
tooltip:hideTooltip 元素
Tooltip 目標
Tooltip 隱藏時觸發事件
tooltip:beforedestroyTooltip 元素
Tooltip 目標
Tooltip 執行個體即將被銷毀前觸發事件

應用程式和 Tooltip 執行個體事件

Tooltip 執行個體在自身執行個體和應用程式執行個體上發出事件。應用程式執行個體事件具有相同名稱,但前面加上 tooltip

事件參數目標說明
show(tooltip)tooltipTooltip 可見時觸發事件。事件處理常式接收 Tooltip 執行個體作為參數
tooltipShow(tooltip)app
hide(tooltip)tooltipTooltip 隱藏時觸發事件。事件處理常式接收 Tooltip 執行個體作為參數
tooltipHide(tooltip)app
beforeDestroy(tooltip)tooltipTooltip 執行個體即將被銷毀前觸發事件。事件處理常式接收 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);
}

範例

tooltip.html
<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>