@slidejs/theme

SlideJS 主题系统 - 运行时 CSS 变量 Hook API

功能特性

- ✅ 统一的标准化主题配置接口
- ✅ 运行时动态设置 CSS 变量
- ✅ 支持全局和作用域自定义
- ✅ 类型安全的 API
- ✅ 所有 runner 自动映射标准变量
- ✅ 内置预设主题（Solarized Dark/Light）

设计理念

高级 API（官方支持）

使用标准变量名，不针对特定 runner：

``typescript
setTheme({
navigationColor: '#ff0000', // 标准变量名
paginationColor: '#00ff00', // 标准变量名
});
`

所有 runner 会自动将这些标准变量映射到自己的变量：

- --slidejs-navigation-color → --slidejs-swiper-navigation-color (Swiper)
- --slidejs-navigation-color → --slidejs-splide-arrow-color (Splide)

$3

如果需要直接设置 runner 特定变量，请自行使用 DOM API：

`typescript
// 不推荐：直接设置 runner 特定变量（风险自负）
document.documentElement.style.setProperty('--slidejs-swiper-navigation-color', '#ff0000');
`

注意：

- 低级 API 不在 SlideJS 官方支持范围内
- 可能导致兼容性问题
- 不推荐使用

安装

`bash
npm install @slidejs/theme
`

使用方式

$3

`typescript
import { setTheme, Preset } from '@slidejs/theme';

// 使用 Solarized Dark 主题（推荐：使用命名空间常量）
setTheme(Preset.SolarizedDark);

// 使用 Solarized Light 主题（推荐：使用命名空间常量）
setTheme(Preset.SolarizedLight);
`

$3

`typescript
import { setTheme } from '@slidejs/theme';

// 设置全局主题（使用标准变量名）
setTheme({
navigationColor: '#ff0000',
paginationColor: '#00ff00',
backgroundColor: '#ffffff',
textColor: '#000000',
});
`

$3

`typescript
import { useTheme } from '@slidejs/theme';

// 为特定容器设置预设主题（推荐：使用命名空间常量）
import { Preset } from '@slidejs/theme';

const theme = useTheme('#my-slides');
theme.set(Preset.SolarizedDark);

// 或使用自定义主题
theme.set({
navigationColor: '#ff0000',
paginationColor: '#00ff00',
});

// 或使用 HTMLElement
import { Preset } from '@slidejs/theme';
const container = document.getElementById('slides');
const theme2 = useTheme(container);
theme2.set(Preset.SolarizedLight);
`

$3

`typescript
import { setTheme } from '@slidejs/theme';

// 使用预设主题切换（推荐：使用命名空间常量）
import { Preset } from '@slidejs/theme';

function setDarkTheme() {
setTheme(Preset.SolarizedDark);
}

function setLightTheme() {
setTheme(Preset.SolarizedLight);
}

// 或使用自定义主题
function setCustomDarkTheme() {
setTheme({
backgroundColor: '#191919',
textColor: '#ffffff',
linkColor: '#42affa',
});
}
`

$3

`typescript
import { SlideThemeHook } from '@slidejs/theme';

// 创建自定义 Hook 实例
const theme = new SlideThemeHook('#my-slides');

// 设置主题
theme.set({
navigationColor: '#ff0000',
});

// 获取 CSS 变量值
const color = theme.get('--slidejs-navigation-color');

// 移除 CSS 变量
theme.remove('--slidejs-navigation-color');

// 清除所有标准主题变量
theme.clear();
`

预设主题

$3

`typescript
import { setTheme, Preset, solarizedDark } from '@slidejs/theme';

// 使用命名空间常量（推荐）
setTheme(Preset.SolarizedDark);

// 或直接使用主题对象
setTheme(solarizedDark);
`

$3

`typescript
import { setTheme, Preset, solarizedLight } from '@slidejs/theme';

// 使用命名空间常量（推荐）
setTheme(Preset.SolarizedLight);

