故障排查

标签已渲染，但球体不显示

浏览器可能尚未注册自定义元素。在客户端代码中导入浏览器入口：


import "@neongate-ai/orbz/browser";

然后检查注册表：


console.log(customElements.get("orb-z"));

React 或 Next.js 中，在客户端导入 @neongate-ai/orbz/browser 并直接渲染 <orb-z>。不要导入包源码文件。

服务器提示 `HTMLElement` 或 `customElements` 未定义

使用文档中的包入口，不要在服务器执行仅限浏览器的应用代码。Orbz 根入口和浏览器入口保护了注册过程，但你自己的代码仍不得在服务端渲染时调用 DOM 全局对象。

将 DOM 查询移至客户端启动、effect 或框架挂载钩子中。参见 SSR 与水合。

TypeScript 在 React 中不识别 `<orb-z>`

按 React 与 Next.js 指南将标签加入 React.JSX.IntrinsicElements。不要通过创建包装组件解决，运行时元素仍是 <orb-z>。

预设与自定义颜色冲突

选择一种外观模式：使用 preset，或移除它并设置 color-*。两者同时存在时预设优先，Orbz 会记录冲突属性。

`palette` 无效

palette 不是公开属性。请使用 preset：


<orb-z preset="magenta"></orb-z>

内置外观包括 Neongate（默认）、periwinkle、magenta、peach、mocha 和 ivory。从 ORBZ_PRESET_NAMES 读取支持的键，参见预设命名。

自定义颜色未显示

进入自定义模式前移除 preset：


orb.removeAttribute("preset");
orb.setAttribute("color-primary", "#7C3AED");

还需确认值是有效 CSS 颜色，且属性属于五个支持名称之一：color-primary、color-secondary、color-accent、color-highlight、color-background。

`paused="false"` 或 `elevated="false"` 仍启用

它们是 HTML 布尔属性，存在即为真，与字符串值无关。请移除属性：


orb.removeAttribute("paused");
orb.removeAttribute("elevated");

或使用对应的 JavaScript 属性：


orb.paused = false;
orb.elevated = false;

在模板框架中，当属性不应存在时绑定 null 或 undefined。

动画未播放

依次检查以下控制项：

移除 paused 或将 JavaScript 属性设为 false。
检查 reduced-motion：always 使用静态呈现。
使用 system 时，检查操作系统的减少动态效果偏好。
确认 speed 为正数。
确认元素已连接且注册。

restart() 重建当前状态动画，但不会覆盖暂停或减少动态效果策略。

状态、速度或预设不正确

不支持的运行时值会归一化为安全默认值：

控制项	默认值
`state`	`idle`
`speed`	`1`
`preset`	`DEFAULT_ORBZ_PRESET`（Neongate）
`reduced-motion`	`system`
`size`	空值或无效数字属性时为 `16rem`

使用导出的 TypeScript 类型和常量，在运行前发现不支持的值。

Vue 警告无法解析 `orb-z`

配置 Vue 模板编译器，将标签视为自定义元素：


vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag === "orb-z",
    },
  },
})

同时在 Vue 客户端入口导入 @neongate-ai/orbz/browser。

Angular 提示 `orb-z` 是未知元素

将 CUSTOM_ELEMENTS_SCHEMA 添加到负责模板的独立组件或 NgModule：


schemas: [CUSTOM_ELEMENTS_SCHEMA]

然后在启动应用前导入浏览器入口。

两个微前端加载不同的 Orbz 版本

自定义元素注册表每个标签只允许一个定义。Orbz 防止重复注册，因此页面上最先注册的实现生效。应在远程模块之间统一精确版本，或由外壳负责注册。参见微前端中的 Orbz。

无法检查或设置 Shadow DOM 样式

Shadow 根有意封闭，不支持公共 CSS 变量、parts、内部类或图层引用。请使用严格的文档属性。若公开外观控件无法表达合理的通用场景，可在 GitHub Issues 提交聚焦的建议。

仍有问题？

提交问题时请包含：

Orbz 版本与包入口
框架及版本
浏览器和操作系统
可复现问题的最小 <orb-z> 标记
相关构建或控制台输出

提交 Orbz 问题 · 查看 npm 包