Source

Chú giải công cụ

Tài liệu và ví dụ để thêm chú giải công cụ Bootstrap tùy chỉnh với CSS và JavaScript bằng cách sử dụng CSS3 cho hoạt ảnh và thuộc tính dữ liệu để lưu trữ tiêu đề cục bộ.

Tổng quan

Những điều cần biết khi sử dụng plugin chú giải công cụ:

  • Chú giải công cụ dựa vào thư viện bên thứ 3 Popper.js để định vị. Bạn phải bao gồm popper.min.js trước bootstrap.js hoặc sử dụng bootstrap.bundle.min.js/ bootstrap.bundle.jscó chứa Popper.js để chú giải công cụ hoạt động!
  • Nếu bạn đang xây dựng JavaScript của chúng tôi từ nguồn, nó yêu cầuutil.js .
  • Chú giải công cụ được chọn tham gia vì lý do hiệu suất, vì vậy bạn phải tự khởi tạo chúng .
  • Chú giải công cụ có tiêu đề dài bằng 0 không bao giờ được hiển thị.
  • Chỉ định container: 'body'để tránh các sự cố hiển thị trong các thành phần phức tạp hơn (như nhóm đầu vào, nhóm nút của chúng tôi, v.v.).
  • Kích hoạt chú giải công cụ trên các phần tử ẩn sẽ không hoạt động.
  • Chú giải công cụ cho .disabledhoặc disabledcác phần tử phải được kích hoạt trên một phần tử trình bao bọc.
  • Khi được kích hoạt từ các siêu liên kết trải dài nhiều dòng, chú giải công cụ sẽ được căn giữa. Sử dụng white-space: nowrap;trên <a>s của bạn để tránh hành vi này.
  • Chú giải công cụ phải được ẩn trước khi các phần tử tương ứng của chúng bị xóa khỏi DOM.
  • Chú giải công cụ có thể được kích hoạt nhờ vào một phần tử bên trong DOM bóng.

Hiệu ứng hoạt ảnh của thành phần này phụ thuộc vào prefers-reduced-motiontruy vấn phương tiện. Xem phần chuyển động giảm trong tài liệu hỗ trợ tiếp cận của chúng tôi .

Có tất cả những điều đó? Tuyệt vời, hãy xem chúng hoạt động như thế nào với một số ví dụ.

Ví dụ: Bật chú giải công cụ ở mọi nơi

Một cách để khởi tạo tất cả các chú giải công cụ trên một trang là chọn chúng theo data-togglethuộc tính của chúng:

$(function () {
  $('[data-toggle="tooltip"]').tooltip()
})

Các ví dụ

Di chuột qua các liên kết bên dưới để xem các chú giải công cụ:

Những chiếc quần bó sát cấp độ tiếp theo có thể bạn chưa từng nghe nói về chúng. Ảnh gian hàng râu vải thô denim letterpress túi đưa tin thuần chay stumptown. Seitan từ trang trại đến bàn ăn, quần áo Mỹ 8-bit quinoa bền vững fixie của mcsweeney có một chambray vinyl richardson terry. Beard stumptown, cardigans banh mi lomo Thundercats. Đậu phụ diesel sinh học williamsburg marfa, bánh chambray thuần chay làm sạch 4 loko mcsweeney. Một nghệ nhân thực sự mỉa mai bất cứ thứ gì keytar , scenester farm-to-table banky Austin twitter xử lý virus cà phê nguyên liệu denim freegan.

Di chuột qua các nút bên dưới để xem bốn hướng của chú giải công cụ: trên cùng, bên phải, dưới cùng và bên trái.

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
  Tooltip on left
</button>

Và với HTML tùy chỉnh được thêm vào:

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

Cách sử dụng

Plugin chú giải công cụ tạo nội dung và đánh dấu theo yêu cầu và theo mặc định đặt chú giải công cụ sau phần tử kích hoạt của chúng.

Kích hoạt chú giải công cụ qua JavaScript:

$('#example').tooltip(options)
Tràn autovàscroll

Vị trí chú giải công cụ cố gắng tự động thay đổi khi vùng chứa chính có overflow: autohoặc overflow: scrollgiống như của chúng tôi .table-responsive, nhưng vẫn giữ vị trí của vị trí ban đầu. Để giải quyết, hãy đặt boundarytùy chọn thành bất kỳ thứ gì khác với giá trị mặc định 'scrollParent', chẳng hạn như 'window':

$('#example').tooltip({ boundary: 'window' })

Đánh dấu

Đánh dấu bắt buộc cho chú giải công cụ chỉ là một datathuộc tính và titletrên phần tử HTML mà bạn muốn có chú giải công cụ. Đánh dấu được tạo của chú giải công cụ khá đơn giản, mặc dù nó yêu cầu một vị trí (theo mặc định, được đặt thành topbởi plugin).

Làm cho chú giải công cụ hoạt động cho người dùng bàn phím và công nghệ hỗ trợ

