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 data-bs để 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 Popper thư viện của bên thứ 3 để đị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.js
có chứa Popper để các chú giải công cụ hoạt động! - 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
.disabled
hoặcdisabled
cá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.
prefers-reduced-motion
truy 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-bs-toggle
thuộc tính của chúng:
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
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ụ:
Văn bản giữ chỗ để chứng minh một số liên kết nội dòng với chú giải công cụ. Đây chỉ là chất làm đầy, không có kẻ giết người. Nội dung được đặt ở đây chỉ để bắt chước sự hiện diện của văn bản thực . Và tất cả những điều đó chỉ để cung cấp cho bạn ý tưởng về cách các chú giải công cụ sẽ trông như thế nào khi được sử dụng trong các tình huống thực tế. Vì vậy, hy vọng bây giờ bạn đã thấy cách các chú giải công cụ này trên các liên kết có thể hoạt động trong thực tế, khi bạn sử dụng chúng trên trang web hoặc dự án của riêng mình .
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. Chỉ đường được phản chiếu khi sử dụng Bootstrap trong RTL.
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip on top">
Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip on right">
Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip on bottom">
Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-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-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
Tooltip with HTML
</button>
Với SVG:
Sass
Biến
$tooltip-font-size: $font-size-sm;
$tooltip-max-width: 200px;
$tooltip-color: $white;
$tooltip-bg: $black;
$tooltip-border-radius: $border-radius;
$tooltip-opacity: .9;
$tooltip-padding-y: $spacer * .25;
$tooltip-padding-x: $spacer * .5;
$tooltip-margin: 0;
$tooltip-arrow-width: .8rem;
$tooltip-arrow-height: .4rem;
$tooltip-arrow-color: $tooltip-bg;
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:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Tràn auto
và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: auto
hoặc overflow: scroll
giố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 vấn đề này, hãy đặt boundary
tùy chọn (đối với công cụ sửa đổi lật sử dụng popperConfig
tùy chọn) thành bất kỳ HTMLElement nào để ghi đè giá trị mặc định 'clippingParents'
, chẳng hạn như document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // or document.querySelector('#boundary')
})
Đánh dấu
Đánh dấu bắt buộc cho chú giải công cụ chỉ là một data
thuộc tính và title
trê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 top
bở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 và hầu hết các công nghệ hỗ trợ hiện không thông báo chú giải công cụ trong trường hợp này. Ngoài ra, đừng chỉ dựa vào hover
là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-bs-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="tooltip-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ó disabled
thuộ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 tabindex="0"
.
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Disabled tooltip">
<button class="btn btn-primary" 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-bs-
, như trong data-bs-animation=""
. Đảm bảo thay đổi kiểu chữ hoa của tên tùy chọn từ camelCase thành kebab-case khi chuyển các tùy chọn qua thuộc tính dữ liệu. Ví dụ, thay vì sử dụng data-bs-customClass="beautifier"
, hãy sử dụng data-bs-custom-class="beautifier"
.
sanitize
,
các tùy chọn sanitizeFn
và và
allowList
không thể được cung cấp bằng các thuộc tính dữ liệu.
Tên | Loại hình | Mặc định | Sự mô tả |
---|---|---|---|
animation |
boolean | true |
Áp dụng chuyển đổi mờ dần CSS cho chú giải công cụ |
container |
chuỗi | phần tử | sai | false |
Thêm chú giải công cụ vào một phần tử cụ thể. |
delay |
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à: |
html |
boolean | false |
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ụ Sử dụng văn bản nếu bạn lo lắng về các cuộc tấn công XSS. |
placement |
chuỗi | hàm số | 'top' |
Cách định vị chú giải công cụ - tự động | đầu trang | đáy | trái | bên phải. 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 |
selector |
chuỗi | sai | false |
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.on hỗ trợ). Xem điều này và một ví dụ thông tin . |
template |
sợi dây | '<div class="tooltip" role="tooltip"><div class="tooltip-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ụ
Phần tử bao bọc ngoài cùng phải có |
title |
chuỗi | phần tử | hàm số | '' |
Giá trị tiêu đề mặc định nếu Nếu một hàm được cung cấp, nó sẽ được gọi với |
trigger |
sợi dây | 'hover focus' |
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.
|
fallbackPlacements |
mảng | ['top', 'right', 'bottom', 'left'] |
Xác định vị trí dự phòng bằng cách cung cấp danh sách các vị trí trong mảng (theo thứ tự ưu tiên). Để biết thêm thông tin, hãy tham khảo tài liệu về hành vi của Popper |
boundary |
chuỗi | yếu tố | 'clippingParents' |
Ranh giới ràng buộc tràn của chú giải công cụ (chỉ áp dụng cho công cụ sửa đổi ngăn chặn dòng chảy của Popper). Theo mặc định, nó 'clippingParents' và có thể chấp nhận tham chiếu HTMLElement (chỉ qua JavaScript). Để biết thêm thông tin, hãy tham khảo tài liệu DetOverflow của Popper . |
customClass |
chuỗi | hàm số | '' |
Thêm các lớp vào chú giải công cụ khi nó được hiển thị. Lưu ý rằng các lớp này sẽ được thêm vào ngoài bất kỳ lớp nào được chỉ định trong mẫu. Để thêm nhiều lớp, hãy phân tách chúng bằng dấu cách Bạn cũng có thể chuyển một hàm sẽ trả về một chuỗi đơn chứa các tên lớp bổ sung. |
sanitize |
boolean | true |
Bật hoặc tắt tính năng vệ sinh. Nếu được kích hoạt 'template' và 'title' các tùy chọn sẽ được khử trùng. Xem phần sanitizer trong tài liệu JavaScript của chúng tôi . |
allowList |
sự vật | Giá trị mặc định | Đối tượng chứa các thuộc tính và thẻ được phép |
sanitizeFn |
null | hàm số | null |
Tại đây bạn có thể cung cấp chức năng khử trùng của riêng mình. Điều này có thể hữu ích nếu bạn muốn sử dụng một thư viện chuyên dụng để thực hiện vệ sinh. |
offset |
mảng | chuỗi | hàm số | [0, 0] |
Phần bù của chú giải công cụ so với mục tiêu của nó. Bạn có thể chuyển một chuỗi trong thuộc tính dữ liệu với các giá trị được phân tách bằng dấu phẩy như: Khi một hàm được sử dụng để xác định độ lệch, nó được gọi với một đối tượng chứa vị trí popper, tham chiếu và popper đóng vai trò là đối số đầu tiên của nó. Nút DOM của phần tử kích hoạt được chuyển làm đối số thứ hai. Hàm phải trả về một mảng có hai số :. Để biết thêm thông tin, hãy tham khảo tài liệu bù đắp của Popper . |
popperConfig |
null | đối tượng | hàm số | null |
Để thay đổi cấu hình Popper mặc định của Bootstrap, hãy xem cấu hình của Popper . Khi một hàm được sử dụng để tạo cấu hình Popper, nó được gọi với một đối tượng có chứa cấu hình Popper mặc định của Bootstrap. Nó giúp bạn sử dụng và hợp nhất mặc định với cấu hình của riêng bạn. Hàm phải trả về một đối tượng cấu hình cho Popper. |
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.
Sử dụng chức năng vớipopperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
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 .
buổi bieu diễn
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.tooltip
sự 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ị.
tooltip.show()
ẩn giấu
Ẩ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.tooltip
sự 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ụ.
tooltip.hide()
chuyển đổi
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.tooltip
hoặc hidden.bs.tooltip
sự 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ụ.
tooltip.toggle()
vứt bỏ
Ẩn và hủy chú giải công cụ của phần tử (Xóa dữ liệu được lưu trữ trên phần tử DOM). Chú giải công cụ sử dụng ủy quyền (được tạo bằng cách sử dụng tùy selector
chọn ) không thể bị hủy riêng lẻ trên các phần tử kích hoạt con.
tooltip.dispose()
cho phép
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.
tooltip.enable()
vô hiệu hóa
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.
tooltip.disable()
toggleEnabled
Chuyển đổi khả năng hiển thị hoặc ẩn chú giải công cụ của phần tử.
tooltip.toggleEnabled()
cập nhật
Cập nhật vị trí của chú giải công cụ của phần tử.
tooltip.update()
getInstance
Phương thức tĩnh cho phép bạn lấy phiên bản chú giải công cụ được liên kết với phần tử DOM
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance
Phương thức tĩnh cho phép bạn lấy phiên bản chú giải công cụ được liên kết với phần tử DOM hoặc tạo một phiên bản mới trong trường hợp nó chưa được khởi tạo
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
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 show phương thức thể hiện được gọi. |
shown.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 hide phươ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). |
inserted.bs.tooltip |
Sự kiện này được kích hoạt sau show.bs.tooltip sự kiện khi mẫu chú giải công cụ đã được thêm vào DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()