@xdy-npm/react-particle-backgrounds 1.0.2 → 1.1.0

package/README.md

@@ -2,6 +2,18 @@
 
 一个基于 [tsparticles](https://particles.js.org/) 和 [Three.js](https://threejs.org/) 的 React 粒子背景组件库，提供 **7 种精美粒子背景主题**。
 
+开发与发布相关说明（Vite 库模式搭建、npm 发布、面试要点）见仓库内 [docs 目录](./docs/README.md)（该目录仅随 Git 维护，**不会**随 `npm install` 的包体发布）。
+
+## 本地调试 Demo
+
+在仓库根目录执行：
+
+```bash
+pnpm demo:dev
+```
+
+会安装 `examples/demo` 依赖并启动 Vite（默认 `http://localhost:5173`）。Demo 通过别名直接引用根目录 `src/index.ts`，改库源码后保存即可热更新。说明见 [examples/demo/README.md](./examples/demo/README.md)。
+
 ## 主题一览
 
 | 主题 | ID | 描述 |

package/dist/index.d.ts

@@ -1,131 +1,142 @@
-import React from 'react';
-import { ISourceOptions, Container } from '@tsparticles/engine';
-
-interface ParticleTheme {
-    id: string;
-    name: string;
-    icon: string;
-    description: string;
-    /** 是否使用 Three.js 而非 tsparticles */
-    isThreeJS?: boolean;
-    /** 根据深色模式状态返回 tsparticles 配置 */
-    options: (isDark: boolean) => ISourceOptions;
-    /** 纯色背景色 */
-    backgroundColor?: string;
-    /** CSS 渐变背景 */
-    backgroundGradient?: string;
-}
-type ThemeId = 'starline' | 'snow' | 'bubble' | 'stars' | 'firefly' | 'geometry' | 'wave' | 'none';
-
-interface ParticlesBackgroundProps {
-    /**
-     * 要显示的主题 ID。如果在 `<ParticleProvider>` 内使用，
-     * 此属性可选，会自动使用 Provider 中的主题。
-     */
-    theme?: ThemeId | string;
-    /** 深色模式开关 — 影响支持的主题的粒子颜色 */
-    isDark?: boolean;
-    /** 粒子加载完成的回调 */
-    onLoaded?: (container?: Container) => void;
-    /** 自定义 CSS 类名 */
-    className?: string;
-    /** 自定义行内样式 */
-    style?: React.CSSProperties;
-}
-/**
- * 渲染全屏粒子背景。
- *
- * 可以通过 props 独立使用：
- * ```tsx
- * <ParticlesBackground theme="starline" isDark />
- * ```
- *
- * 也可以在 `<ParticleProvider>` 内使用以共享状态：
- * ```tsx
- * <ParticleProvider defaultTheme="snow">
- *   <ParticlesBackground />
- * </ParticleProvider>
- * ```
- */
-declare const ParticlesBackground: React.FC<ParticlesBackgroundProps>;
-
-interface ThemeSelectorProps {
-    /** 在屏幕上的位置 */
-    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-    /** 激活状态的强调色 */
-    accentColor?: string;
-}
-/**
- * 浮动主题选择器按钮 + 抽屉面板。
- * 必须在 `<ParticleProvider>` 内使用。
- *
- * ```tsx
- * <ParticleProvider>
- *   <ParticlesBackground />
- *   <ThemeSelector />
- * </ParticleProvider>
- * ```
- */
-declare const ThemeSelector: React.FC<ThemeSelectorProps>;
-
-interface ParticleWaveProps {
-    /** 波浪背后的 CSS 渐变或纯色背景 */
-    background?: string;
-    className?: string;
-    style?: React.CSSProperties;
-}
-/**
- * 使用 Three.js 渲染的 3D 粒子海洋波浪。
- * Three.js 以动态方式加载 — 如果未安装，此组件不会渲染任何内容。
- */
-declare const ParticleWave: React.FC<ParticleWaveProps>;
-
-interface ParticleContextValue {
-    themeId: string;
-    isDark: boolean;
-    setTheme: (id: string) => void;
-    setDark: (dark: boolean) => void;
-}
-interface ParticleProviderProps {
-    /** 初始/默认主题 ID */
-    defaultTheme?: ThemeId | string;
-    /** 是否使用深色模式粒子颜色 */
-    isDark?: boolean;
-    /** 是否将主题选择持久化到 localStorage */
-    persist?: boolean;
-    children: React.ReactNode;
-}
-/**
- * 为子组件提供粒子主题状态。
- * 用此 Provider 包裹你的应用（或子树），即可无需显式传参地使用
- * `<ParticlesBackground />` 和 `<ThemeSelector />`。
- */
-declare const ParticleProvider: React.FC<ParticleProviderProps>;
-/** 访问当前粒子主题上下文。必须在 `<ParticleProvider>` 内使用。 */
-declare const useParticleTheme: () => ParticleContextValue;
-
-declare const baseConfig: Partial<ISourceOptions>;
-/** 支持多色粒子的主题所使用的默认强调色 */
-declare const DEFAULT_COLORS: string[];
-
-declare const starlineTheme: ParticleTheme;
-
-declare const snowTheme: ParticleTheme;
-
-declare const bubbleTheme: ParticleTheme;
-
-declare const starsTheme: ParticleTheme;
-
-declare const fireflyTheme: ParticleTheme;
-
-declare const geometryTheme: ParticleTheme;
-
-declare const waveTheme: ParticleTheme;
-
-/** 所有内置粒子主题（不包含 "none"） */
-declare const particleThemes: ParticleTheme[];
-/** 根据 ID 获取主题。找不到时回退到 starline。 */
-declare const getThemeById: (id: string) => ParticleTheme;
-declare const DEFAULT_THEME_ID = "starline";
-
-export { DEFAULT_COLORS, DEFAULT_THEME_ID, ParticleProvider, type ParticleProviderProps, type ParticleTheme, ParticleWave, ParticlesBackground, type ParticlesBackgroundProps, type ThemeId, ThemeSelector, type ThemeSelectorProps, baseConfig, bubbleTheme, fireflyTheme, geometryTheme, getThemeById, particleThemes, snowTheme, starlineTheme, starsTheme, useParticleTheme, waveTheme };
+import { Container } from '@tsparticles/engine';
+import { default as default_2 } from 'react';
+import { ISourceOptions } from '@tsparticles/engine';
+
+export declare const baseConfig: Partial<ISourceOptions>;
+
+export declare const bubbleTheme: ParticleTheme;
+
+/** 支持多色粒子的主题所使用的默认强调色 */
+export declare const DEFAULT_COLORS: string[];
+
+export declare const DEFAULT_THEME_ID = "starline";
+
+export declare const fireflyTheme: ParticleTheme;
+
+export declare const geometryTheme: ParticleTheme;
+
+/** 根据 ID 获取主题。找不到时回退到 starline。 */
+export declare const getThemeById: (id: string) => ParticleTheme;
+
+declare interface ParticleContextValue {
+    themeId: string;
+    isDark: boolean;
+    setTheme: (id: string) => void;
+    setDark: (dark: boolean) => void;
+}
+
+/**
+ * 为子组件提供粒子主题状态。
+ * 用此 Provider 包裹你的应用（或子树），即可无需显式传参地使用
+ * `<ParticlesBackground />` 和 `<ThemeSelector />`。
+ */
+export declare const ParticleProvider: default_2.FC<ParticleProviderProps>;
+
+export declare interface ParticleProviderProps {
+    /** 初始/默认主题 ID */
+    defaultTheme?: ThemeId | string;
+    /** 是否使用深色模式粒子颜色 */
+    isDark?: boolean;
+    /** 是否将主题选择持久化到 localStorage */
+    persist?: boolean;
+    children: default_2.ReactNode;
+}
+
+/**
+ * 渲染全屏粒子背景。
+ *
+ * 可以通过 props 独立使用：
+ * ```tsx
+ * <ParticlesBackground theme="starline" isDark />
+ * ```
+ *
+ * 也可以在 `<ParticleProvider>` 内使用以共享状态：
+ * ```tsx
+ * <ParticleProvider defaultTheme="snow">
+ *   <ParticlesBackground />
+ * </ParticleProvider>
+ * ```
+ */
+export declare const ParticlesBackground: default_2.FC<ParticlesBackgroundProps>;
+
+export declare interface ParticlesBackgroundProps {
+    /**
+     * 要显示的主题 ID。如果在 `<ParticleProvider>` 内使用，
+     * 此属性可选，会自动使用 Provider 中的主题。
+     */
+    theme?: ThemeId | string;
+    /** 深色模式开关 — 影响支持的主题的粒子颜色 */
+    isDark?: boolean;
+    /** 粒子加载完成的回调 */
+    onLoaded?: (container?: Container) => void;
+    /** 自定义 CSS 类名 */
+    className?: string;
+    /** 自定义行内样式 */
+    style?: default_2.CSSProperties;
+}
+
+export declare interface ParticleTheme {
+    id: string;
+    name: string;
+    icon: string;
+    description: string;
+    /** 是否使用 Three.js 而非 tsparticles */
+    isThreeJS?: boolean;
+    /** 根据深色模式状态返回 tsparticles 配置 */
+    options: (isDark: boolean) => ISourceOptions;
+    /** 纯色背景色 */
+    backgroundColor?: string;
+    /** CSS 渐变背景 */
+    backgroundGradient?: string;
+}
+
+/** 所有内置粒子主题（不包含 "none"） */
+export declare const particleThemes: ParticleTheme[];
+
+/**
+ * 使用 Canvas 2D 渲染的粒子海洋波浪效果。
+ * 轻量级实现，无需 Three.js 依赖。
+ */
+export declare const ParticleWave: default_2.FC<ParticleWaveProps>;
+
+declare interface ParticleWaveProps {
+    /** 波浪背后的 CSS 渐变或纯色背景 */
+    background?: string;
+    className?: string;
+    style?: default_2.CSSProperties;
+}
+
+export declare const snowTheme: ParticleTheme;
+
+export declare const starlineTheme: ParticleTheme;
+
+export declare const starsTheme: ParticleTheme;
+
+export declare type ThemeId = 'starline' | 'snow' | 'bubble' | 'stars' | 'firefly' | 'geometry' | 'wave' | 'none';
+
+/**
+ * 浮动主题选择器按钮 + 抽屉面板。
+ * 必须在 `<ParticleProvider>` 内使用。
+ *
+ * ```tsx
+ * <ParticleProvider>
+ *   <ParticlesBackground />
+ *   <ThemeSelector />
+ * </ParticleProvider>
+ * ```
+ */
+export declare const ThemeSelector: default_2.FC<ThemeSelectorProps>;
+
+export declare interface ThemeSelectorProps {
+    /** 在屏幕上的位置 */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** 激活状态的强调色 */
+    accentColor?: string;
+}
+
+/** 访问当前粒子主题上下文。必须在 `<ParticleProvider>` 内使用。 */
+export declare const useParticleTheme: () => ParticleContextValue;
+
+export declare const waveTheme: ParticleTheme;
+
+export { }