更新记录

1.0.0（2026-02-15）

基于阿里云一键登录SDK的鸿蒙UTS插件，支持uni-app和uni-app x项目。

平台兼容性

uni-app(4.76)

uni-app x(4.76)

阿里云一键登录鸿蒙UTS插件

基于阿里云一键登录SDK的鸿蒙UTS插件，支持uni-app和uni-app x项目。

功能特性

• ✅ 支持鸿蒙系统一键登录
• ✅ 自动获取手机号码
• ✅ 支持三大运营商（移动、联通、电信）
• ✅ 支持自定义授权页UI配置
• ✅ 支持自定义登录页和协议详情页组件
• ✅ 支持切换到短信登录回调
• ✅ 完整的错误处理机制
• ✅ TypeScript类型支持

安装配置

1. 配置依赖

阿里云一键登录SDK已包含在插件的 libs 目录中，无需额外安装。依赖配置已在 utssdk/app-harmony/config.json 中配置：

{
  "dependencies": {
    "numberauth_standard": "./libs/auth_number_product-v2.0.17-log-online-standard-release.har"
  }
}

2. 配置权限

插件会自动配置以下权限：

• ohos.permission.INTERNET - 网络访问权限
• ohos.permission.GET_NETWORK_INFO - 获取网络状态
• ohos.permission.GET_TELEPHONY_STATE - 获取手机状态
• ohos.permission.READ_PHONE_STATE - 读取手机状态

权限说明文本存储在 utssdk/app-harmony/resources/base/element/string.json 中，支持国际化。

使用方法

1. 初始化SDK密钥（可选，推荐）

在应用启动时设置SDK密钥，这样后续调用 oneClickLogin 时就不需要每次都传入 secretInfo：

import { setAuthSDKInfo } from "@/uni_modules/zzc-ali-one-click-login";

// 在 App.vue 的 onLaunch 中
setAuthSDKInfo("your_secret_info"); // 从阿里云控制台获取的SDK密钥

2. 检查一键登录是否可用

import { checkOneClickLoginAvailable } from "@/uni_modules/zzc-ali-one-click-login";

// 检查一键登录是否可用（需要传入 secretInfo）
const isAvailable = await checkOneClickLoginAvailable({
  secretInfo: "your_secret_info", // SDK密钥
});

if (!isAvailable) {
  console.log("当前设备不支持一键登录");
  // 显示短信登录界面
} else {
  // 显示一键登录按钮
}

3. 执行一键登录

import {
  oneClickLogin,
  setAuthConfig,
  quitLoginPage,
  toSetSwitchToSmsLoginCallback,
  toSetCloseLoginPageCallback,
} from "@/uni_modules/zzc-ali-one-click-login";

// 设置切换到短信登录的回调
toSetSwitchToSmsLoginCallback(() => {
  console.log("用户点击了切换到短信登录");
  quitLoginPage(); // 退出授权页
  // 跳转到短信登录页面
  uni.navigateTo({
    url: "/pages/acount/fastlogin",
  });
});

// 设置关闭授权页的回调
toSetCloseLoginPageCallback(() => {
  console.log("用户点击了关闭授权页");
  quitLoginPage(); // 退出授权页
});

// 配置授权页UI（可选）
setAuthConfig({
  // 登录按钮配置
  loginBtnText: "一键登录",
  loginBtnFontSize: 18,
  loginBtnFontColor: "#FFFFFF",
  // 更多UI配置...
});

// 执行一键登录
oneClickLogin({
  secretInfo: "your_secret_info", // SDK密钥（如果已调用 setAuthSDKInfo，这里可以不传）
  totalTime: 10000, // 超时时间（毫秒），可选，默认 10000
  success: (res) => {
    console.log("登录成功:");
    console.log("手机号:", res.phoneNumber);
    console.log("运营商:", res.carrierType);
    console.log("Token:", res.token);
    console.log("是否新用户:", res.isNewUser);
  },
  fail: (err) => {
    console.log("登录失败:", err.errMsg);
    console.log("错误码:", err.errCode);
  },
  complete: (res) => {
    console.log("登录完成");
  },
});

4. 在Vue组件中使用

