jyj-components 1.0.0

package/QUICKSTART.md

@@ -0,0 +1,300 @@
+# 快速开始
+
+## 5 分钟上手指南
+
+### 1. 构建组件
+
+```bash
+cd D:\myCode\miniProgram\jyj-components
+npm install
+npm run build
+```
+
+构建完成后，会在项目根目录生成 `miniprogram_dist` 目录。
+
+### 2. 在小程序中引入
+
+#### 方式 A：本地引入（推荐用于开发测试）
+
+将 `miniprogram_dist` 目录复制到你的小程序项目中，例如：
+
+```
+your-miniprogram/
+├── components/
+│   └── jyj-components/  # 复制 miniprogram_dist 到这里并重命名
+├── pages/
+└── app.json
+```
+
+在 `app.json` 中全局注册：
+
+```json
+{
+  "usingComponents": {
+    "ad-banner": "/components/jyj-components/ad-banner/index",
+    "ad-interstitial": "/components/jyj-components/ad-interstitial/index",
+    "ad-rewarded-video": "/components/jyj-components/ad-rewarded-video/index",
+    "ad-splash": "/components/jyj-components/ad-splash/index",
+    "ad-coupon": "/components/jyj-components/ad-coupon/index"
+  }
+}
+```
+
+或在页面 JSON 中单独注册：
+
+```json
+{
+  "usingComponents": {
+    "ad-banner": "/components/jyj-components/ad-banner/index"
+  }
+}
+```
+
+### 3. 使用组件
+
+#### 示例 1：横幅广告
+
+**pages/index/index.wxml**
+```xml
+<view class="container">
+  <text>页面内容</text>
+
+  <!-- 横幅广告 -->
+  <ad-banner
+    slotId="banner-slot-001"
+    bind:adLoad="onBannerLoad"
+    bind:adError="onBannerError"
+  />
+</view>
+```
+
+**pages/index/index.js**
+```javascript
+Page({
+  onBannerLoad(e) {
+    console.log('横幅广告加载成功', e.detail);
+  },
+
+  onBannerError(e) {
+    console.error('横幅广告加载失败', e.detail);
+  }
+});
+```
+
+#### 示例 2：插屏广告
+
+**pages/game/game.wxml**
+```xml
+<view class="container">
+  <button bindtap="showAd">显示插屏广告</button>
+
+  <ad-interstitial
+    slotId="interstitial-slot-001"
+    isShow="{{showInterstitial}}"
+    isDestroy="{{destroyInterstitial}}"
+    bind:adClose="onAdClose"
+  />
+</view>
+```
+
+**pages/game/game.js**
+```javascript
+Page({
+  data: {
+    showInterstitial: false,
+    destroyInterstitial: false
+  },
+
+  showAd() {
+    this.setData({ showInterstitial: true });
+  },
+
+  onAdClose() {
+    this.setData({
+      showInterstitial: false,
+      destroyInterstitial: true
+    });
+  }
+});
+```
+
+#### 示例 3：激励视频
+
+**pages/reward/reward.wxml**
+```xml
+<view class="container">
+  <button bindtap="watchVideo">观看视频获得奖励</button>
+
+  <ad-rewarded-video
+    slotId="video-slot-001"
+    isShow="{{showVideo}}"
+    bind:adFinished="onVideoFinished"
+    bind:adClose="onVideoClose"
+  />
+</view>
+```
+
+**pages/reward/reward.js**
+```javascript
+Page({
+  data: {
+    showVideo: false,
+    coins: 100
+  },
+
+  watchVideo() {
+    this.setData({ showVideo: true });
+  },
+
+  onVideoFinished(e) {
+    if (e.detail.isEnded) {
+      // 用户看完视频，发放奖励
+      this.setData({
+        coins: this.data.coins + 50,
+        showVideo: false
+      });
+      wx.showToast({
+        title: '获得 50 金币',
+        icon: 'success'
+      });
+    }
+  },
+
+  onVideoClose() {
+    this.setData({ showVideo: false });
+  }
+});
+```
+
+#### 示例 4：开屏广告
+
+**app.js 或首页**
+```xml
+<ad-splash
+  slotId="splash-slot-001"
+  bind:adFinished="onSplashFinished"
+/>
+
+<view class="main-content" wx:if="{{!showSplash}}">
+  <!-- 主要内容 -->
+</view>
+```
+
+```javascript
+Page({
+  data: {
+    showSplash: true
+  },
+
+  onSplashFinished() {
+    this.setData({ showSplash: false });
+  }
+});
+```
+
+#### 示例 5：优惠券组件
+
+**pages/coupon/coupon.wxml**
+```xml
+<ad-coupon
+  secret="{{couponSecret}}"
+  phone="{{userPhone}}"
+  userId="{{userId}}"
+/>
+```
+
+**pages/coupon/coupon.js**
+```javascript
+Page({
+  data: {
+    couponSecret: 'secret-key-from-server',
+    userPhone: '13800138000',
+    userId: 'user123'
+  }
+});
+```
+
+### 4. 测试
+
+在微信开发者工具中打开你的小程序项目，即可看到广告组件的效果。
+
+### 5. 常见配置
+
+#### 获取 slotId
+
+联系后端开发人员或管理员获取有效的广告位 ID（slotId）。
+
+#### 广告数据格式
+
+后端接口应返回以下格式的数据：
+
+```json
+{
+  "code": 1,
+  "data": [
+    {
+      "id": "ad001",
+      "source": "wx",
+      "showCount": 3,
+      "banner": {
+        "unitId": "adunit-xxxxxxxx"
+      }
+    },
+    {
+      "id": "ad002",
+      "source": "custom",
+      "showCount": 2,
+      "banner": {
+        "material": "https://example.com/ad.jpg",
+        "appid": "wxAppId",
+        "path": "pages/index/index"
+      }
+    }
+  ]
+}
+```
+
+### 6. 下一步
+
+- 查看 [README.md](./README.md) 了解完整的 API 文档
+- 查看 `tools/demo` 目录中的完整示例
+- 运行 `npm run dev` 启动开发模式，实时预览组件效果
+
+## 故障排除
+
+### 问题：组件不显示
+
+**解决方案：**
+1. 检查 `slotId` 是否正确
+2. 打开调试器查看网络请求是否成功
+3. 确认后端返回的数据格式正确
+
+### 问题：构建失败
+
+**解决方案：**
+```bash
+# 清理并重新安装依赖
+npm run clean
+rm -rf node_modules
+npm install
+npm run build
+```
+
+### 问题：组件路径找不到
+
+**解决方案：**
+确保路径正确，使用绝对路径：
+```json
+{
+  "usingComponents": {
+    "ad-banner": "/components/jyj-components/ad-banner/index"
+  }
+}
+```
+
+## 技术支持
+
+如有问题，请查看：
+- [完整文档](./README.md)
+- [GitHub Issues](https://github.com/your-repo/issues)
+- 联系开发团队

package/README.md

@@ -0,0 +1,200 @@
+# 聚优甲广告组件库
+
+微信小程序广告组件库。
+
+## 安装
+
+### 方式一：npm 安装（推荐）
+
+```bash
+npm install jyj-components
+```
+
+在小程序 `app.json` 中配置：
+
+```json
+{
+  "usingComponents": {
+    "ad-banner": "jyj-components/ad-banner/index",
+    "ad-interstitial": "jyj-components/ad-interstitial/index",
+    "ad-rewarded-video": "jyj-components/ad-rewarded-video/index",
+    "ad-splash": "jyj-components/ad-splash/index"
+  }
+}
+```
+
+### 方式二：本地引入
+
+将 `miniprogram_dist` 目录复制到项目中，然后在 `app.json` 中配置相对路径。
+
+## 组件使用
+
+### 1. 横幅广告 (ad-banner)
+
+
+
+```xml
+<ad-banner
+  slotId="your-slot-id"
+  bind:adLoad="onAdLoad"
+  bind:adError="onAdError"
+/>
+```
+
+**属性：**
+- `slotId` (String, 必填)：广告位 ID
+
+**事件：**
+- `adLoad`：广告加载成功
+- `adError`：广告加载失败
+- `adOpenMiniProgram`：跳转小程序（自定义广告）
+
+### 2. 插屏广告 (ad-interstitial)
+
+
+```xml
+<ad-interstitial
+  slotId="your-slot-id"
+  isShow="{{showAd}}"
+  isDestroy="{{destroyAd}}"
+  bind:adLoad="onAdLoad"
+  bind:adError="onAdError"
+  bind:adClose="onAdClose"
+/>
+```
+
+**属性：**
+- `slotId` (String, 必填)：广告位 ID
+- `isShow` (Boolean)：控制广告显示
+- `isDestroy` (Boolean)：控制广告销毁 默认false 每个广告实例只能修改一次
+
+**事件：**
+- `adLoad`：广告加载成功
+- `adError`：广告加载失败
+- `adClose`：广告关闭
+
+**使用示例：**
+
+```javascript
+Page({
+  data: {
+    showAd: false,
+    destroyAd: false
+  },
+
+  showInterstitialAd() {
+    this.setData({ showAd: true });
+  },
+
+  onAdClose() {
+    this.setData({
+      showAd: false,
+      destroyAd: true
+    });
+  }
+});
+```
+
+### 3. 激励视频广告 (ad-rewarded-video)
+
+
+
+```xml
+<ad-rewarded-video
+  slotId="your-slot-id"
+  isShow="{{showVideo}}"
+  isDestroy="{{destroyVideo}}"
+  bind:adLoad="onAdLoad"
+  bind:adError="onAdError"
+  bind:adClose="onAdClose"
+  bind:adFinished="onAdFinished"
+/>
+```
+
+**属性：**
+- `slotId` (String, 必填)：广告位 ID
+- `isShow` (Boolean)：控制视频播放
+- `isDestroy` (Boolean)：控制广告销毁 默认false 每个广告实例只能修改一次
+
+**事件：**
+- `adLoad`：广告加载成功
+- `adError`：广告加载失败
+- `adClose`：广告关闭
+- `adFinished`：视频播放完成（用户获得奖励）
+
+**使用示例：**
+
+```javascript
+Page({
+  data: {
+    showVideo: false
+  },
+
+  watchVideoForReward() {
+    this.setData({ showVideo: true });
+  },
+
+  onAdFinished(e) {
+    if (e.detail.isEnded) {
+      // 用户看完视频，发放奖励
+      this.giveReward();
+    }
+  }
+});
+```
+
+### 4. 开屏广告 (ad-splash)
+
+
+```xml
+<ad-splash
+  slotId="your-slot-id"
+  bind:adLoad="onAdLoad"
+  bind:adError="onAdError"
+  bind:adFinished="onAdFinished"
+/>
+```
+
+**属性：**
+- `slotId` (String, 必填)：广告位 ID
+
+**事件：**
+- `adLoad`：广告加载成功
+- `adError`：广告加载失败
+- `adFinished`：广告结束（倒计时结束或用户跳过）
+
+**使用示例：**
+
+```javascript
+// app.js 或首页
+Page({
+  onLoad() {
+    // 开屏广告会自动展示
+  },
+
+  onAdFinished() {
+    // 广告结束，进入主页面
+    console.log('开屏广告结束');
+  }
+});
+```
+
+## 注意事项
+
+1. 向运营人员获取授权链接 通过授权链接授权权限
+2. **广告位 ID**：需要向运营人员申请有效的 `slotId`
+
+
+## 常见问题
+
+### Q: 广告不显示？
+A: 检查 `slotId` 是否正确，网络请求是否成功，广告数据格式是否正确。
+
+### Q: 如何控制广告展示时机？
+A: 使用 `isShow` 属性控制插屏和激励视频的展示时机。
+
+### Q: 如何销毁广告实例？
+A: 设置 `isDestroy` 为 `true` 即可销毁广告实例，释放内存。
+
+
+

package/gulpfile.js

@@ -0,0 +1,26 @@
+const gulp = require('gulp')
+const clean = require('gulp-clean')
+
+const config = require('./tools/config')
+const BuildTask = require('./tools/build')
+const id = require('./package.json').name || 'miniprogram-custom-component'
+
+// 构建任务实例
+// eslint-disable-next-line no-new
+new BuildTask(id, config.entry)
+
+// 清空生成目录和文件
+gulp.task('clean', gulp.series(() => gulp.src(config.distPath, {read: false, allowEmpty: true}).pipe(clean()), done => {
+  if (config.isDev) {
+    return gulp.src(config.demoDist, {read: false, allowEmpty: true})
+      .pipe(clean())
+  }
+
+  return done()
+}))
+// 监听文件变化并进行开发模式构建
+gulp.task('watch', gulp.series(`${id}-watch`))
+// 开发模式构建
+gulp.task('dev', gulp.series(`${id}-dev`))
+// 生产模式构建
+gulp.task('default', gulp.series(`${id}-default`))