概念	说明	相关组件或 API
屏幕亮度调节	控制屏幕明暗程度（范围 `0~1`），支持获取和设置。	•tt.getScreenBrightness •tt.setScreenBrightness
录屏	阻止或允许用户使用系统级录屏功能，仅在当前页面生效。	•tt.disableUserScreenRecord •tt.enableUserScreenRecord
截屏/录屏事件监听	监测用户截屏或录屏行为，触发自定义逻辑（如提示弹窗）。	•tt.onUserCaptureScreen •tt.offUserCaptureScreen •tt.onUserScreenRecord •tt.offUserScreenRecord
视频组件	抖音小程序原生视频组件，支持清晰度切换、进度控制等。	video

目标

本教程实现了抖音小程序中屏幕相关的核心功能：

视频播放与清晰度切换（video 组件）。

屏幕亮度调节（tt.getScreenBrightness 和 tt.setScreenBrightness）。

禁止录屏（tt.disableUserScreenRecord）。

录屏事件监听（tt.onUserScreenRecord 和 tt.offUserScreenRecord）。

准备工作

开发抖音小程序的视图容器前，你需要完成以下前置准备，详情请参见开发准备。

•

注册账号并完成认证

•

创建小程序

•

添加协作者/管理员

•

安装抖音开发者工具 IDE

步骤一：在 IDE 新建小程序项目

具体步骤请参见创建小程序项目。

步骤二：嵌入视频并实现清晰度切换

•

播放指定视频，提供 480P 和 720P 清晰度选择。

•

视频地址：https://sf1-ttcdn-tos.pstatp.com/obj/developer/sdk/1534422848153.mp4

本教程重点在屏幕设置，不介绍 video 组件的开发过程，video 组件的具体开发步骤请参见开发 Video 视频组件。

index.ttml

index.js

index.ttss

<view class="container">
  <!-- 视频组件 -->
  <video
    id="myVideo"
    src="{{videoSrc}}"
    controls
    objectFit="fill"
    style="width: 100%; height: 300px;"
  ></video>
  
  <!-- 清晰度选择 -->
  <view class="quality-btn-group">
    <button bindtap="setQuality" data-quality="480">480P</button>
    <button bindtap="setQuality" data-quality="720">720P</button>
  </view>
</view>

代码讲解：

•

<video> 组件通过 src 绑定视频源，controls 显示原生控制条。

•

data-quality 自定义属性存储清晰度参数，通过 e.currentTarget.dataset.quality 读取。

•

setData 更新视频源，触发组件重新加载视频。

完成上述步骤后，页面如下：

步骤三：屏幕亮度调节与显示

显示当前屏幕亮度，通过滑块调节亮度（范围 0~1）。

在 index.ttml 添加亮度显示和滑块组件。

◦

初始化显示：页面加载时，通过 tt.getScreenBrightness 获取初始亮度值，更新 data.brightness，触发页面渲染，文本和滑块同步显示初始值。

◦

用户调节亮度：

▪

滑动滑块时，value 实时变化，但仅在滑动结束后（或实时，取决于小程序实现）触发 bindchange 事件。

▪

onBrightnessChange 函数中，通过 tt.setScreenBrightness 将滑块值设置为当前屏幕亮度，并更新 data.brightness，实现双向同步（滑块位置 ↔ 屏幕亮度 ↔ 文本显示）。

◦

视觉反馈：activeColor 直观显示亮度进度，toFixed(2) 确保文本显示与滑块精度一致（均为两位小数）。

<view class="brightness-container">
  <text>屏幕亮度：{{brightness.toFixed(2)}}</text> <!-- 保留两位小数 -->
  <slider
    value="{{brightness}}"
    min="0"
    max="1"
    step="0.01"
    bindchange="onBrightnessChange"
    activeColor="#ffd700"
  />
</view>

编写 index.js，获取初始亮度并处理滑块变化。

◦

数据初始化（data）：存储屏幕亮度值 brightness（初始值为 0），通过 数据绑定 连接页面视图（如滑块、文本）与逻辑层，确保数据变化时视图自动更新。

◦

页面加载逻辑（onLoad）：页面加载时调用 getInitialBrightness，用于 获取设备当前屏幕亮度，确保用户进入页面时显示的亮度与实际设备一致。

◦