<template>
  <view class="login-container">
    <button @click="handleOneClickLogin" :disabled="!isAvailable || isLoading">
      {{ isLoading ? "登录中..." : "一键登录" }}
    </button>
  </view>
</template>

<script setup>
import { ref, onMounted } from "vue";
import {
  oneClickLogin,
  checkOneClickLoginAvailable,
  setAuthConfig,
  quitLoginPage,
  toSetSwitchToSmsLoginCallback,
} from "@/uni_modules/zzc-ali-one-click-login";

const isAvailable = ref(false);
const isLoading = ref(false);

onMounted(async () => {
  // 检查一键登录是否可用
  try {
    isAvailable.value = await checkOneClickLoginAvailable({
      secretInfo: "your_secret_info",
    });
  } catch (error) {
    console.error("检查一键登录可用性失败:", error);
    isAvailable.value = false;
  }

  // 设置切换到短信登录的回调
  toSetSwitchToSmsLoginCallback(() => {
    quitLoginPage();
    uni.navigateTo({
      url: "/pages/acount/fastlogin",
    });
  });
});

const handleOneClickLogin = () => {
  isLoading.value = true;
  oneClickLogin({
    secretInfo: "your_secret_info",
    success: (res) => {
      uni.showToast({
        title: `登录成功: ${res.phoneNumber}`,
        icon: "success",
      });
      // 处理登录成功逻辑
    },
    fail: (err) => {
      uni.showToast({
        title: err.errMsg,
        icon: "error",
      });
    },
    complete: () => {
      isLoading.value = false;
    },
  });
};
</script>

API文档

setAuthSDKInfo(secretInfo)

设置SDK密钥信息。建议在应用启动时调用，这样后续调用 oneClickLogin 时就不需要每次都传入 secretInfo。

参数：

• secretInfo (string, 必填): 从阿里云控制台获取的SDK密钥

使用示例：

import { setAuthSDKInfo } from "@/uni_modules/zzc-ali-one-click-login";

setAuthSDKInfo("your_secret_info");

checkOneClickLoginAvailable(options)

检查一键登录是否可用。

参数：

• options.secretInfo (string, 必填): SDK密钥

返回值：

• Promise<boolean>: 是否可用

使用示例：

import { checkOneClickLoginAvailable } from "@/uni_modules/zzc-ali-one-click-login";

const isAvailable = await checkOneClickLoginAvailable({
  secretInfo: "your_secret_info",
});

oneClickLogin(options)

执行一键登录。

参数：

• options.secretInfo (string, 必填): SDK密钥（如果已调用 setAuthSDKInfo，这里可以不传，但建议传入以确保一致性）
• options.totalTime (number, 可选): 超时时间（毫秒），默认 10000
• options.success (function, 可选): 成功回调
• options.fail (function, 可选): 失败回调
• options.complete (function, 可选): 完成回调

成功回调参数：

• res.phoneNumber (string): 手机号码
• res.carrierType (string): 运营商类型 (CMCC: 移动, CUCC: 联通, CTCC: 电信)
• res.token (string): 取号Token
• res.isNewUser (boolean): 是否为新用户

使用示例：

import { oneClickLogin } from "@/uni_modules/zzc-ali-one-click-login";

oneClickLogin({
  secretInfo: "your_secret_info",
  totalTime: 10000,
  success: (res) => {
    console.log("登录成功:", res.phoneNumber);
  },
  fail: (err) => {
    console.log("登录失败:", err.errMsg);
  },
});

setAuthConfig(config)

设置授权页UI配置。支持配置登录按钮、手机号显示、协议栏、自定义组件等。

参数：

• config (object): UI配置对象，支持以下配置项：

登录按钮配置：

• loginBtnText (string): 登录按钮文本
• loginBtnFontSize (number): 登录按钮字体大小
• loginBtnFontColor (string): 登录按钮字体颜色
• loginBtnWidth (number): 登录按钮宽度
• loginBtnHeight (number): 登录按钮高度
• loginBtnBackGroundColor (string): 登录按钮背景色
• loginBtnDisableBackGroundColor (string): 登录按钮未选中状态背景色
• loginBtnBorder (object): 登录按钮边框配置
• loginBtnBorderWidth (number): 登录按钮选中状态边框宽度
• loginBtnBorderColor (string): 登录按钮选中状态边框颜色
• 更多配置项请参考阿里云一键登录SDK文档

