Làm cho các phần tử tuỳ chỉnh hoạt động với các sổ đăng ký có phạm vi

Jayson Chen

Patrick Brosset

Xuất bản: Ngày 9 tháng 3 năm 2026

Các phần tử tuỳ chỉnh cho phép nhà phát triển ứng dụng web tạo, chia sẻ và sử dụng lại các thành phần giao diện người dùng có hành vi riêng biệt, giúp việc phát triển trở nên dễ dàng hơn. Nhưng khi ứng dụng của bạn kết hợp nhiều nhóm phần tử tuỳ chỉnh, mọi thứ có thể trở nên lộn xộn và có thể xảy ra xung đột tên. Các sổ đăng ký phần tử tuỳ chỉnh có phạm vi giải quyết vấn đề này!

Nhóm Microsoft Edge đã nghiên cứu tính năng này và chúng tôi rất vui mừng thông báo rằng các sổ đăng ký phần tử tuỳ chỉnh có phạm vi hiện đã có sẵn theo mặc định từ Edge và Chrome 146, cũng như các trình duyệt khác dựa trên Chromium. Giờ đây, bạn có thể đóng gói các phần tử tuỳ chỉnh, giải quyết một vấn đề tồn tại từ lâu đối với các nhà phát triển thành phần và thư viện vi mô.

Các sổ đăng ký phần tử tuỳ chỉnh có phạm vi mở ra những mẫu quan trọng cho nhà phát triển web. Giờ đây, bạn có thể sử dụng nhiều thư viện phần tử tuỳ chỉnh do nhiều nhóm phát triển độc lập hoặc nhiều phiên bản của cùng một thư viện song song.

Scoped custom element registry là gì?

Hiện tại, mọi định nghĩa về phần tử tuỳ chỉnh trên một trang web đều nằm trong một sổ đăng ký dùng chung duy nhất tại window.customElements. Điều này có nghĩa là nếu cả hai thư viện khác nhau đều cố gắng xác định một phần tử tuỳ chỉnh có cùng tên thẻ, chẳng hạn như <my-button>, thì sẽ xảy ra lỗi và trang sẽ bị hỏng. Đây là một vấn đề nghiêm trọng trong thực tế. Các ứng dụng lớn có giao diện người dùng được tạo thành từ nhiều nhóm, hệ thống thiết kế hoặc vi giao diện người dùng có thể dễ dàng gặp phải tình trạng xung đột tên. Các sổ đăng ký phần tử tuỳ chỉnh có phạm vi giải quyết vấn đề này bằng cách cho phép bạn tạo các sổ đăng ký độc lập. Mỗi sổ đăng ký duy trì một tập hợp các định nghĩa về phần tử tuỳ chỉnh riêng, hoàn toàn tách biệt với sổ đăng ký chung và với nhau.

Tạo sổ đăng ký mới

Thay vì xác định mọi phần tử tuỳ chỉnh trong sổ đăng ký window.customElements chung:

1. Tạo một sổ đăng ký mới bằng cách gọi new CustomElementRegistry().
2. Cung cấp cho sổ đăng ký mới của bạn một phạm vi cụ thể (xem phần Phạm vi của sổ đăng ký).
3. Xác định các phần tử sẽ được đưa vào sổ đăng ký mới.

Sau đó, khi một phần tử tuỳ chỉnh được dùng, trình duyệt sẽ tra cứu định nghĩa của phần tử đó trong sổ đăng ký được liên kết (không nhất thiết phải là sổ đăng ký chung). Điều này có nghĩa là các phần khác nhau trên trang của bạn có thể sử dụng hoàn toàn các tập hợp định nghĩa phần tử tuỳ chỉnh khác nhau.

Phạm vi sổ đăng ký

Bạn có thể đặt phạm vi cho một sổ đăng ký phần tử tuỳ chỉnh thành một tài liệu, một gốc bóng hoặc một phần tử riêng lẻ.

Phạm vi cho gốc bóng

Để phạm vi một sổ đăng ký mới cho một gốc bóng, hãy sử dụng lựa chọn customElementRegistry khi gọi phương thức attachShadow(). Giờ đây, tất cả các phần tử tuỳ chỉnh nằm trong gốc bóng đó sẽ sử dụng định nghĩa trong sổ đăng ký có phạm vi tương ứng:

