# 配置与主题样式

URL: https://caijiao.org/driver-js/03-advanced/01-configuration
Source: docs/driver-js/03-advanced/01-configuration.md
Description: 讲解 Driver.js 常用配置项、遮罩效果、弹层类名、CSS 覆盖和团队设计系统中的主题适配方法。

Driver.js 的默认样式可以直接使用，但在真实项目中通常需要与产品设计系统保持一致。你可以通过实例配置和 CSS 覆盖完成定制。

## 常用全局配置

```js
const driverObj = driver({
  animate: true,
  showProgress: true,
  allowClose: true,
  smoothScroll: true,
  overlayColor: "#000",
  overlayOpacity: 0.55,
  stagePadding: 8,
  popoverClass: "app-driver-popover",
  nextBtnText: "下一步",
  prevBtnText: "上一步",
  doneBtnText: "完成",
});
```

| 配置 | 作用 |
| --- | --- |
| `animate` | 是否启用过渡动画 |
| `showProgress` | 是否显示步骤进度 |
| `allowClose` | 是否允许用户关闭导览 |
| `smoothScroll` | 切换步骤时是否平滑滚动 |
| `overlayColor` | 遮罩颜色 |
| `overlayOpacity` | 遮罩透明度 |
| `stagePadding` | 高亮区域和目标元素之间的内边距 |
| `popoverClass` | 给弹层添加自定义类名 |

不同版本可用配置会略有差异，遇到不确定项时以官方 API 文档为准。

## 按步骤覆盖配置

全局配置适用于整个实例。某些步骤如果需要特殊位置或文案，可以在 step 中覆盖：

```js
const driverObj = driver({
  showProgress: true,
  steps: [
    {
      element: "#danger-zone",
      popover: {
        title: "危险区域",
        description: "这里的操作会影响整个团队，请确认后再继续。",
        side: "top",
        align: "start",
        popoverClass: "app-driver-popover app-driver-popover-danger",
      },
    },
  ],
});
```

## 定制弹层样式

通过 `popoverClass` 添加类名后，可以在项目 CSS 中覆盖：

```css
.app-driver-popover {
  border-radius: 8px;
  color: #172033;
  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
}

.app-driver-popover .driver-popover-title {
  font-size: 16px;
  font-weight: 700;
}

.app-driver-popover .driver-popover-description {
  line-height: 1.7;
}

.app-driver-popover .driver-popover-next-btn {
  background: #2563eb;
  border-color: #2563eb;
  color: #fff;
}
```

覆盖样式时尽量只影响你的自定义类名下面的元素，避免污染其他页面或第三方组件。

## 代码演示

下面的演示使用 `popoverClass` 定制深色弹层，并同时调整遮罩、圆角和中文按钮文案。

[在线代码演示](/driver-js/demos/3-theme.html)

## 遮罩与高亮区域

遮罩不宜过深，否则用户看不清页面上下文；也不宜过浅，否则焦点不够明显。

```js
const driverObj = driver({
  overlayColor: "#0f172a",
  overlayOpacity: 0.5,
  stagePadding: 10,
  stageRadius: 8,
});
```

后台类产品通常使用较克制的遮罩和圆角，让提示显得像系统的一部分。

## 暗色主题

如果应用有暗色模式，可以根据根节点类名调整弹层：

```css
.dark .app-driver-popover {
  background: #111827;
  border: 1px solid #374151;
  color: #f9fafb;
}

.dark .app-driver-popover .driver-popover-description {
  color: #d1d5db;
}
```

如果暗色主题由 CSS 变量驱动，可以让弹层直接复用变量：

```css
.app-driver-popover {
  background: var(--panel-bg);
  border-color: var(--border-color);
  color: var(--text-color);
}
```

## 配置建议

- 后台系统优先保持弹层简洁，不要过度品牌化。
- 引导按钮要和主按钮视觉一致，但不能比页面主操作更抢眼。
- 遮罩和高亮区域要在浅色、暗色、移动端都测试。
- 危险操作步骤可以使用更明确的标题和说明，但不要用夸张样式制造焦虑。