手机号显示配置：

• numberFontSize (number): 手机号字体大小
• numberFontColor (string): 手机号字体颜色
• numberHeight (number): 手机号栏高度
• numberMagin (object): 手机号偏移

协议栏配置：

• privacyFontSize (number): 协议字体大小
• privacyFontColor (string): 协议字体颜色
• privacyMargin (object): 协议栏偏移
• privacySpanOneText (string): 第一个自定义协议文本
• privacySpanOneUrl (string): 第一个自定义协议网址
• privacySpanOneFontSize (number): 第一个自定义协议字体大小
• privacySpanOneFontColor (string): 第一个自定义协议字体颜色
• 更多协议配置项请参考阿里云一键登录SDK文档

自定义组件：

• loginPageComponent (ComponentBuilder): 授权页自定义组件（通过 @Builder 定义）
• clauseComponent (ComponentBuilder): 协议详情页自定义组件（通过 @Builder 定义）

使用示例：

import { setAuthConfig } from "@/uni_modules/zzc-ali-one-click-login";

setAuthConfig({
  loginBtnText: "一键登录",
  loginBtnFontSize: 18,
  loginBtnFontColor: "#FFFFFF",
  loginBtnBackGroundColor: "#007AFF",
  numberFontSize: 24,
  numberFontColor: "#333333",
  privacyFontSize: 14,
  privacyFontColor: "#666666",
  // 更多配置...
});

quitLoginPage()

退出授权页界面。通常在用户点击"切换到短信登录"或"关闭"按钮时调用。

使用示例：

import { quitLoginPage } from "@/uni_modules/zzc-ali-one-click-login";

quitLoginPage();

toSetSwitchToSmsLoginCallback(callback)

设置切换到短信登录的回调函数。当用户在授权页点击"切换登录方式"按钮时，会触发此回调。

参数：

• callback (function): 回调函数

使用示例：

import {
  toSetSwitchToSmsLoginCallback,
  quitLoginPage,
} from "@/uni_modules/zzc-ali-one-click-login";

toSetSwitchToSmsLoginCallback(() => {
  console.log("用户点击了切换到短信登录");
  quitLoginPage(); // 退出授权页
  // 跳转到短信登录页面
  uni.navigateTo({
    url: "/pages/acount/fastlogin",
  });
});

toSetCloseLoginPageCallback(callback)

设置关闭授权页的回调函数。当用户在授权页点击关闭按钮时，会触发此回调。

参数：

• callback (function): 回调函数

使用示例：

import {
  toSetCloseLoginPageCallback,
  quitLoginPage,
} from "@/uni_modules/zzc-ali-one-click-login";

toSetCloseLoginPageCallback(() => {
  console.log("用户点击了关闭授权页");
  quitLoginPage(); // 退出授权页
});

getCurrentCarrierName()

获取当前运营商名称。

返回值：

• Promise<string>: 运营商名称（如："中国移动"、"中国联通"、"中国电信"）

使用示例：

import { getCurrentCarrierName } from "@/uni_modules/zzc-ali-one-click-login";

const carrierName = await getCurrentCarrierName();
console.log("运营商:", carrierName);

getBundleSignature()

获取应用包签名信息。

返回值：

• Promise<string>: 返回应用签名字符串

使用示例：

import { getBundleSignature } from "@/uni_modules/zzc-ali-one-click-login";

getBundleSignature()
  .then((signature) => {
    console.log("应用签名:", signature);
  })
  .catch((error) => {
    console.error("获取签名失败:", error);
  });

checkEnvAvailable(authType)

检查环境可用性。

参数：

• authType (number): 认证类型，通常为 2

使用示例：

import { checkEnvAvailable } from "@/uni_modules/zzc-ali-one-click-login";

checkEnvAvailable(2);

错误码说明

自定义授权页组件

插件支持自定义授权页和协议详情页组件。自定义组件通过 @Builder 定义在 utssdk/app-harmony/builder.ets 文件中。

自定义登录页组件

在 builder.ets 中定义 loginComponent：