Bạn chỉ nên thêm chú giải công cụ vào các phần tử HTML truyền thống có thể lấy tiêu điểm bằng bàn phím và tương tác (chẳng hạn như liên kết hoặc điều khiển biểu mẫu). Mặc dù các phần tử HTML tùy ý (chẳng hạn như <span>các) có thể được đặt tiêu điểm bằng cách thêm tabindex="0"thuộc tính, điều này sẽ thêm các điểm dừng tab có thể gây khó chịu và khó hiểu trên các phần tử không tương tác cho người dùng bàn phím. Ngoài ra, hầu hết các công nghệ hỗ trợ hiện không công bố chú giải công cụ trong tình huống này.

Ngoài ra, đừng chỉ dựa vào hoverlàm trình kích hoạt cho chú giải công cụ của bạn, vì điều này sẽ khiến chú giải công cụ của bạn không thể kích hoạt cho người dùng bàn phím.

<!-- HTML to write -->
<a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

Các phần tử bị vô hiệu hóa

Các phần tử có disabledthuộc tính không tương tác, có nghĩa là người dùng không thể tập trung, di chuột hoặc nhấp vào chúng để kích hoạt chú giải công cụ (hoặc cửa sổ bật lên). Để giải quyết vấn đề này, bạn sẽ muốn kích hoạt chú giải công cụ từ một trình bao bọc <div>hoặc <span>lý tưởng là có thể lấy tiêu điểm bằng bàn phím bằng cách sử dụng tabindex="0"và ghi đè lên pointer-eventsphần tử bị vô hiệu hóa.

<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

Tùy chọn

Các tùy chọn có thể được chuyển qua các thuộc tính dữ liệu hoặc JavaScript. Đối với các thuộc tính dữ liệu, hãy nối tên tùy chọn vào data-, như trong data-animation="".

Tên Loại hình Mặc định Sự mô tả
hoạt hình boolean thật Áp dụng chuyển đổi mờ dần CSS cho chú giải công cụ
thùng đựng hàng chuỗi | phần tử | sai sai

Thêm chú giải công cụ vào một phần tử cụ thể. container: 'body'Ví dụ :. Tùy chọn này đặc biệt hữu ích ở chỗ nó cho phép bạn định vị chú giải công cụ trong luồng tài liệu gần phần tử kích hoạt - điều này sẽ ngăn chú giải công cụ trôi ra khỏi phần tử kích hoạt trong quá trình thay đổi kích thước cửa sổ.
sự chậm trễ số | sự vật 0

Độ trễ hiển thị và ẩn chú giải công cụ (mili giây) - không áp dụng cho loại kích hoạt thủ công

Nếu một số được cung cấp, độ trễ được áp dụng cho cả ẩn / hiện

Cấu trúc đối tượng là:delay: { "show": 500, "hide": 100 }
html boolean sai

Cho phép HTML trong chú giải công cụ.

Nếu đúng, các thẻ HTML trong chú giải công cụ titlesẽ được hiển thị trong chú giải công cụ. Nếu sai, phương thức của jQuery textsẽ được sử dụng để chèn nội dung vào DOM.

Sử dụng văn bản nếu bạn lo lắng về các cuộc tấn công XSS.
vị trí chuỗi | hàm số 'đứng đầu'

Cách định vị chú giải công cụ - tự động | đầu trang | đáy | trái | bên phải.
Khi autođược chỉ định, nó sẽ tự động định hướng lại chú giải công cụ.

Khi một hàm được sử dụng để xác định vị trí, nó được gọi với nút DOM của chú giải công cụ làm đối số đầu tiên và nút DOM phần tử kích hoạt là nút thứ hai của nó. Bối thiscảnh được đặt thành phiên bản chú giải công cụ.
bộ chọn chuỗi | sai sai Nếu một bộ chọn được cung cấp, các đối tượng chú giải công cụ sẽ được ủy quyền cho các mục tiêu được chỉ định. Trong thực tế, điều này cũng được sử dụng để áp dụng chú giải công cụ cho các phần tử DOM được thêm động ( jQuery.onhỗ trợ). Xem điều này và một ví dụ thông tin .
mẫu sợi dây '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

HTML cơ sở để sử dụng khi tạo chú giải công cụ.

Chú giải công cụ titlesẽ được đưa vào .tooltip-inner.

.arrowsẽ trở thành mũi tên của chú giải công cụ.

Phần tử bao bọc ngoài cùng phải có .tooltiplớp và role="tooltip".
Tiêu đề chuỗi | phần tử | hàm số ''

Giá trị tiêu đề mặc định nếu titlethuộc tính không có.

Nếu một hàm được cung cấp, nó sẽ được gọi với thistập tham chiếu của nó tới phần tử mà chú giải công cụ được gắn vào.
Kích hoạt sợi dây 'di chuột tiêu điểm'

Cách kích hoạt chú giải công cụ - nhấp vào | di chuột qua | tiêu điểm | thủ công. Bạn có thể vượt qua nhiều lần kích hoạt; ngăn cách chúng bằng một khoảng trắng.

'manual'cho biết rằng chú giải công cụ sẽ được kích hoạt theo chương trình thông qua .tooltip('show'), .tooltip('hide')và .tooltip('toggle')các phương thức; giá trị này không thể được kết hợp với bất kỳ trình kích hoạt nào khác.

