关于Bigcommerce自定义私有应用适配Blueprint/Stencil的前端内容注入问询

我太懂你现在的困扰了——Bigcommerce官方文档在跨主题兼容的前端细节上确实有点零散，不过你已经搭好hello-world基础环境，这步已经赢在起跑线了！接下来咱们针对商品页按钮+弹窗的需求，一步步搞定两大主题的适配：

一、Stencil主题（主流推荐，比如Cornerstone） #

Stencil基于Bootstrap构建，自带很多现成的样式和组件，适配起来相对省心：

• 利用主题模板钩子/脚本管理器注入按钮
  如果你不想修改主题代码（私有应用最佳实践），直接用后台的「Storefront → Script Manager」添加脚本：选择「Product Page」作为注入位置，插入按钮的HTML和触发逻辑：

  <button id="custom-app-modal-btn" class="btn btn-primary mt-3">打开私有应用内容</button>
  

  用主题自带的btn类能直接匹配当前主题的按钮样式，不用自己折腾CSS。
• 动态加载弹窗并适配样式
  弹窗用Stencil自带的Bootstrap模态框，避免样式冲突，同时从你的私有应用拉取内容：

  document.addEventListener('DOMContentLoaded', () => {
    const triggerBtn = document.getElementById('custom-app-modal-btn');
    
    // 动态创建模态框结构
    const modal = document.createElement('div');
    modal.className = 'modal fade';
    modal.innerHTML = `
      <div class="modal-dialog">
        <div class="modal-content">
          <div class="modal-header">
            <h5 class="modal-title">私有应用专属内容</h5>
            <button type="button" class="close" data-dismiss="modal">&times;</button>
          </div>
          <div class="modal-body" id="modal-content-container"></div>
        </div>
      </div>
    `;
    document.body.appendChild(modal);
  
    // 点击按钮拉取内容并弹窗
    triggerBtn.addEventListener('click', () => {
      fetch('你的私有应用内容接口')
        .then(res => res.text())
        .then(html => {
          document.getElementById('modal-content-container').innerHTML = html;
          $(modal).modal('show'); // 用Stencil自带的jQuery Bootstrap方法
        });
    });
  });
  

• 自定义样式适配
  如果需要微调样式，用Stencil的CSS变量继承主题配色，比如：

  #custom-app-modal-btn {
    background-color: var(--primary-color);
    border-color: var(--primary-color);
  }
  

二、Blueprint主题（旧版主题，比如Classic） #

Blueprint是Bigcommerce的旧版主题体系，没有Bootstrap依赖，需要手动适配样式：

• 注入按钮与样式匹配
  同样用Script Manager注入按钮，用Blueprint自带的button类匹配主题样式：

  <button id="blueprint-custom-modal-btn" class="button">打开私有应用内容</button>
  

• 原生JS实现弹窗
  因为Blueprint没有自带模态框，自己写轻量版弹窗避免冲突：

  document.addEventListener('DOMContentLoaded', () => {
    const triggerBtn = document.getElementById('blueprint-custom-modal-btn');
    
    // 创建弹窗遮罩和内容容器
    const overlay = document.createElement('div');
    overlay.className = 'custom-modal-overlay';
    overlay.style.display = 'none';
    
    const contentBox = document.createElement('div');
    contentBox.className = 'custom-modal-content';
    overlay.appendChild(contentBox);
    document.body.appendChild(overlay);
  
    // 加载内容并显示弹窗
    triggerBtn.addEventListener('click', () => {
      fetch('你的私有应用内容接口')
        .then(res => res.text())
        .then(html => {
          contentBox.innerHTML = html;
          overlay.style.display = 'block';
        });
    });
  
    // 点击遮罩关闭弹窗
    overlay.addEventListener('click', (e) => {
      if (e.target === overlay) overlay.style.display = 'none';
    });
  });
  

  配套CSS适配Blueprint风格：

  .custom-modal-overlay {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: rgba(0,0,0,0.6);
    z-index: 9999;
  }
  .custom-modal-content {
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    background: #fff;
    padding: 25px;
    width: 85%;
    max-width: 600px;
    box-shadow: 0 0 15px rgba(0,0,0,0.3);
  }
  

三、跨主题通用技巧 #

• 主题检测
  通过HTML标签的类名区分主题，写一套兼容代码：

  const isStencil = document.documentElement.classList.contains('stencil');
  const isBlueprint = document.documentElement.classList.contains('blueprint');
  
  if (isStencil) {
    // 执行Stencil逻辑
  } else if (isBlueprint) {
    // 执行Blueprint逻辑
  }
  

• 权限与安全
  确保私有应用拥有storefront_content_read权限，前端调用接口时做好身份验证（比如用JWT，别把敏感密钥暴露在前端代码里）。
• 测试验证
  分别用Cornerstone（Stencil）和Classic（Blueprint）测试店铺验证功能，确保按钮样式、弹窗逻辑在两种主题下都正常工作。

内容的提问来源于stack exchange，提问作者Aljay