CustomElementRegistry: upgrade() method

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

Phương thức upgrade() của giao diện CustomElementRegistry nâng cấp tất cả các custom element có shadow trong một cây con Node, ngay cả trước khi chúng được kết nối với tài liệu chính.

Cú pháp

upgrade(root)

Tham số

root: Một thể hiện Node có các phần tử hậu duệ chứa shadow cần nâng cấp. Nếu không có phần tử hậu duệ nào có thể được nâng cấp, sẽ không có lỗi nào bị ném ra.

Khi một phần tử HTML được phân tích cú pháp hoặc tạo ra, nó có thể dùng một tên thẻ tương ứng với một custom element (ví dụ, <my-element>). Nếu lớp của custom element đó chưa được đăng ký với CustomElementRegistry phù hợp vào thời điểm phần tử được tạo, phần tử đó tồn tại như một HTMLElement chưa được định nghĩa. Nó trông và hoạt động như một phần tử không xác định bình thường - không có hành vi đặc biệt, callback vòng đời, hay phương thức prototype tùy chỉnh.

Nâng cấp là quá trình chuyển đổi ngược một phần tử như vậy thành một custom element đầy đủ khi định nghĩa của nó trở nên sẵn có. Khi một phần tử được nâng cấp:

Prototype của nó được hoán đổi sang lớp custom element đã được đăng ký bằng define().
connectedCallback() của nó và mọi lifecycle callback khác áp dụng được sẽ được gọi.
Nếu lớp định nghĩa observedAttributes, thì attributeChangedCallback() sẽ được gọi cho mỗi thuộc tính đã có giá trị.

Thông thường, các phần tử sẽ được nâng cấp tự động khi định nghĩa của chúng được đăng ký bằng define(), nhưng chỉ khi chúng đã được kết nối với tài liệu. Phương thức upgrade() hữu ích khi bạn cần nâng cấp các phần tử tồn tại trong một cây con DOM chưa được kết nối (ví dụ, phần tử được tạo qua Document.createElement() hoặc được phân tích vào một DocumentFragment) trước khi chúng được chèn vào tài liệu.

Ví dụ

Lấy từ đặc tả HTML:

const el = document.createElement("spider-man");

class SpiderMan extends HTMLElement {}
customElements.define("spider-man", SpiderMan);

console.assert(!(el instanceof SpiderMan)); // not yet upgraded

customElements.upgrade(el);
console.assert(el instanceof SpiderMan); // upgraded!