@mar7th/firework 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,163 @@
+# SparkFireworks
+
+一个轻量的网页烟花模拟器和烟花效果库，支持可视化调参、内置预设、CDN 直接引入、npm 安装以及高级脚本自定义粒子。
+
+## 在线与源码
+
+- npm: <https://www.npmjs.com/package/@mar7th/firework>
+- Gitee: <https://gitee.com/march7th-online/firework-yoimiya>
+
+## 安装
+
+```bash
+npm install @mar7th/firework
+```
+
+## 使用
+
+### ESM
+
+```html
+<canvas id="fireworks" style="width:100vw;height:100vh;display:block"></canvas>
+
+<script type="module">
+  import SparkFireworks from "@mar7th/firework";
+
+  const fireworks = SparkFireworks.create("fireworks", {
+    particleCount: 220,
+    colorStart: "#ffd166",
+    colorEnd: "#ef476f",
+    enableTrails: true
+  });
+
+  fireworks.launchRandom();
+</script>
+```
+
+### CDN
+
+unpkg:
+
+```html
+<script type="module">
+  import SparkFireworks from "https://unpkg.com/@mar7th/firework@1.0.0/dist-lib/spark-fireworks.js";
+
+  const fireworks = SparkFireworks.create("fireworks", {
+    autoLaunch: true
+  });
+</script>
+```
+
+jsDelivr:
+
+```html
+<script type="module">
+  import SparkFireworks from "https://cdn.jsdelivr.net/npm/@mar7th/firework@1.0.0/dist-lib/spark-fireworks.js";
+
+  const fireworks = SparkFireworks.create("fireworks", {
+    autoLaunch: true
+  });
+</script>
+```
+
+UMD:
+
+```html
+<canvas id="fireworks" style="width:100vw;height:100vh;display:block"></canvas>
+<script src="https://cdn.jsdelivr.net/npm/@mar7th/firework@1.0.0/dist-lib/spark-fireworks.umd.cjs"></script>
+<script>
+  const fireworks = SparkFireworks.create("fireworks", {
+    autoLaunch: true,
+    autoLaunchIntervalSeconds: 1
+  });
+</script>
+```
+
+## 常用 API
+
+```js
+const fireworks = SparkFireworks.create(canvasOrId, configOrOptions);
+
+fireworks.launch(x, y);
+fireworks.launchRandom();
+fireworks.startAutoPlay(seconds);
+fireworks.stopAutoPlay();
+fireworks.setConfig({ particleCount: 300 });
+fireworks.destroy();
+```
+
+`create` 的第一个参数可以是 canvas 元素，也可以是 canvas 的 id。第二个参数可以直接传配置，也可以传完整 options：
+
+```js
+SparkFireworks.create("fireworks", {
+  config: {
+    explosionShape: "heart",
+    particleCount: 300
+  },
+  onFpsChange(fps) {
+    console.log("FPS", fps);
+  }
+});
+```
+
+更完整的 API 说明见 [docs/api-guide.md](docs/api-guide.md)。
+
+## 高级脚本
+
+高级模式允许你通过 `createParticles(canvasData)` 完全控制粒子的生成方式。高级模式下所有参数均以脚本设置为准，页面设置可能被覆盖不生效。
+
+```js
+SparkFireworks.create("fireworks", {
+  advancedMode: true,
+  createParticles(canvasData) {
+    return {
+      config: {
+        gravity: 0.08,
+        enableTrails: true
+      },
+      particles: [
+        {
+          x: canvasData.x,
+          y: canvasData.y,
+          vx: 2,
+          vy: -3,
+          size: 4,
+          life: 90,
+          startColor: "#ffd166",
+          endColor: "#ef476f"
+        }
+      ]
+    };
+  }
+});
+```
+
+## 本地开发
+
+```bash
+npm install
+npm run dev
+```
+
+构建页面和库文件：
+
+```bash
+npm run build
+```
+
+只构建库文件：
+
+```bash
+npm run build:lib
+```
+
+构建产物：
+
+```text
+dist-lib/spark-fireworks.js
+dist-lib/spark-fireworks.umd.cjs
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

package/advanced-guide.html

@@ -25,6 +25,7 @@
           <a href="/guide.html">使用指导</a>
           <a href="/advanced-guide.html">高级指导</a>
           <a href="/api-download.html">API 下载</a>
+          <a href="https://gitee.com/march7th-online/firework-yoimiya" target="_blank" rel="noreferrer">开源地址</a>
         </div>
       </nav>
 

package/api-download.html

@@ -25,6 +25,7 @@
           <a href="/guide.html">使用指导</a>
           <a href="/advanced-guide.html">高级指导</a>
           <a href="/api-download.html">API 下载</a>
+          <a href="https://gitee.com/march7th-online/firework-yoimiya" target="_blank" rel="noreferrer">开源地址</a>
         </div>
       </nav>
 

package/demo.html

@@ -23,6 +23,7 @@
         <div class="top-bar">
           <div class="action-group" aria-label="预设与配置">
             <a class="toolbar-link" href="/">首页</a>
+            <a class="toolbar-link" href="https://gitee.com/march7th-online/firework-yoimiya" target="_blank" rel="noreferrer">开源地址</a>
             <select id="presetSelect" aria-label="选择预设"></select>
             <button id="resetConfigButton" type="button">初始化设置</button>
             <button id="savePresetButton" type="button">保存</button>

package/guide.html

@@ -25,6 +25,7 @@
           <a href="/guide.html">使用指导</a>
           <a href="/advanced-guide.html">高级指导</a>
           <a href="/api-download.html">API 下载</a>
+          <a href="https://gitee.com/march7th-online/firework-yoimiya" target="_blank" rel="noreferrer">开源地址</a>
         </div>
       </nav>
 
@@ -43,6 +44,17 @@
         </ol>
       </section>
 
+      <section class="doc-section">
+        <h2>npm 包地址</h2>
+        <p>
+          SparkFireworks 已发布到 npm：
+          <a href="https://www.npmjs.com/package/@mar7th/firework" target="_blank" rel="noreferrer">https://www.npmjs.com/package/@mar7th/firework</a>
+        </p>
+        <pre><code>npm install @mar7th/firework</code></pre>
+        <p>源码仓库：<a href="https://gitee.com/march7th-online/firework-yoimiya" target="_blank" rel="noreferrer">Gitee 开源地址</a></p>
+        <p class="note">如果只想通过 CDN 直接引入，请查看 <a href="/api-download.html">API 下载</a> 页面中的 unpkg 和 jsDelivr 示例。</p>
+      </section>
+
       <section class="doc-section">
         <h2>顶部工具栏</h2>
         <ul>

package/index.html

@@ -25,6 +25,7 @@
           <a href="/guide.html">使用指导</a>
           <a href="/advanced-guide.html">高级指导</a>
           <a href="/api-download.html">API 下载</a>
+          <a href="https://gitee.com/march7th-online/firework-yoimiya" target="_blank" rel="noreferrer">开源地址</a>
         </div>
       </nav>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mar7th/firework",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "./dist-lib/spark-fireworks.umd.cjs",
   "module": "./dist-lib/spark-fireworks.js",
@@ -18,6 +18,7 @@
     "docs",
     "examples",
     "*.html",
+    "README.md",
     "favicon.jpg",
     "vite.config.js",
     "vite.lib.config.js"