获取初始亮度（getInitialBrightness）：调用 tt.getScreenBrightness API 获取当前亮度值。

▪

成功时：通过 setData 更新 brightness，触发页面视图更新（如滑块位置、亮度文本）。

▪

失败时：控制台打印错误并提示用户，增强容错性。

◦

滑块变化事件处理（onBrightnessChange）：获取滑块当前值 value，调用 tt.setScreenBrightness 设置设备屏幕亮度。

▪

成功时：更新 brightness（确保滑块位置与实际亮度同步），并通过 Toast 提示用户当前亮度（保留两位小数）。

▪

失败时：记录错误，确保异常情况不影响用户操作。

Page({
  data: {
    brightness: 0, // 初始亮度
  },
  
  onLoad() {
    this.getInitialBrightness(); // 页面加载时获取初始亮度
  },
  
  // 获取初始亮度
  getInitialBrightness() {
    tt.getScreenBrightness({
      success: (res) => {
        this.setData({ brightness: res.value });
      },
      fail: (err) => {
        console.error("获取亮度失败：", err);
        tt.showToast({ title: "亮度获取失败", icon: "none" });
      }
    });
  },
  
  // 滑块变化事件
  onBrightnessChange(e) {
    const value = e.detail.value;
    tt.setScreenBrightness({
      value,
      success: () => {
        this.setData({ brightness: value });
        tt.showToast({ title: `亮度设置为 ${value.toFixed(2)}`, icon: "none" });
      },
      fail: (err) => {
        console.error("设置亮度失败：", err);
      }
    });
  }
});

在index.ttss 中优化亮度模块布局。

.brightness-container {
  padding: 20px;
  background-color: #f5f5f5;
  border-radius: 8px;
  margin-bottom: 20px;
}
.brightness-container text {
  font-size: 16px;
  margin-right: 10px;
}

完成上述步骤后，页面如下：

步骤四：禁止当前页面录屏

当小程序中有需要保护的敏感信息、版权内容或隐私数据时，例如付费课程、机密文档展示页面，可使用 tt.disableUserScreenRecord 禁止用户录屏造成信息泄露。

在 index.js 中调用 tt.disableUserScreenRecord 禁止当前页面的系统级录屏，确保用户进入页面时录屏功能已被限制。

说明

•

禁止录屏生效后，用户仍可以通过手机系统自带的录屏功能进行录制，但会显示为黑屏，看不到当前页面的具体内容。

•

目前不支持通过 API 直接禁止用户使用系统级截屏功能（如手机物理按键截屏、手势截屏等）。tt.onUserCaptureScreen 仅能监听截屏行为，并在截屏发生后提示用户，但无法阻止截屏操作。

•

onLoad ：调用 this.disableScreenRecording() 方法，目的是在页面加载时就触发禁止录屏的操作。

•

disableScreenRecording ：该函数封装了禁止录屏的具体逻辑。

◦

tt.disableUserScreenRecord 是抖音小程序提供的 API，用于禁止用户录屏。

◦

success ：当禁止录屏操作成功时执行，在控制台打印 “禁止录屏成功” 的信息，并且使用 tt.showToast 提示用户。

◦

fail ：当禁止录屏操作失败时执行，将错误信息打印到控制台，同时使用 tt.showToast 弹出提示框告知用户禁止录屏失败。

Page({
  onLoad() {
    this.disableScreenRecording(); // 新增禁止录屏逻辑
  },
  
  // 禁止录屏
  disableScreenRecording() {
    tt.disableUserScreenRecord({
      success: () => {
        console.log("禁止录屏成功");
        tt.showToast({ title: "当前页面禁止录屏", icon: "none" }); 
      },
      fail: (err) => {
        console.error("禁止录屏失败：", err);
        tt.showToast({ title: "禁止录屏失败", icon: "none" });
      }
    });
  }
});

步骤五：监听用户截屏和录屏事件

监测用户截屏和录屏操作，触发提示弹窗。

注意

•

tt.onUserScreenRecord 支持监听系统级录屏（如手机自带的录屏功能），但无法监听第三方应用录屏。

•

部分机型或抖音版本可能对该 API 支持有限，建议添加 tt.canIUse('onUserScreenRecord') 兼容性检测。

在index.ttml中添加状态显示区域（可选，用于显示监听状态）。