// Create your custom registry.
const registry = new CustomElementRegistry();
// Define a custom element in the new registry.
registry.define('my-card', class extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from scoped registry!';
  }
});

// Create shadow root, providing it with your new custom element registry.
const host = document.querySelector('#host');
const shadow = host.attachShadow({
  mode: 'open',
  customElementRegistry: registry,
});

shadow.innerHTML = '<my-card></my-card>';

DOM tối khai báo

Sử dụng thuộc tính shadowrootcustomelementregistry trên phần tử <template> để cho trình duyệt biết rằng gốc bóng kết quả đang sử dụng một sổ đăng ký có phạm vi thay vì sổ đăng ký chung:

<my-host>
  <template shadowrootmode="open" shadowrootcustomelementregistry>
    <my-widget></my-widget>
  </template>
</my-host>

  const registry = new CustomElementRegistry();
  registry.define('my-widget', class extends HTMLElement {
    connectedCallback() { this.textContent = 'Scoped!'; }
  });

  const shadow = document.querySelector('my-host').shadowRoot;
  registry.initialize(shadow);

Như trong ví dụ, thuộc tính này dành riêng không gian cho sổ đăng ký phần tử tuỳ chỉnh và người dùng cần xác định cũng như khởi tạo sổ đăng ký để Scoping gốc bóng thành một tài liệu bị ngắt kết nối

Bạn cũng có thể giới hạn phạm vi của sổ đăng ký trong một tài liệu, chẳng hạn như tài liệu do document.implementation.createHTMLDocument() tạo. Điều này cho phép bạn sao chép các phần tử <template> và thực hiện thao tác với tài liệu ngoài màn hình, mỗi phần tử có một bộ định nghĩa thành phần riêng biệt. Để thực hiện việc này, hãy sử dụng phương thức CustomElementRegistry.initialize():

// Create a new registry.
const registry = new CustomElementRegistry();
registry.define('app-widget', AppWidget);

// Create a document, and use registry.initialize() to scope the registry to the document.
const doc = document.implementation.createHTMLDocument('');
registry.initialize(doc);

doc.body.innerHTML = '<app-widget></app-widget>';

Phạm vi cho một phần tử riêng lẻ

Bạn cũng có thể liên kết trực tiếp một sổ đăng ký với một phần tử và cây con của phần tử đó bằng cách truyền lựa chọn customElementRegistry đến document.createElement(). Phần tử và các thành phần con của phần tử này sẽ phân giải dựa trên sổ đăng ký đó, bất kể phần nào của DOM mà chúng được chèn vào sau này:

// Create a registry and define a custom element in it.
const registry = new CustomElementRegistry();
registry.define('fancy-label', FancyLabel);

// Create a new DOM element and scope the new registry to it.
const el = document.createElement('fancy-input', {
  customElementRegistry: registry,
});

// Use a custom element in the new DOM element.
el.innerHTML = '<fancy-label>Name</fancy-label>';

Tìm hiểu thêm

Để tìm hiểu thêm, hãy xem bản minh hoạ Edge và mã nguồn của bản minh hoạ này, đồng thời đọc bài viết tham khảo CustomElementRegistry của MDN

Giờ đây, các sổ đăng ký phần tử tuỳ chỉnh có phạm vi được bật theo mặc định trong cả Microsoft Edge và Chrome, cũng như trong các trình duyệt khác dựa trên Chromium, nhờ sự hợp tác của chúng tôi thông qua dự án Chromium.

Bạn không cần bật bất kỳ chế độ cài đặt nào hoặc đăng ký bản dùng thử theo nguyên gốc. Bạn có thể bắt đầu sử dụng tính năng này ngay hôm nay trong các trình duyệt dựa trên Chromium.

Nếu bạn cần triển khai tính năng này trong các trình duyệt khác, hãy bày tỏ sự ủng hộ đối với vấn đề Đăng ký phần tử tuỳ chỉnh có phạm vi và để lại bình luận về các trường hợp sử dụng cũng như giải pháp thay thế của bạn.

Nếu bạn phát hiện thấy lỗi khi triển khai tính năng này trong một trình duyệt dựa trên Chromium, hãy mở một vấn đề để chúng tôi điều tra tại crbug.com/new.

Chúng tôi hy vọng rằng các sổ đăng ký phần tử tuỳ chỉnh có phạm vi sẽ giúp bạn sử dụng các thành phần web dễ dàng hơn.