// 或直接使用主题对象
setTheme(solarizedLight);
`

API 参考

$3

设置全局标准主题（官方支持）。

- 参数可以是标准主题配置对象
- 或预设主题命名空间常量（Preset.SolarizedDark 或 Preset.SolarizedLight）

$3

创建作用域主题 Hook。

$3

主题 Hook 类，提供以下方法：

- set(theme: StandardTheme | PresetThemeName): 设置标准主题或预设主题（官方支持）
- get(variableName: string): 获取 CSS 变量值
- remove(variableName: string): 移除 CSS 变量
- clear(): 清除所有标准主题变量

$3

`typescript
import {
Preset,
solarizedDark,
solarizedLight,
presets,
type PresetThemeName,
} from '@slidejs/theme';

// 使用命名空间常量（推荐）
setTheme(Preset.SolarizedDark);
setTheme(Preset.SolarizedLight);

// 或直接使用主题对象
setTheme(solarizedDark);
setTheme(solarizedLight);

// 获取所有预设主题
Object.keys(presets); // ['solarized-dark', 'solarized-light']
`

标准主题配置

`typescript
interface StandardTheme {
navigationColor?: string; // 导航按钮颜色
paginationColor?: string; // 分页器颜色
paginationActiveColor?: string; // 分页器激活颜色
scrollbarBg?: string; // 滚动条背景色
scrollbarDragBg?: string; // 滚动条拖拽颜色
arrowColor?: string; // 箭头颜色（用于 Splide）
progressBarColor?: string; // 进度条颜色
backgroundColor?: string; // 背景色
textColor?: string; // 文本颜色
linkColor?: string; // 链接颜色
headingColor?: string; // 标题颜色
codeBackground?: string; // 代码背景色
}
`

标准 CSS 变量

所有标准变量都以 --slidejs- 开头，不包含 runner 名称：

- --slidejs-navigation-color
- --slidejs-pagination-color
- --slidejs-pagination-active-color
- --slidejs-scrollbar-bg
- --slidejs-scrollbar-drag-bg
- --slidejs-arrow-color
- --slidejs-progress-bar-color
- --slidejs-background-color
- --slidejs-text-color
- --slidejs-link-color
- --slidejs-heading-color
- --slidejs-code-background

抽象主题属性

主题系统定义了从 Slide 抽象角度的通用主题属性：

`typescript
interface StandardTheme {
navigationColor?: string; // 导航控件颜色
paginationColor?: string; // 分页控件颜色
paginationActiveColor?: string; // 分页控件激活状态颜色
scrollbarBg?: string; // 滚动条背景色
scrollbarDragBg?: string; // 滚动条拖拽颜色
arrowColor?: string; // 导航箭头颜色
progressBarColor?: string; // 进度指示器颜色
backgroundColor?: string; // 幻灯片背景色
textColor?: string; // 文本颜色
linkColor?: string; // 链接颜色
headingColor?: string; // 标题颜色
codeBackground?: string; // 代码块背景色
}
`

重要：

- 这些是抽象主题属性，不涉及具体的 runner 实现
- 各个 runner 可以自由决定如何应用这些抽象属性
- 例如，navigationColor 可能被应用到按钮、箭头或其他导航控件，取决于 runner 的实现

预设主题详情

$3

基于 Solarized 配色方案的深色主题，适合在暗光环境下使用。

颜色方案：

- 背景：#002b36 (base03)
- 文本：#839496 (base0)
- 链接/导航：#268bd2 (blue)
- 激活状态：#2aa198 (cyan)

$3

基于 Solarized 配色方案的浅色主题，适合在明亮环境下使用。

颜色方案：

- 背景：#fdf6e3 (base3)
- 文本：#657b83 (base00)
- 链接/导航：#268bd2 (blue)
- 激活状态：#2aa198` (cyan)

参考：Solarized 官方网站

许可证

MIT