◦

按钮禁用逻辑：通过 disabled="{{isListening}}" 和 disabled="{{!isListening}}" 确保同一时间只有一个按钮可用。

◦

状态显示：实时显示当前监听状态和录屏事件反馈，增强用户感知。

<view class="button-listen">
    <button 
      type="primary" 
      disabled="{{isListening}}" 
      bindtap="startListening"
    >
      开启录屏监听
    </button>
    <button 
      type="warn" 
      disabled="{{!isListening}}" 
      bindtap="stopListening"
    >
      取消录屏监听
    </button>
  </view>

在index.js 定义监听函数并在 onLoad 中启用监听。

◦

数据状态管理（data）

▪

isListening：标记当前是否处于录屏监听状态，用于控制按钮的禁用状态（开启后禁用 “开启” 按钮，反之禁用 “取消” 按钮）。

▪

recordStatus：显示当前监听状态或录屏事件反馈（如 “检测到录屏开始”）。

◦

开启监听（startListening）

▪

核心 API：tt.onUserScreenRecord，接收一个回调函数，当用户开始 / 停止录屏时触发。

▪

回调逻辑：根据 res.state 判断录屏状态（start/stop），更新 recordStatus 并显示 Toast 提示。

▪

状态更新：开启监听后，设置 isListening: true，并通过 disabled 属性禁用 “开启” 按钮，避免重复调用。

◦

取消监听（stopListening）

▪

核心 API：通过保存的 listener 引用调用解绑（或直接使用 tt.offUserScreenRecord），确保移除事件监听，避免内存泄漏。

▪

状态更新：取消监听后，设置 isListening: false，禁用 “取消” 按钮，恢复 “开启” 按钮可用。

Page({
  data: {
    monitorStatus: "未监听"
  },
  
  onLoad() {
    this.getInitialBrightness();
    this.disableScreenRecording();
    this.startMonitor(); // 新增监听初始化
  },
  
  // 启动监听
  startMonitor() {
    this.setData({ monitorStatus: "监听中" });
    
    // 监听截屏
    tt.onUserCaptureScreen(() => {
      tt.showToast({
        title: "检测到截屏操作",
        icon: "none",
        duration: 2000
      });
    });
    
    // 监听录屏开始（即使页面禁止录屏，部分设备仍可能尝试录屏）
    tt.onUserScreenRecordStart(() => {
      tt.showToast({
        title: "检测到录屏开始",
        icon: "none",
        duration: 2000
      });
    });
    
    // 监听录屏结束
    tt.onUserScreenRecordStop(() => {
      tt.showToast({
        title: "检测到录屏结束",
        icon: "none",
        duration: 2000
      });
    });
  },
  
  // 页面卸载时清除监听（可选，避免内存泄漏）
  onUnload() {
    tt.offUserCaptureScreen();
    tt.offUserScreenRecordStart();
    tt.offUserScreenRecordStop();
  }
});

完成上述步骤后，页面如下：

完整代码示例

index.ttml

index.ttss

index.js

<view class="container">
    <!-- 视频组件 -->
    <video
      id="myVideo"
      src="{{videoSrc}}"
      controls
      objectFit="fill"
      style="width: 100%; height: 300px;"
    ></video>
    
    <!-- 清晰度选择 -->
    <view class="quality-btn-group">
      <button bindtap="setQuality" data-quality="480">480P</button>
      <button bindtap="setQuality" data-quality="720">720P</button>
    </view>
  </view>

  <view class="brightness-container">
    <text>屏幕亮度：{{brightness.toFixed(2)}}</text> <!-- 保留两位小数 -->
    <slider
      value="{{brightness}}"
      min="0"
      max="1"
      step="0.01"
      bindchange="onBrightnessChange"
      activeColor="#ffd700"
    />
  </view>

  <view class="button-listen">
    <button 
      type="primary" 
      disabled="{{isListening}}" 
      bindtap="startListening"
    >
      开启录屏监听
    </button>
    <button 
      type="warn" 
      disabled="{{!isListening}}" 
      bindtap="stopListening"
    >
      取消录屏监听
    </button>
  </view>

结果验证

您可以在 IDE 中验证本教程实现的各个功能，也可以对小程序进行预览和调试，详情请参见 IDE 调试和真机调试。