鸿蒙 Account Kit：使用自定义按钮登录（四）
当标准华为账号登录按钮无法满足UI设计需求时，可以使用自定义按钮，通过调用API实现华为账号登录。
一、自定义按钮登录
应用应遵照【华为账号登录】按钮规范在登录页面嵌入自定义华为账号登录按钮，使用自定义按钮触发调用华为账号登录API获取Authorization Code，通过服务端交互获取用户的UnionID、OpenID完成用户登录；或者与应用账号完成绑定，绑定后用于登录或者验证。
适用场景
当标准“华为账号登录”按钮无法满足UI设计需求时，可以使用自定义按钮方案。
二、支持版本
| 设备类型 | 支持版本 |
|---|---|
| Phone | 支持 |
| Tablet | 支持 |
| PC/2in1 | 支持 |
| Wearable | 5.1.0(18)开始支持 |
| TV | 5.1.1(19)开始支持 |
三、业务流程
| 阶段 | 说明 |
|---|---|
| 展示自定义按钮调用登录API | 用户点击自定义登录按钮，应用调用华为账号登录API，请求授权信息。华为账号未登录时拉起登录页，已登录时直接返回Authorization Code |
| 用户关联应用账号 | 服务端通过Authorization Code获取Access Token，再获取UnionID，完成用户关联和登录 |
安全性
通过Authorization Code凭证获取用户信息可以有效避免黑客通过数据遍历、身份伪造、重放攻击等手段导致的安全风险。
四、开发前提
在进行代码开发前，请确保已完成：
| 配置项 | 说明 |
|---|---|
| 配置签名和指纹 | 参考配置签名和指纹 |
| 配置Client ID | 参考配置Client ID |
注意：此场景无需申请账号权限。
五、相关接口
| 接口 | 描述 |
|---|---|
createLoginWithHuaweiIDRequest() | 创建账号登录请求。forceLogin参数控制用户未登录华为账号时是否强制拉起登录界面 |
constructor(context) | 创建登录请求Controller |
executeRequest(request) | 通过Promise方式执行登录操作 |
注意：上述接口需在页面或自定义组件生命周期内调用。
六、客户端开发
6.1 导入模块
import { authentication } from '@kit.AccountKit'; import { hilog } from '@kit.PerformanceAnalysisKit'; import { util } from '@kit.ArkTS'; import { BusinessError } from '@kit.BasicServicesKit';6.2 错误码枚举
export enum ErrorCode { ERROR_CODE_LOGIN_OUT = 1001502001, // 账号未登录 ERROR_CODE_NETWORK_ERROR = 1001502005, // 网络错误 ERROR_CODE_INTERNAL_ERROR = 1001502009, // 内部错误 ERROR_CODE_USER_CANCEL = 1001502012, // 用户取消授权 ERROR_CODE_SYSTEM_SERVICE = 12300001, // 系统服务异常 ERROR_CODE_REQUEST_REFUSE = 1001500002 // 重复请求 }6.3 创建登录请求并执行
// 创建登录请求，并设置参数 const loginRequest = new authentication.HuaweiIDProvider() .createLoginWithHuaweiIDRequest(); // 用户是否需要登录授权，该值为true且用户未登录或未授权时，会拉起用户登录或授权页面 loginRequest.forceLogin = true; // 用于防跨站点请求伪造 loginRequest.state = util.generateRandomUUID(); // 执行登录请求 try { const controller = new authentication.AuthenticationController( this.getUIContext().getHostContext() ); controller.executeRequest(loginRequest).then((response: authentication.LoginWithHuaweiIDResponse) => { const state = response.state; if (state && loginRequest.state !== state) { hilog.error(0x0000, 'testTag', `The state is different, response state: ${state}`); return; } hilog.info(0x0000, 'testTag', 'Succeeded in logging in.'); const code = response?.data?.authorizationCode; // 开发者处理code（传给服务端） }).catch((error: BusinessError) => { dealAllError(error); }); } catch (error) { dealAllError(error); }6.4 错误处理
function dealAllError(error: BusinessError): void { hilog.error(0x0000, 'testTag', `Failed to login. Code: ${error.code}, message: ${error.message}`); if (error.code === ErrorCode.ERROR_CODE_LOGIN_OUT) { // 用户未登录华为账号，请登录华为账号并重试或使用其他方式登录 } else if (error.code === ErrorCode.ERROR_CODE_NETWORK_ERROR) { // 网络异常，请检查当前网络状态并重试 } else if (error.code === ErrorCode.ERROR_CODE_INTERNAL_ERROR) { // 登录失败，请尝试使用其他方式登录 } else if (error.code === ErrorCode.ERROR_CODE_USER_CANCEL) { // 用户取消授权 } else if (error.code === ErrorCode.ERROR_CODE_SYSTEM_SERVICE) { // 系统服务异常，请稍后重试 } else if (error.code === ErrorCode.ERROR_CODE_REQUEST_REFUSE) { // 重复请求，应用无需处理 } else { // 应用登录失败，请尝试使用其他方式登录 } }七、服务端开发
7.1 获取Access Token
应用服务端使用Client ID、Client Secret、Authorization Code调用获取用户级凭证接口向华为账号服务器请求获取Access Token、Refresh Token。
7.2 获取UnionID
使用Access Token调用解析凭证接口获取用户的UnionID。
7.3 用户关联
应用通过查询获取的UnionID判断该用户是否已关联：
已关联：完成用户登录
未关联：创建新用户，绑定UnionID，完成用户登录
八、Token过期处理
8.1 Access Token过期处理
| 项目 | 说明 |
|---|---|
| 有效期 | 60分钟 |
| 处理方式 | 使用Refresh Token（有效期180天）通过刷新用户级凭证接口获取新的Access Token |
备注：当Access Token失效时，若应用不使用Refresh Token获取新的Access Token，账号的授权信息将会失效，导致使用Access Token的功能都会失败。
8.2 Access Token非正常失效场景
当Access Token非正常失效（如修改密码、退出账号、删除设备）时，应用可重新登录授权获取Authorization Code，向华为账号服务器请求获取新的Access Token。
8.3 Refresh Token过期处理
| 项目 | 说明 |
|---|---|
| 有效期 | 180天 |
| 处理方式 | 失效后，应用服务端需要通知客户端，重新调用授权接口，请求用户重新授权 |
九、三种登录方式对比
| 对比项 | 自定义按钮登录 | 华为账号登录按钮 | 华为账号一键登录 |
|---|---|---|---|
| UI定制 | 完全自定义 | 固定样式 | 固定样式 |
| 获取信息 | UnionID | UnionID | 手机号+UnionID |
| 开发者类型 | 企业+个人 | 企业+个人 | 仅企业 |
| 调用方式 | API调用 | 组件 | 组件+API |
| 适用场景 | UI定制需求 | 快速集成 | 需要手机号 |
业务流程
用户点击自定义登录按钮 ↓ 创建LoginWithHuaweiIDRequest ↓ 设置forceLogin=true，生成state ↓ 调用executeRequest执行登录 ↓ 获取Authorization Code ↓ 服务端用Authorization Code换取Access Token ↓ 用Access Token获取UnionID ↓ 根据UnionID关联/创建用户 ↓ 完成登录自定义按钮登录通过createLoginWithHuaweiIDRequest创建登录请求，设置forceLogin和state参数，调用executeRequest获取Authorization Code，服务端再用Code换取Access Token和UnionID，适用于需要完全自定义登录按钮UI的场景，支持企业开发者和个人开发者。