@slidejs/theme

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

功能特性

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

设计理念

高级 API（官方支持）

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

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

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

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

低级 API（自行使用，风险自负）

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

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

注意：

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

安装

npm install @slidejs/theme

使用方式

使用预设主题（推荐）

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

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

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

全局主题设置（自定义）

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

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

作用域主题设置

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);

动态切换主题

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',
  });
}

高级用法

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();

预设主题

Solarized Dark

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

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

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

Solarized Light

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

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

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

API 参考

setTheme(theme: StandardTheme | PresetThemeName)

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

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

useTheme(selector?: HTMLElement | string): SlideThemeHook)

创建作用域主题 Hook。

SlideThemeHook

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

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

预设主题导出

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']

标准主题配置

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 抽象角度的通用主题属性：

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 的实现

预设主题详情

Solarized Dark

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

颜色方案：

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

Solarized Light

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

颜色方案：

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

参考：Solarized 官方网站

许可证

MIT