---
nav:
  title: 组件
  order: 2
group:
  title: 基础组件
  order: 1
title: Login
order: 1
category: pro
---

# Login2 Component

## Overview

`Login2` 提供邮箱、手机号、验证码、密码、多种 OAuth 方式以及访客登录的统一登录体验。组件完全受控于配置项，支持多步骤流程、浏览器自动填充优化、密码强度校验以及“记住我 / 忘记密码”等常见能力。

## Props

| Prop                     | Type                                            | Description                              | Default |
| ------------------------ | ----------------------------------------------- | ---------------------------------------- | ------- |
| `config`                 | `Login2Config`                                  | 登录配置对象，决定登录方式、UI、附加能力 | —       |
| `visible`                | `boolean`                                       | 是否展示组件                             | `true`  |
| `onClose`                | `() => void`                                    | 关闭弹层回调                             | —       |
| `className`              | `string`                                        | 自定义类名                               | —       |
| `style`                  | `React.CSSProperties`                           | 自定义样式                               | —       |
| `onLogin`                | `(originResult, method, data, channel) => void` | 登录成功回调                             | —       |
| `onOAuthLogin`           | `(provider, channel) => void`                   | OAuth 登录完成回调                       | —       |
| `onSendVerificationCode` | `(account, type, channel) => void`              | 发送验证码回调                           | —       |
| `onForgotPassword`       | `(account, channel) => void`                    | 忘记密码流程回调                         | —       |
| `onSwitchToRegister`     | `() => void`                                    | 切换到注册页回调                         | —       |
| `onError`                | `(error, method) => void`                       | 统一错误回调                             | —       |

### `Login2Config`

```ts
interface Login2Config {
  loginMethods: LoginMethodItem[]; // 登录方式配置数组
  ui?: UIConfig; // UI 定制（主题色、文案、密码规则等）
  oauth?: OAuthConfig; // 第三方登录配置
  legalTerms?: LegalTermsConfig; // 法律条款配置
  channel?: string; // 渠道标识
  emailLinkVerification?: {
    // 邮件链接重置密码配置
    enabled: boolean;
    code: string;
  };
}
```

`loginMethods` 中可混合邮箱、手机号、OAuth 与访客登录方式。对于邮箱/手机号可通过 `verificationMethods` 配置密码 / 验证码登录模式，`stepByStep` 控制分步骤体验。

### 密码规则（`config.ui?.passwordRules`）

`Login2` 与 `Register2` 共用 `usePasswordValidationRules` 钩子，可在 `config.ui.passwordRules` 中声明：

```ts
passwordRules?: {
  minLength?: number;             // 最小长度
  requireUppercase?: boolean;     // 是否需要大写字母
  requireLowercase?: boolean;     // 是否需要小写字母
  requireNumber?: boolean;        // 是否需要数字
  requireSpecialCharacters?: boolean; // 是否需要特殊字符
}
```

当未提供规则时组件默认要求最少 6 位并自动生成验证提示。文案会从 `locales` 中读取对应的 `pisell-set-password-*` key，可根据需求自定义多语言。

## Behaviour Highlights

- **多模式登录**：支持密码、验证码、分步骤邮箱/手机登录；可配置默认方式与切换逻辑。
- **OAuth 复用**：通过 `OAuthButtonGroup` 统一渲染 Google / Facebook / Apple / 访客等按钮，并保留“上次登录方式”提示。
- **自动填充优化**：多处使用隐藏 `username` 字段、动态 `name` 属性等技巧，规避浏览器自动填充错位问题。
- **密码校验**：`usePasswordValidationRules` 钩子抽象密码校验逻辑，与忘记密码、注册组件共享。
- **错误呈现**：验证码输入错误使用内联样式提示，避免依赖 `message.error` 导致的体验抖动。

## Usage Example

```
import Login2, { Login2Config } from '@pisell/private-materials/pro/Login2.0';

const config: Login2Config = {
  loginMethods: [
    {
      type: 'email',
      verificationMethods: ['password', 'verification_code'],
      stepByStep: true,
    },
    {
      type: 'phone',
      verificationMethods: ['verification_code'],
    },
    { type: 'google' },
    { type: 'facebook' },
    { type: 'guest' },
  ],
  ui: {
    passwordRules: {
      minLength: 8,
      requireNumber: true,
    },
  },
};

export default function LoginExample() {
  return (
    <Login2
      config={config}
      onLogin={(result, method, data) => {
        console.log('login success', method, data, result);
      }}
      onSwitchToRegister={() => {
        console.log('switch to register');
      }}
    />
  );
}
```

## Related Utilities

- `usePasswordValidationRules`：在登录、注册、忘记密码等场景下复用密码校验规则。
- `OAuthButtonGroup`：抽象第三方登录按钮组，统一尺寸、间距与“上次登录”标识。

## Best Practices

1. **配置驱动**：尽量通过 `config.loginMethods` 管理*login*方式，在 UI 中避免硬编码。
2. **密码强度**：建议结合 `config.ui.passwordRules` 与提示文案，让密码策略显式可见。
3. **表单触发**：使用组件内提供的 `Enter` 键提交和显式按钮，避免 `onFinish` 自动触发带来的误提交。
4. **错误处理**：通过 `onError` 收口异常，或结合埋点上报登录失败原因。