'hover'riêng nó sẽ dẫn đến các chú giải công cụ không thể được kích hoạt thông qua bàn phím và chỉ nên được sử dụng nếu có các phương pháp thay thế để truyền tải cùng một thông tin cho người dùng bàn phím.
bù lại số | sợi dây 0 Phần bù của chú giải công cụ so với mục tiêu của nó. Để biết thêm thông tin, hãy tham khảo tài liệu bù đắp của Popper.js .
dự phòng chuỗi | mảng 'lật' Cho phép chỉ định vị trí mà Popper sẽ sử dụng khi dự phòng. Để biết thêm thông tin, hãy tham khảo tài liệu về hành vi của Popper.js
ranh giới chuỗi | yếu tố 'scrollParent' Ranh giới ràng buộc tràn của chú giải công cụ. Chấp nhận các giá trị của , 'viewport'hoặc một tham chiếu HTMLElement (chỉ JavaScript). Để biết thêm thông tin, hãy tham khảo tài liệu ngăn chặn dòng chảy của Popper.js .'window''scrollParent'

Thuộc tính dữ liệu cho các chú giải công cụ riêng lẻ

Ngoài ra, các tùy chọn cho chú giải công cụ riêng lẻ có thể được chỉ định thông qua việc sử dụng các thuộc tính dữ liệu, như đã giải thích ở trên.

Phương pháp

Các phương thức và chuyển tiếp không đồng bộ

Tất cả các phương thức API là không đồng bộ và bắt đầu quá trình chuyển đổi . Họ quay lại người gọi ngay sau khi quá trình chuyển đổi được bắt đầu nhưng trước khi quá trình chuyển đổi kết thúc . Ngoài ra, một lệnh gọi phương thức trên một thành phần chuyển tiếp sẽ bị bỏ qua .

Xem tài liệu JavaScript của chúng tôi để biết thêm thông tin .

$().tooltip(options)

Đính kèm trình xử lý chú giải công cụ vào tập hợp phần tử.

.tooltip('show')

Tiết lộ chú giải công cụ của một phần tử. Trả về trình gọi trước khi chú giải công cụ thực sự được hiển thị (tức là trước khi shown.bs.tooltipsự kiện xảy ra). Đây được coi là cách kích hoạt "thủ công" của chú giải công cụ. Chú giải công cụ có tiêu đề dài bằng 0 không bao giờ được hiển thị.

$('#element').tooltip('show')

.tooltip('hide')

Ẩn chú giải công cụ của phần tử. Trả về trình gọi trước khi chú giải công cụ thực sự bị ẩn (tức là trước khi hidden.bs.tooltipsự kiện xảy ra). Đây được coi là cách kích hoạt "thủ công" của chú giải công cụ.

$('#element').tooltip('hide')

.tooltip('toggle')

Chuyển đổi chú giải công cụ của phần tử. Trả về trình gọi trước khi chú giải công cụ thực sự được hiển thị hoặc bị ẩn (nghĩa là trước khi sự kiện shown.bs.tooltiphoặc hidden.bs.tooltipsự kiện xảy ra). Đây được coi là cách kích hoạt "thủ công" của chú giải công cụ.

$('#element').tooltip('toggle')

.tooltip('dispose')

Ẩn và hủy chú giải công cụ của phần tử. Chú giải công cụ sử dụng ủy quyền (được tạo bằng cách sử dụng tùy selectorchọn ) không thể bị hủy riêng lẻ trên các phần tử kích hoạt con.

$('#element').tooltip('dispose')

.tooltip('enable')

Cung cấp cho chú giải công cụ của một phần tử khả năng được hiển thị. Chú giải công cụ được bật theo mặc định.

$('#element').tooltip('enable')

.tooltip('disable')

Loại bỏ khả năng hiển thị chú giải công cụ của phần tử. Chú giải công cụ sẽ chỉ có thể được hiển thị nếu nó được bật lại.

$('#element').tooltip('disable')

.tooltip('toggleEnabled')

Chuyển đổi khả năng hiển thị hoặc ẩn chú giải công cụ của phần tử.

$('#element').tooltip('toggleEnabled')

.tooltip('update')

Cập nhật vị trí của chú giải công cụ của phần tử.

$('#element').tooltip('update')

Sự kiện

Loại sự kiện Sự mô tả
show.bs.tooltip Sự kiện này kích hoạt ngay lập tức khi showphương thức thể hiện được gọi.
show.bs.tooltip Sự kiện này được kích hoạt khi chú giải công cụ đã được hiển thị cho người dùng (sẽ đợi quá trình chuyển đổi CSS hoàn tất).
hide.bs.tooltip Sự kiện này được kích hoạt ngay lập tức khi hidephương thức thể hiện đã được gọi.
hidden.bs.tooltip Sự kiện này được kích hoạt khi chú giải công cụ hoàn tất bị ẩn khỏi người dùng (sẽ đợi quá trình chuyển đổi CSS hoàn tất).
insert.bs.tooltip Sự kiện này được kích hoạt sau show.bs.tooltipsự kiện khi mẫu chú giải công cụ đã được thêm vào DOM. 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something…
})