更新记录

1.0.1（2026-07-24）

1.0.0（2026-07-24）

• 首次发布
• 新增 iOS 端 requestAgeRange 接口，调用 Apple DeclaredAgeRange 框架获取用户声明年龄范围
• 支持传入最多 3 个年龄阈值，返回年龄区间上下界、声明方式与分享状态
• 返回结果新增 activeParentalControls 字段（家长控制项）

平台兼容性

uni-app(4.84)

uni-app x(4.84)

hl-age-range-uts

Apple Declared Age Range（声明年龄范围） UTS 插件。

简单说：调用 iOS 系统弹窗，让用户（或家长）决定是否把「年龄范围」分享给你的 App，你拿到的不是精确生日，而是类似「13～14 岁」「16 岁及以上」这样的区间，用来做适龄功能开关。

注意：仅 iOS 26.0+，且需 Xcode 26+ 编译。Android / HarmonyOS 无此系统能力。

一、你需要准备什么

按顺序做，缺一步都可能签名失败或运行时报错。

本仓库已带 demo 页：pages/age-range-demo/index，配好能力后可直接真机验证。

二、能力配置（最关键，一步步来）

这项能力不是在证书里配，而是在 App ID + 描述文件 上开通。

2.1 插件侧（已配好，了解即可）

文件位置：

uni_modules/hl-age-range-uts/utssdk/app-ios/UTS.entitlements

内容：

<key>com.apple.developer.declared-age-range</key>
<true/>

2.3 配完怎么确认？

• 描述文件重新生成时间是新的
• 打包用的 Bundle ID = 已勾选能力的那个 App ID
• 安装到 iOS 26+ 真机后，点 demo「获取年龄范围」能弹出系统界面（而不是马上返回 -10 / -11）

三、平台支持

四、API 说明

requestAgeRange(ageGates, callback)

向系统请求用户的声明年龄范围。系统会弹出说明界面，由用户或监护人选择是否分享。

ageGates 是什么意思？

你告诉系统「你关心哪些年龄分界线」。例如传 [13, 15, 18]，系统会据此划分年龄段；返回结果里用 lowerBound / upperBound 告诉你用户落在哪一段。

• lowerBound == null：低于你设的最低阈值（例如「不到 13」）
• upperBound == null：达到或超过最高阈值（例如「18 及以上」）

返回字段 AgeRangeResult

activeParentalControls 可能的值

错误码

五、使用示例

<template>
  <view class="container">
    <button @click="getAgeRange">获取年龄范围</button>
    <text v-if="resultText">{{ resultText }}</text>
  </view>
</template>

<script setup>
import { ref } from 'vue'
import { requestAgeRange } from '@/uni_modules/hl-age-range-uts'

const resultText = ref('')

const getAgeRange = () => {
  // 关心 16 岁这条分界线；也可写成 [13, 15, 18]
  requestAgeRange([16], (result) => {
    if (result.code != 0) {
      resultText.value = `错误(${result.code})：${result.message}`
      return
    }
    if (!result.shared) {
      resultText.value = '用户拒绝分享年龄范围'
      return
    }

    // 例：判断是否达到 16 岁及以上
    if (result.lowerBound != null && result.lowerBound >= 16) {
      resultText.value = '用户可能是 16+'
    } else {
      resultText.value = `年龄范围：${result.lowerBound ?? '-'} ~ ${result.upperBound ?? '+'}，声明方式：${result.declaration}`
    }

    // 可选：处理家长控制
    if (result.activeParentalControls.indexOf('communicationLimits') >= 0) {
      // 限制聊天 / 通讯类功能
    }
  })
}
</script>

六、常见问题（FAQ）

Q1：证书里要勾什么吗？
不需要。证书只管签名身份。要勾的是 App ID 上的 Declared Age Range，然后重新生成描述文件。

Q2：返回 code = 0 但没有年龄？
看 shared。shared = false 表示用户拒绝分享，这是正常业务结果，不是崩溃。

Q3：一直返回 -10 / -11？

• -10：打包用的 Xcode / SDK 太旧
• -11：真机系统不是 iOS 26+

Q5：怎么测试？
建议 iOS 26.2+ 真机 + Sandbox Apple 账号。普通账号/旧系统可能弹不出完整流程。