uniapp项目发布H5，设置支付宝环境下访问H5自定义导航栏

菜喵007
272 阅读4分钟

使用 AlipayJSBridge 设置支付宝 H5 页面标题栏颜色

本文档基于支付宝 H5 环境的 AlipayJSBridge API，详细介绍如何设置页面标题栏颜色。

功能概述

在支付宝 H5 环境中，通过 AlipayJSBridge 的 setTitleColor 方法，可以自定义页面标题栏的背景颜色，提升页面与品牌风格的一致性。

效果展示

在这里插入图片描述

代码实现

以下为代码，包含环境检测、错误处理、动态颜色设置和超时机制：

// 设置支付宝 H5 页面标题栏颜色
function setAlipayTitleColor(colorHex = 'FF0000', reset = false, timeoutMs = 5000) {
  // 移除颜色值中的 # 号并转换为十进制
  const parseColor = (hex) => {
    const cleanHex = hex.replace(/^#/, '');
    return parseInt(cleanHex, 16);
  };

  // 检查是否在支付宝 H5 环境中
  if (typeof AlipayJSBridge === 'undefined') {
    console.error('当前页面未在支付宝 H5 环境中打开');
    return Promise.reject(new Error('非支付宝环境'));
  }

  return new Promise((resolve, reject) => {
    // 设置超时机制
    const timeout = setTimeout(() => {
      console.error('AlipayJSBridge 初始化超时');
      reject(new Error('AlipayJSBridge 初始化超时'));
    }, timeoutMs);

    // 监听 AlipayJSBridge 就绪事件
    document.addEventListener(
      'AlipayJSBridgeReady',
      () => {
        try {
          // 清除超时计时器
          clearTimeout(timeout);
          
          // 调用 setTitleColor API
          AlipayJSBridge.call('setTitleColor', {
            color: parseColor(colorHex),
            reset: reset // 是否重置为支付宝默认颜色
          }, (result) => {
            if (result && result.error) {
              console.error(`设置标题栏颜色失败: ${result.errorMessage || '未知错误'}`);
              reject(new Error(result.errorMessage || '设置标题栏颜色失败'));
            } else {
              console.log(`标题栏颜色已设置为 #${colorHex}`);
              resolve(result);
            }
          });
        } catch (error) {
          console.error(`调用 AlipayJSBridge 失败: ${error.message}`);
          reject(error);
        }
      },
      { once: true } // 事件只触发一次
    );
  });
}

// 示例调用
setAlipayTitleColor('FF0000', false)
  .then(() => console.log('标题栏颜色设置成功'))
  .catch((error) => console.error('标题栏颜色设置失败:', error.message));

优化亮点

  1. 模块化函数：

    • 封装为 setAlipayTitleColor 函数，支持动态传入颜色值（colorHex）、重置标志（reset）和超时时间（timeoutMs）。
    • 默认颜色为 #FF0000，默认不重置，超时时间为 5 秒。

  2. 健壮的错误处理：

    • 检查 AlipayJSBridge 是否存在，避免在非支付宝环境中运行。
    • 添加 try-catch 捕获 API 调用中的异常。
    • 处理 setTitleColor 的返回结果，记录错误信息。

  3. 异步支持：

    • 使用 Promise 封装，支持异步调用，便于链式操作和错误处理。
    • 添加超时机制，避免 AlipayJSBridgeReady 事件长时间未触发。

  4. 颜色处理：

    • 支持带 # 或不带 # 的十六进制颜色值，增强兼容性。
    • 使用 toLocaleString 格式化颜色值，提升日志可读性。

  5. 事件优化：

    • 使用 { once: true } 确保事件监听器只触发一次，释放资源。
    • 清除超时计时器，避免内存泄漏。

使用方法

  1. 引入代码：

    • 将上述代码复制到项目的 JavaScript 文件中（如 utils/alipay.js）。

  2. 调用函数：

    • 根据需求传入颜色值（支持 #FF0000 或 FF0000 格式）： 
      setAlipayTitleColor('00FF00') // 设置为绿色
  .then(() => console.log('标题栏颜色设置为绿色'))
  .catch((error) => console.error('设置失败:', error.message));

  3. 动态配置：

    • 可根据页面需求动态设置颜色： 
      const brandColor = window.location.search.includes('theme=dark') ? '333333' : 'FF0000';
setAlipayTitleColor(brandColor, false, 3000);

注意事项

  1. 环境要求：

    • 确保页面在支付宝 H5 环境中运行（如支付宝小程序或支付宝浏览器）。
    • 可通过 navigator.userAgent 进一步验证环境： 
      const isAlipay = /AlipayClient/.test(navigator.userAgent);

  2. 颜色格式：

    • 颜色值必须为有效的十六进制格式（如 FF0000 或 #FF0000）。
    • 无效颜色值可能导致 API 调用失败。

  3. 超时处理：

    • 默认超时时间为 5 秒，可根据网络环境调整 timeoutMs 参数。
    • 超时后会触发错误，建议在 UI 中提示用户。

  4. API 兼容性：

    • 参考支付宝官方文档 Alipay JSAPI 确保 setTitleColor API 可用。
    • 不同支付宝版本可能存在兼容性差异，建议测试多个版本。

调试建议

  1. 检查环境：

    • 在非支付宝环境中，日志会输出“当前页面未在支付宝 H5 环境中打开”。
    • 确保页面通过支付宝客户端或模拟器访问。

  2. 验证效果：

    • 检查标题栏颜色是否变化为指定颜色（如 #FF0000 为红色）。
    • 若无变化，查看控制台日志，确认是否有错误信息。

  3. 性能优化：

    • 避免频繁调用 setAlipayTitleColor，建议在页面初始化时调用一次。
    • 使用 { once: true } 减少事件监听器的内存占用。

总结

通过优化后的 setAlipayTitleColor 函数，开发者可以轻松在支付宝 H5 环境中设置标题栏颜色

如需进一步帮助，请参考 Alipay JSAPI 官方文档。

avatar
文章
阅读
粉丝