Khắc phục sự cố
Thẻ hiển thị nhưng không có quả cầu
Trình duyệt có thể chưa đăng ký phần tử tùy chỉnh. Import điểm vào trình duyệt trong mã máy khách:
import "@neongate-ai/orbz/browser";Sau đó kiểm tra sổ đăng ký:
console.log(customElements.get("orb-z"));Trong React hoặc Next.js, import @neongate-ai/orbz/browser ở máy khách và hiển thị trực tiếp <orb-z>. Không import tệp nguồn của gói.
Máy chủ báo HTMLElement hoặc customElements chưa được định nghĩa
Dùng điểm vào gói được ghi trong tài liệu thay vì chạy mã chỉ dành cho trình duyệt trên máy chủ. Điểm vào gốc và browser bảo vệ đăng ký, nhưng mã của bạn cũng không được gọi biến DOM toàn cục khi SSR.
Chuyển truy vấn DOM sang khởi động máy khách, effect hoặc hook mount. Xem SSR và hydration.
TypeScript không nhận biết <orb-z> trong React
Thêm thẻ vào React.JSX.IntrinsicElements như hướng dẫn React và Next.js. Không giải quyết bằng thành phần bọc; phần tử runtime vẫn là <orb-z>.
Preset xung đột với màu tùy chỉnh
Chọn một chế độ: dùng preset hoặc xóa nó rồi đặt color-*. Nếu cùng có, preset ưu tiên và Orbz ghi lại thuộc tính xung đột.
palette không có tác dụng
palette không phải thuộc tính công khai. Dùng preset:
<orb-z preset="magenta"></orb-z>Preset tích hợp gồm Neongate (mặc định), periwinkle, magenta, peach, mocha và ivory. Đọc khóa hợp lệ từ ORBZ_PRESET_NAMES; xem tên preset.
Màu tùy chỉnh không xuất hiện
Xóa preset trước khi chuyển sang chế độ tùy chỉnh:
orb.removeAttribute("preset");
orb.setAttribute("color-primary", "#7C3AED");Cũng kiểm tra giá trị màu CSS hợp lệ và thuộc tính là một trong năm tên: color-primary, color-secondary, color-accent, color-highlight hoặc color-background.
paused="false" hoặc elevated="false" vẫn bật
Đây là thuộc tính boolean HTML: có mặt là đúng bất kể giá trị chuỗi. Hãy xóa thuộc tính:
orb.removeAttribute("paused");
orb.removeAttribute("elevated");Hoặc dùng thuộc tính JavaScript tương ứng:
orb.paused = false;
orb.elevated = false;Trong framework dùng mẫu, liên kết null hoặc undefined khi cần bỏ thuộc tính.
Hoạt ảnh không chạy
Kiểm tra theo thứ tự:
- Xóa
pausedhoặc đặt thuộc tính JavaScript thànhfalse. - Kiểm tra
reduced-motion:alwaysdùng hiển thị tĩnh. - Với
system, kiểm tra tùy chọn giảm chuyển động của hệ điều hành. - Xác nhận
speeddương. - Xác nhận phần tử đã được kết nối và đăng ký.
restart() dựng lại hoạt ảnh hiện tại nhưng không ghi đè chính sách tạm dừng hoặc giảm chuyển động.
Trạng thái, tốc độ hoặc preset sai
Giá trị runtime không hỗ trợ được chuẩn hóa về mặc định an toàn:
| Điều khiển | Mặc định |
|---|---|
state | idle |
speed | 1 |
preset | DEFAULT_ORBZ_PRESET (Neongate) |
reduced-motion | system |
size | 16rem khi giá trị rỗng hoặc thuộc tính số không hợp lệ |
Dùng kiểu TypeScript và hằng số được export để phát hiện giá trị không hỗ trợ trước khi chạy.
Vue cảnh báo không nhận diện được orb-z
Cấu hình trình biên dịch mẫu Vue coi thẻ là phần tử tùy chỉnh:
vue({
template: {
compilerOptions: {
isCustomElement: (tag) => tag === "orb-z",
},
},
})Cũng import @neongate-ai/orbz/browser từ điểm vào máy khách Vue.
Angular báo orb-z không phải phần tử đã biết
Thêm CUSTOM_ELEMENTS_SCHEMA vào thành phần standalone hoặc NgModule sở hữu mẫu:
schemas: [CUSTOM_ELEMENTS_SCHEMA]Sau đó import điểm vào trình duyệt trước khi khởi động ứng dụng.
Hai microfrontend tải phiên bản Orbz khác nhau
Sổ đăng ký Custom Elements chỉ cho một định nghĩa mỗi tên thẻ. Orbz chặn đăng ký trùng nên triển khai đầu tiên có hiệu lực. Phối hợp một phiên bản chính xác giữa các remote hoặc để shell đăng ký. Xem Orbz trong microfrontend.
Không thể kiểm tra hoặc định kiểu Shadow DOM
Shadow root được đóng theo thiết kế. Không hỗ trợ biến CSS công khai, part, lớp nội bộ hoặc tham chiếu lớp. Dùng thuộc tính được ghi trong tài liệu. Nếu không đáp ứng nhu cầu chung hợp lệ, mở đề xuất cụ thể tại GitHub Issues .
Vẫn chưa giải quyết được?
Khi mở issue, hãy cung cấp:
- phiên bản Orbz và điểm vào gói
- framework và phiên bản
- trình duyệt và hệ điều hành
- mã đánh dấu
<orb-z>nhỏ nhất tái hiện vấn đề - đầu ra build hoặc console liên quan