# 3D Viewer / 配置器 CSS 样式覆盖

[返回目录](../README.md)

SDK 组件使用 Light DOM，因此接入方可以在自己的样式表中直接覆盖本文列出的稳定选择器。本文只承诺列出的 CSS 变量、选择器和状态属性；未列出的内部 `.pv-*` 类名可能随版本调整。

主题色、字体、圆角等通用视觉参数应优先通过 [`siteConfig.theme`](../theme/README.md) 配置。CSS 覆盖适合调整布局、间距、文本策略和具体控件外观。

## 覆盖作用域

建议给组件增加业务类名，将覆盖限制在单个实例中：

```html
<product-3d-configurator
  class="brand-configurator"
  product-id="your-product-id"
></product-3d-configurator>
```

```css
.brand-configurator .pv-3d-configurator-panel {
  background: #f8fafc;
}

.brand-configurator product-configurator .pv-option {
  border-radius: 999px;
}
```

使用比 SDK 默认规则更明确的作用域选择器，通常不需要 `!important`。如果通过异步方式加载业务样式，请确保业务样式在 SDK 初始化后仍然存在。

## 公共布局变量

变量设置在 `product-3d-configurator` 或它的业务类名上。

| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `--pv-3d-configurator-min-height` | `640px` | 组合组件和状态页的最小高度 |
| `--pv-3d-configurator-panel-width` | `400px` | 宽度大于 900px 时右侧配置面板宽度 |
| `--pv-3d-configurator-panel-padding` | `24px` | 桌面配置面板内边距 |
| `--pv-3d-configurator-mobile-viewer-height` | `58vh`；手机为 `52svh` | 宽度不超过 900px 时 Viewer 高度 |
| `--pv-3d-configurator-mobile-panel-padding` | `20px` | 宽度不超过 900px 时配置面板内边距 |

```css
.brand-configurator {
  --pv-3d-configurator-min-height: 720px;
  --pv-3d-configurator-panel-width: 440px;
  --pv-3d-configurator-panel-padding: 28px;
}

@media (max-width: 900px) {
  .brand-configurator {
    --pv-3d-configurator-mobile-viewer-height: 50svh;
    --pv-3d-configurator-mobile-panel-padding: 16px;
  }
}
```

## 稳定布局选择器

| 选择器 | 对象 |
| --- | --- |
| `.pv-3d-configurator-layout` | Viewer 与配置面板的 Grid 容器 |
| `.pv-3d-configurator-viewer` | Viewer 区域 |
| `.pv-3d-configurator-panel` | 可滚动的配置面板 |
| `.pv-3d-configurator-state` | 加载、空数据和错误状态容器 |
| `product-configurator .pv-configurator` | 配置器根容器 |
| `.pv-config-header`、`.pv-config-title`、`.pv-config-reset` | 配置器标题栏、标题和重置按钮 |
| `.pv-config-row` | 一行配置项 |
| `.pv-config-label` | 行标题 |
| `.pv-config-row-content`、`.pv-config-options` | 选项容器 |

配置分区可以通过稳定的 `data-section` 属性定位：

```css
/* 对象选择区 */
.brand-configurator .pv-config-section[data-section="objects"] {
  padding-bottom: 12px;
}

/* 表面工艺区 */
.brand-configurator .pv-config-section[data-section="surface-process"] {
  border-top: 1px solid #e5e7eb;
  padding-top: 16px;
}
```

## 稳定选项与对象选择器

| 选择器 | 对象 |
| --- | --- |
| `.pv-option` | 通用对象 / 工艺选项按钮 |
| `.pv-option-text` | 通用选项文字 |
| `.pv-object-option` | 对象选项按钮 |
| `.pv-object-label` | 对象名称 |
| `.pv-object-visibility` | 显示 / 隐藏对象按钮 |
| `.pv-option[data-active="true"]` | 当前选中的选项 |
| `.pv-object-option[data-visible="false"]` | 当前隐藏的对象 |

默认情况下长文本使用单行省略。需要完整换行时，可以覆盖文字节点：

```css
.brand-configurator .pv-option-text,
.brand-configurator .pv-object-label {
  overflow: visible;
  overflow-wrap: anywhere;
  text-overflow: clip;
  white-space: normal;
}

.brand-configurator .pv-object-option {
  min-height: 40px;
  text-align: left;
}

.brand-configurator .pv-object-visibility {
  color: #0f766e;
  opacity: 1;
}
```

触屏设备中 `.pv-object-visibility` 默认始终可见；鼠标设备中默认在 hover、键盘聚焦或对象已经隐藏时显示。

## 稳定颜色与渐变选择器

| 选择器 | 对象 |
| --- | --- |
| `.pv-color-module` | 颜色模块 |
| `.pv-color-current` | 当前颜色按钮 |
| `.pv-color-popover` | 颜色设置弹层 |
| `.pv-color-sub-tabs`、`.pv-color-sub-tab` | Pantone / RGB / CMYK 标签栏和标签 |
| `.pv-pantone-grid`、`.pv-pantone-item`、`.pv-pantone-label` | Pantone 网格、色块项和名称 |
| `.pv-gradient-section` | 渐变颜色区域 |
| `.pv-gradient-craft-module` | 渐变工艺模块 |
| `.pv-gradient-craft-option` | 渐变工艺入口 |
| `.pv-gradient-craft-popover` | 渐变工艺弹层 |

```css
.brand-configurator .pv-color-popover,
.brand-configurator .pv-gradient-craft-popover {
  border-color: #cbd5e1;
  box-shadow: 0 18px 45px rgb(15 23 42 / 16%);
}

.brand-configurator .pv-pantone-label {
  font-size: 10px;
}
```

## 响应式覆盖示例

SDK 默认在 900px 及以下切换为 Viewer 在上、配置面板在下；767px 及以下将配置行改为上下排列。接入方可以保持该断点，只调整尺寸和细节：

```css
@media (min-width: 901px) and (max-width: 1199px) {
  .brand-configurator {
    --pv-3d-configurator-panel-width: 360px;
    --pv-3d-configurator-panel-padding: 18px;
  }
}

@media (max-width: 767px) {
  .brand-configurator .pv-option {
    min-height: 40px;
    padding-inline: 12px;
  }
}
```

完整可运行页面见 [配置器 CSS 自定义示例](configurator-css-customization.html)。

## 升级检查

升级 SDK 后，建议至少在 390px、768px、1024px 和 1440px 宽度下检查：页面是否出现横向滚动、Viewer 与配置面板是否按预期排列、长对象名和工艺名是否仍在按钮边界内，以及颜色 / 渐变弹层是否在视口内。