开发教程与代码示例

入门

小程序框架

小程序运行时

自定义组件

基础教程

能力教程

流量入口

通用能力

推广变现

经营能力

行业能力

AI/AR 能力

性能优化

安全

自定义页面结构
收藏
我的收藏

简介

本 Codelabs 将聚焦在如何设计、申请和开发自定义页面结构。

能力介绍

为保障小程序的良好体验，在原本的标准化导航栏之外提供「自定义页面结构能力」供开发者使用。申请能力通过后，顶部导航栏将不再展示，小程序可以以沉浸式样式展示。

自定义导航栏能力设计初衷是为了提升小程序的用户体验，申请能力的开发者需详细阅读设计指南，按照指南要求完成页面布局配置，保证用户体验。

标准化导航栏	自定义导航栏

标准化导航栏下，页面的可绘制高度为导航栏以下区域；而自定义导航栏下，页面的可绘制高度为页面全局，开发者可依据自身需求在导航栏区增加标题、搜索、Tab、定位等内容。

因此，需要注意：

设计内容需避开 logo、返回、胶囊（反馈、更多、关闭）三个元素。

元素与平台胶囊需居中对齐，不重叠、不错位、元素间保持一定的安全距离。

准入条件

•

账号主体需为企业主体，详情查看入驻抖音开放平台；

•

小程序需上线，详情查看发布上线；

•

信用分达到 90 分，详情查看信用分介绍；

•

申请时需明确告知能力预期的使用场景，且使用场景符合平台要求。

•

申请时需附上详细抖音小程序的设计稿或真实线上截图，需要保证优质的用户体验，遵循设计规范。

最终效果

学习内容

小程序自定义页面结构介绍。

如何在开发者平台控制台申请自定义页面结构能力。

如何在项目中接入及使用自定义导航栏。

能力申请

开发者平台申请

第一步：进入申请页

登录开发者平台控制台。

在「我的应用」页面中点击「小程序」，然后在「小程序」页签中点击已创建的应用。

在应用详情页面左侧导航栏选择「能力」>「互动能力」。在「互动能力」页面点击「容器界面」，在「容器界面」页签的「自定义导航栏」区域点击「申请开通」。

第二步：填写信息提交申请

申请该能力时需要填写「申请原因」、「使用场景」及「场景示例图」。

平台根据填写的信息及小程序的内容进行审核。

若开通后，发现开发者在使用过程中滥用此能力，对用户或平台造成负面影响，平台将有权利随时对该功能进行收回，并视情况对违规的小程序进行处罚。

第三步：平台审核

平台根据填写的应用场景及小程序内容进行审核，审核时间为 5 个工作日。

服务端 OpenAPI 申请

见接口列表：

API名称	API类型	API描述
申请能力	OpenAPI	通过该接口申请页面结构自定义能力
查询能力申请状态	OpenAPI	查询页面结构自定义能力申请状态
管理页面结构自定义能力（服务商调用）	OpenAPI	服务商可通过该系列接口申请能力并查询能力申请状态

能力使用

使用 tt.getCustomButtonBoundingClientRect 获取自定义导航栏可绘制区域。

在开发者工具预览。

确认导航栏绘制内容

// tt-get-custom-button-bounding-client-rect.ttml
<view class="title" style="line-height:{{height}};height:{{height}};margin-top:{{marginTop}};margin-left: {{marginLeft}};margin-right:{{marginRight}}">自定义导航栏区域</view>

获取自定义导航栏可绘制区域位置信息

Page({
  data: {
    marginTop: '',
    height: '',
    marginLeft: '',
    marginRight: '',
    leftIconKeys: [],
    leftIconInfo: {},
    capsuleKeys: [],
    capsuleInfo: {},
    systemInfo: {},
    customNavigationInfo: {},
    customNavigationKeys: []
  },
  unit: 'px',
  onReady: function() {
    console.log(this.unit)
    if(tt.canIUse("getCustomButtonBoundingClientRect.return.customNavigation")) {
      try{
        const res = tt.getCustomButtonBoundingClientRect({
          measurementUnit: this.unit
        });
        // 使用优化后的参数
        const top = res.customNavigation.marginTop;
        const height = res.customNavigation.height;
        const left = res.customNavigation.marginLeft;
        const right = res.customNavigation.marginRight;
        this.setData({
          marginTop: top + this.unit,
          marginLeft: left + this.unit,
          marginRight: right + this.unit,
          height: height + this.unit,
        })
      }catch(e) {
        // getCustomButtonBoundingClientRect只适用于自定义导航栏
        // 非自定义（默认）导航栏调用将抛出错误
        console.log(e);
      }
    } else {
      try{
        const res = tt.getCustomButtonBoundingClientRect();
        const systemInfo = tt.getSystemInfoSync();
        console.log(res);
        // 使用之前的参数
        const top = res.capsule.top;
        const height = res.capsule.height;
        const left = res.leftIcon?.right ?? 0;
        const right = systemInfo.windowWidth - res.capsule.left;
        this.unit = 'px';
        this.setData({
          marginTop: top + this.unit,
          marginLeft: left + this.unit,
          marginRight: right + this.unit,
          height: height + this.unit,
        })
      }catch(e) {
        // getCustomButtonBoundingClientRect只适用于自定义导航栏
        // 非自定义（默认）导航栏调用将抛出错误
        console.log(e);
      }

    }
  },
  getCustomButtonInfo() {
    if(tt.canIUse("getCustomButtonBoundingClientRect")) {
      try {
        let res = tt.getCustomButtonBoundingClientRect();
        this.setData({
          leftIconInfo: res.leftIcon,
          leftIconKeys: Object.keys(res.leftIcon),
          capsuleInfo: res.capsule,
          capsuleKeys: Object.keys(res.capsule),
          customNavigationInfo: res?.customNavigation,
          customNavigationKeys: Object.keys(res?.customNavigation ?? {})
        })
      } catch (error) {
        // getCustomButtonBoundingClientRect只适用于自定义导航栏
        // 非自定义（默认）导航栏调用将抛出错误
        console.log(error);
      }
    }  else {
      tt.showModal({
        title: "提示",
        content:
          "当前客户端版本过低，无法使用该功能，请升级客户端或关闭后重启更新。",
      });
    }
  },
})

在页面配置里配置自定义导航栏

// tt-get-custom-button-bounding-client-rect.json
{"navigationBarTitleText":"获取胶囊按钮信息","navigationStyle":"custom"}

在 IDE 中使用不同机型调试，保证不同机型兼容性

总结

恭喜，你已经完成了自定义页面结构接入 Codelab。

你在该 Codelab 中了解了：

•

如何完成自定义页面结构能力申请

•

在小程序中使用api绘制自定义导航栏位置

更多资料查看：

•