@Builder
export function loginComponent(): void {
  Column() {
    // Logo
    Image($r('app.media.mytel_app_launcher'))
      .width('86vp')
      .height('86vp')
      .margin({ top: 200 })
      .borderRadius(16)

    // 切换到短信登录按钮
    Text('切换登录方式')
      .width('100%')
      .height('40vp')
      .margin({ top: 260 })
      .textAlign(TextAlign.Center)
      .fontColor(Color.Gray)
      .fontSize('15fp')
      .onClick(() => {
        // 点击切换到短信登录时，调用外部回调函数
        if (switchToSmsLoginCallback !== null) {
          switchToSmsLoginCallback();
        }
      })

    // 关闭按钮
    Image($r('app.media.icon_closed'))
      .width('24vp')
      .height('24vp')
      .margin({ top: '100vp', left: '20vp' })
      .onClick(() => {
        if (closeLoginPageCallback !== null) {
          closeLoginPageCallback();
        }
      })
  }
  .width('100%')
  .height('100%')
}

自定义协议详情页组件

在 builder.ets 中定义 clauseComponent：

@Builder
export function clauseComponent(): void {
  Image($r('app.media.icon_closed'))
    .width('24vp')
    .height('24vp')
    .margin({ top: '8vp', left: '20vp' })
    .onClick(() => {
      router.back();
    })
}

完整使用示例

// App.vue
import { setAuthSDKInfo } from "@/uni_modules/zzc-ali-one-click-login";
import config from "@/config";

onLaunch(() => {
  // 初始化SDK密钥
  setAuthSDKInfo(config.ALI_AUTH_SDK_KEY_HARMONY);
});

// pages/login/index.vue
import {
  oneClickLogin,
  checkOneClickLoginAvailable,
  setAuthConfig,
  quitLoginPage,
  toSetSwitchToSmsLoginCallback,
  toSetCloseLoginPageCallback,
} from "@/uni_modules/zzc-ali-one-click-login";

// 在页面加载时检查可用性
onLoad(async () => {
  const isAvailable = await checkOneClickLoginAvailable({
    secretInfo: config.ALI_AUTH_SDK_KEY_HARMONY,
  });

  if (isAvailable) {
    // 设置回调
    toSetSwitchToSmsLoginCallback(() => {
      quitLoginPage();
      uni.navigateTo({ url: "/pages/acount/fastlogin" });
    });

    toSetCloseLoginPageCallback(() => {
      quitLoginPage();
    });

    // 配置UI
    setAuthConfig({
      loginBtnText: "一键登录",
      loginBtnFontSize: 18,
      // 更多配置...
    });

    // 执行一键登录
    oneClickLogin({
      secretInfo: config.ALI_AUTH_SDK_KEY_HARMONY,
      success: (res) => {
        console.log("登录成功:", res.phoneNumber);
        // 处理登录成功逻辑
      },
      fail: (err) => {
        console.log("登录失败:", err.errMsg);
        // 显示短信登录界面
      },
    });
  } else {
    // 显示短信登录界面
  }
});

注意事项

1. SDK密钥配置：

   • 使用前需要在阿里云控制台创建应用并获取SDK密钥（secretInfo）
   • 建议在应用启动时调用 setAuthSDKInfo 设置密钥
   • 也可以在每次调用 oneClickLogin 时传入 secretInfo

2. 环境检查：

   • 建议在使用前先调用 checkOneClickLoginAvailable 检查可用性
   • 一键登录需要开启蜂窝数据流量
   • 需要手机系统给予应用蜂窝数据权限

3. UI配置：

   • 可以通过 setAuthConfig 自定义授权页UI
   • 支持自定义登录页和协议详情页组件（通过 builder.ets）
   • 自定义组件需要符合 ArkTS 的 @Builder 语法

4. 回调设置：

   • 建议在调用 oneClickLogin 之前设置切换到短信登录和关闭授权页的回调
   • 回调函数中记得调用 quitLoginPage() 退出授权页

5. 错误处理：

   • 用户取消登录是正常情况，不应作为错误处理
   • 建议在 fail 回调中根据错误码进行相应处理

参考文档

• uni-app x UTS插件开发文档
• 阿里云一键登录文档
• UTS 语法
• UTS API插件
• UTS uni-app兼容模式组件
• UTS 标准模式组件
• Hello UTS