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

package/README.md

@@ -1,37 +1,37 @@
 # react-particle-backgrounds
 
-A React component library that provides **7 beautiful particle background themes** powered by [tsparticles](https://particles.js.org/) and [Three.js](https://threejs.org/).
+一个基于 [tsparticles](https://particles.js.org/) 和 [Three.js](https://threejs.org/) 的 React 粒子背景组件库，提供 **7 种精美粒子背景主题**。
 
-## Themes
+## 主题一览
 
-| Theme | ID | Description |
-|-------|----|-------------|
-| ✨ Star Links | `starline` | Classic particle linking effect |
-| ❄️ Snowfall | `snow` | Romantic falling snowflakes |
-| 🫧 Bubbles | `bubble` | Dreamy rising bubbles |
-| ⭐ Twinkling Stars | `stars` | Sparkling starry sky |
-| 🪲 Fireflies | `firefly` | Warm glowing firefly effect |
-| 🔷 Geometry | `geometry` | Floating abstract geometric shapes |
-| 🌊 Particle Ocean | `wave` | 3D particle wave (Three.js) |
-| 🚫 None | `none` | Disable effects |
+| 主题 | ID | 描述 |
+|------|----|------|
+| ✨ 星链 | `starline` | 经典粒子连线效果 |
+| ❄️ 飘雪 | `snow` | 浪漫飘落雪花 |
+| 🫧 气泡 | `bubble` | 梦幻上升气泡 |
+| ⭐ 繁星 | `stars` | 闪烁星空效果 |
+| 🪲 萤火虫 | `firefly` | 温暖的萤火虫光效 |
+| 🔷 几何 | `geometry` | 漂浮的抽象几何图形 |
+| 🌊 粒子海洋 | `wave` | 3D 粒子波浪（Three.js） |
+| 🚫 无 | `none` | 关闭粒子效果 |
 
-## Installation
+## 安装
 
 ```bash
 npm install @xdy-npm/react-particle-backgrounds
-# or
+# 或
 pnpm add @xdy-npm/react-particle-backgrounds
 ```
 
-For the **Particle Ocean** (wave) theme, you also need Three.js:
+如需使用**粒子海洋**（wave）主题，还需要安装 Three.js：
 
 ```bash
 npm install three
 ```
 
-## Quick Start
+## 快速开始
 
-### Simple Usage (Props)
+### 基础用法（Props 方式）
 
 ```tsx
 import { ParticlesBackground } from '@xdy-npm/react-particle-backgrounds';
@@ -48,7 +48,7 @@ function App() {
 }
 ```
 
-### With Theme Selector (Context)
+### 配合主题选择器（Context 方式）
 
 ```tsx
 import {
@@ -70,7 +70,7 @@ function App() {
 }
 ```
 
-### Programmatic Theme Switching
+### 编程式切换主题
 
 ```tsx
 import {
@@ -84,7 +84,7 @@ function ThemeButton() {
 
   return (
     <button onClick={() => setTheme('firefly')}>
-      Current: {themeId} — Switch to Firefly
+      当前：{themeId} — 切换到萤火虫
     </button>
   );
 }
@@ -103,52 +103,52 @@ function App() {
 
 ### `<ParticlesBackground />`
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `theme` | `ThemeId \| string` | `'starline'` | Theme ID (overrides provider) |
-| `isDark` | `boolean` | `true` | Dark mode toggle |
-| `onLoaded` | `(container?) => void` | — | Callback when particles load |
-| `className` | `string` | — | CSS class |
-| `style` | `CSSProperties` | — | Inline styles |
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `theme` | `ThemeId \| string` | `'starline'` | 主题 ID（会覆盖 Provider 中的设置） |
+| `isDark` | `boolean` | `true` | 深色模式开关 |
+| `onLoaded` | `(container?) => void` | — | 粒子加载完成的回调 |
+| `className` | `string` | — | CSS 类名 |
+| `style` | `CSSProperties` | — | 行内样式 |
 
 ### `<ParticleProvider />`
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `defaultTheme` | `ThemeId \| string` | `'starline'` | Initial theme |
-| `isDark` | `boolean` | `true` | Dark mode state |
-| `persist` | `boolean` | `true` | Save to localStorage |
-| `children` | `ReactNode` | — | Child components |
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `defaultTheme` | `ThemeId \| string` | `'starline'` | 初始主题 |
+| `isDark` | `boolean` | `true` | 深色模式状态 |
+| `persist` | `boolean` | `true` | 是否持久化到 localStorage |
+| `children` | `ReactNode` | — | 子组件 |
 
 ### `<ThemeSelector />`
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Button position |
-| `accentColor` | `string` | `'#3b82f6'` | Active state color |
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | 按钮位置 |
+| `accentColor` | `string` | `'#3b82f6'` | 激活状态颜色 |
 
 ### `useParticleTheme()`
 
-Hook to access theme state (must be within `<ParticleProvider>`).
+用于访问主题状态的 Hook（必须在 `<ParticleProvider>` 内使用）。
 
 ```ts
 const { themeId, isDark, setTheme, setDark } = useParticleTheme();
 ```
 
-### Theme Objects
+### 主题对象
 
-Access individual theme configs:
+访问单个主题配置：
 
 ```ts
 import { starlineTheme, particleThemes, getThemeById } from '@xdy-npm/react-particle-backgrounds';
 
 const theme = getThemeById('snow');
-const options = theme.options(true); // get tsparticles config for dark mode
+const options = theme.options(true); // 获取深色模式下的 tsparticles 配置
 ```
 
-## Custom Themes
+## 自定义主题
 
-You can create your own theme and pass it directly:
+你可以创建自己的主题并直接传入：
 
 ```tsx
 import type { ParticleTheme } from '@xdy-npm/react-particle-backgrounds';
@@ -156,9 +156,9 @@ import { baseConfig } from '@xdy-npm/react-particle-backgrounds';
 
 const myTheme: ParticleTheme = {
   id: 'custom',
-  name: 'My Theme',
+  name: '我的主题',
   icon: '🎨',
-  description: 'A custom particle theme',
+  description: '一个自定义粒子主题',
   options: (isDark) => ({
     ...baseConfig,
     particles: {
@@ -172,6 +172,6 @@ const myTheme: ParticleTheme = {
 };
 ```
 
-## License
+## 许可证
 
 MIT

package/dist/index.d.mts

@@ -6,41 +6,41 @@ interface ParticleTheme {
     name: string;
     icon: string;
     description: string;
-    /** Whether this theme uses Three.js instead of tsparticles */
+    /** 是否使用 Three.js 而非 tsparticles */
     isThreeJS?: boolean;
-    /** Returns tsparticles config for the given dark mode state */
+    /** 根据深色模式状态返回 tsparticles 配置 */
     options: (isDark: boolean) => ISourceOptions;
-    /** Solid background color */
+    /** 纯色背景色 */
     backgroundColor?: string;
-    /** CSS gradient background */
+    /** CSS 渐变背景 */
     backgroundGradient?: string;
 }
 type ThemeId = 'starline' | 'snow' | 'bubble' | 'stars' | 'firefly' | 'geometry' | 'wave' | 'none';
 
 interface ParticlesBackgroundProps {
     /**
-     * Theme ID to display. If used inside a `<ParticleProvider>`,
-     * this is optional and the provider's theme will be used.
+     * 要显示的主题 ID。如果在 `<ParticleProvider>` 内使用，
+     * 此属性可选，会自动使用 Provider 中的主题。
      */
     theme?: ThemeId | string;
-    /** Dark mode toggle — affects particle colors for supported themes */
+    /** 深色模式开关 — 影响支持的主题的粒子颜色 */
     isDark?: boolean;
-    /** Callback when particles finish loading */
+    /** 粒子加载完成的回调 */
     onLoaded?: (container?: Container) => void;
-    /** Custom CSS class */
+    /** 自定义 CSS 类名 */
     className?: string;
-    /** Custom inline styles */
+    /** 自定义行内样式 */
     style?: React.CSSProperties;
 }
 /**
- * Renders a full-screen particle background.
+ * 渲染全屏粒子背景。
  *
- * Can be used standalone with props:
+ * 可以通过 props 独立使用：
  * ```tsx
  * <ParticlesBackground theme="starline" isDark />
  * ```
  *
- * Or inside a `<ParticleProvider>` for shared state:
+ * 也可以在 `<ParticleProvider>` 内使用以共享状态：
  * ```tsx
  * <ParticleProvider defaultTheme="snow">
  *   <ParticlesBackground />
@@ -50,14 +50,14 @@ interface ParticlesBackgroundProps {
 declare const ParticlesBackground: React.FC<ParticlesBackgroundProps>;
 
 interface ThemeSelectorProps {
-    /** Position on screen */
+    /** 在屏幕上的位置 */
     position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-    /** Accent color for active states */
+    /** 激活状态的强调色 */
     accentColor?: string;
 }
 /**
- * A floating theme selector button + drawer panel.
- * Must be used inside a `<ParticleProvider>`.
+ * 浮动主题选择器按钮 + 抽屉面板。
+ * 必须在 `<ParticleProvider>` 内使用。
  *
  * ```tsx
  * <ParticleProvider>
@@ -69,14 +69,14 @@ interface ThemeSelectorProps {
 declare const ThemeSelector: React.FC<ThemeSelectorProps>;
 
 interface ParticleWaveProps {
-    /** CSS gradient or solid background behind the wave */
+    /** 波浪背后的 CSS 渐变或纯色背景 */
     background?: string;
     className?: string;
     style?: React.CSSProperties;
 }
 /**
- * 3D particle ocean wave rendered with Three.js.
- * Three.js is loaded dynamically — if not installed, this component renders nothing.
+ * 使用 Three.js 渲染的 3D 粒子海洋波浪。
+ * Three.js 以动态方式加载 — 如果未安装，此组件不会渲染任何内容。
  */
 declare const ParticleWave: React.FC<ParticleWaveProps>;
 
@@ -87,25 +87,25 @@ interface ParticleContextValue {
     setDark: (dark: boolean) => void;
 }
 interface ParticleProviderProps {
-    /** Initial/default theme ID */
+    /** 初始/默认主题 ID */
     defaultTheme?: ThemeId | string;
-    /** Whether to use dark mode particle colors */
+    /** 是否使用深色模式粒子颜色 */
     isDark?: boolean;
-    /** Persist theme selection to localStorage */
+    /** 是否将主题选择持久化到 localStorage */
     persist?: boolean;
     children: React.ReactNode;
 }
 /**
- * Provides particle theme state to child components.
- * Wrap your app (or a subtree) with this provider to use
- * `<ParticlesBackground />` and `<ThemeSelector />` without explicit props.
+ * 为子组件提供粒子主题状态。
+ * 用此 Provider 包裹你的应用（或子树），即可无需显式传参地使用
+ * `<ParticlesBackground />` 和 `<ThemeSelector />`。
  */
 declare const ParticleProvider: React.FC<ParticleProviderProps>;
-/** Access the current particle theme context. Must be used within a `<ParticleProvider>`. */
+/** 访问当前粒子主题上下文。必须在 `<ParticleProvider>` 内使用。 */
 declare const useParticleTheme: () => ParticleContextValue;
 
 declare const baseConfig: Partial<ISourceOptions>;
-/** Default accent colors used by themes that support multi-color particles */
+/** 支持多色粒子的主题所使用的默认强调色 */
 declare const DEFAULT_COLORS: string[];
 
 declare const starlineTheme: ParticleTheme;
@@ -122,9 +122,9 @@ declare const geometryTheme: ParticleTheme;
 
 declare const waveTheme: ParticleTheme;
 
-/** All built-in particle themes (excludes "none") */
+/** 所有内置粒子主题（不包含 "none"） */
 declare const particleThemes: ParticleTheme[];
-/** Get a theme by its ID. Falls back to starline if not found. */
+/** 根据 ID 获取主题。找不到时回退到 starline。 */
 declare const getThemeById: (id: string) => ParticleTheme;
 declare const DEFAULT_THEME_ID = "starline";
 

package/dist/index.d.ts

@@ -6,41 +6,41 @@ interface ParticleTheme {
     name: string;
     icon: string;
     description: string;
-    /** Whether this theme uses Three.js instead of tsparticles */
+    /** 是否使用 Three.js 而非 tsparticles */
     isThreeJS?: boolean;
-    /** Returns tsparticles config for the given dark mode state */
+    /** 根据深色模式状态返回 tsparticles 配置 */
     options: (isDark: boolean) => ISourceOptions;
-    /** Solid background color */
+    /** 纯色背景色 */
     backgroundColor?: string;
-    /** CSS gradient background */
+    /** CSS 渐变背景 */
     backgroundGradient?: string;
 }
 type ThemeId = 'starline' | 'snow' | 'bubble' | 'stars' | 'firefly' | 'geometry' | 'wave' | 'none';
 
 interface ParticlesBackgroundProps {
     /**
-     * Theme ID to display. If used inside a `<ParticleProvider>`,
-     * this is optional and the provider's theme will be used.
+     * 要显示的主题 ID。如果在 `<ParticleProvider>` 内使用，
+     * 此属性可选，会自动使用 Provider 中的主题。
      */
     theme?: ThemeId | string;
-    /** Dark mode toggle — affects particle colors for supported themes */
+    /** 深色模式开关 — 影响支持的主题的粒子颜色 */
     isDark?: boolean;
-    /** Callback when particles finish loading */
+    /** 粒子加载完成的回调 */
     onLoaded?: (container?: Container) => void;
-    /** Custom CSS class */
+    /** 自定义 CSS 类名 */
     className?: string;
-    /** Custom inline styles */
+    /** 自定义行内样式 */
     style?: React.CSSProperties;
 }
 /**
- * Renders a full-screen particle background.
+ * 渲染全屏粒子背景。
  *
- * Can be used standalone with props:
+ * 可以通过 props 独立使用：
  * ```tsx
  * <ParticlesBackground theme="starline" isDark />
  * ```
  *
- * Or inside a `<ParticleProvider>` for shared state:
+ * 也可以在 `<ParticleProvider>` 内使用以共享状态：
  * ```tsx
  * <ParticleProvider defaultTheme="snow">
  *   <ParticlesBackground />
@@ -50,14 +50,14 @@ interface ParticlesBackgroundProps {
 declare const ParticlesBackground: React.FC<ParticlesBackgroundProps>;
 
 interface ThemeSelectorProps {
-    /** Position on screen */
+    /** 在屏幕上的位置 */
     position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-    /** Accent color for active states */
+    /** 激活状态的强调色 */
     accentColor?: string;
 }
 /**
- * A floating theme selector button + drawer panel.
- * Must be used inside a `<ParticleProvider>`.
+ * 浮动主题选择器按钮 + 抽屉面板。
+ * 必须在 `<ParticleProvider>` 内使用。
  *
  * ```tsx
  * <ParticleProvider>
@@ -69,14 +69,14 @@ interface ThemeSelectorProps {
 declare const ThemeSelector: React.FC<ThemeSelectorProps>;
 
 interface ParticleWaveProps {
-    /** CSS gradient or solid background behind the wave */
+    /** 波浪背后的 CSS 渐变或纯色背景 */
     background?: string;
     className?: string;
     style?: React.CSSProperties;
 }
 /**
- * 3D particle ocean wave rendered with Three.js.
- * Three.js is loaded dynamically — if not installed, this component renders nothing.
+ * 使用 Three.js 渲染的 3D 粒子海洋波浪。
+ * Three.js 以动态方式加载 — 如果未安装，此组件不会渲染任何内容。
  */
 declare const ParticleWave: React.FC<ParticleWaveProps>;
 
@@ -87,25 +87,25 @@ interface ParticleContextValue {
     setDark: (dark: boolean) => void;
 }
 interface ParticleProviderProps {
-    /** Initial/default theme ID */
+    /** 初始/默认主题 ID */
     defaultTheme?: ThemeId | string;
-    /** Whether to use dark mode particle colors */
+    /** 是否使用深色模式粒子颜色 */
     isDark?: boolean;
-    /** Persist theme selection to localStorage */
+    /** 是否将主题选择持久化到 localStorage */
     persist?: boolean;
     children: React.ReactNode;
 }
 /**
- * Provides particle theme state to child components.
- * Wrap your app (or a subtree) with this provider to use
- * `<ParticlesBackground />` and `<ThemeSelector />` without explicit props.
+ * 为子组件提供粒子主题状态。
+ * 用此 Provider 包裹你的应用（或子树），即可无需显式传参地使用
+ * `<ParticlesBackground />` 和 `<ThemeSelector />`。
  */
 declare const ParticleProvider: React.FC<ParticleProviderProps>;
-/** Access the current particle theme context. Must be used within a `<ParticleProvider>`. */
+/** 访问当前粒子主题上下文。必须在 `<ParticleProvider>` 内使用。 */
 declare const useParticleTheme: () => ParticleContextValue;
 
 declare const baseConfig: Partial<ISourceOptions>;
-/** Default accent colors used by themes that support multi-color particles */
+/** 支持多色粒子的主题所使用的默认强调色 */
 declare const DEFAULT_COLORS: string[];
 
 declare const starlineTheme: ParticleTheme;
@@ -122,9 +122,9 @@ declare const geometryTheme: ParticleTheme;
 
 declare const waveTheme: ParticleTheme;
 
-/** All built-in particle themes (excludes "none") */
+/** 所有内置粒子主题（不包含 "none"） */
 declare const particleThemes: ParticleTheme[];
-/** Get a theme by its ID. Falls back to starline if not found. */
+/** 根据 ID 获取主题。找不到时回退到 starline。 */
 declare const getThemeById: (id: string) => ParticleTheme;
 declare const DEFAULT_THEME_ID = "starline";