## 简介

气泡常用于解释功能、显示帮助文案等场景，以气泡浮层形式承载辅助或提示信息，也可承载如链接、操作按钮等功能信息；气泡类组件均为非阻碍式信息提示，不会打断用户当前操作。

## 示例

### 基础形态

```tsx
import React from 'react';
import { Balloon, Button } from '@alicloud/console-components';

const titleStyle = {
  fontSize: '12px',
  fontWeight: 500,
  lineHeight: '20px',
  marginBottom: '8px',
};
const but = (
  <Button
    id="topRight"
    style={{
      margin: '25px 0 25px 400px',
      background: '#E5E5E5',
    }}
  />
);
const baseWithTittle = {
  trigger: but,
  content: (
    <div style={{ width: '266px' }}>
      <div style={titleStyle}>文字提示</div>
      点击/鼠标移入元素，弹出气泡浮层，内容文案超出长度后允许自动换行。
    </div>
  ),
};

export default () => {
  return (
    <Balloon
      align="l"
      closable={false}
      trigger={baseWithTittle.trigger}
      triggerType="click"
    >
      {baseWithTittle.content}
    </Balloon>
  );
};

export const meta = {
  title: '带标题气泡',
  describe: '通过设置align属性设置气泡出现方向，气泡内容通过Children自定义。',
};

```

```tsx
import React from 'react';
import { Balloon, Button } from '@alicloud/console-components';

const but = (
  <Button
    id="topRight"
    style={{
      margin: '25px 0 25px 400px',
      background: '#E5E5E5',
    }}
  />
);
const baseWithPureText = {
  trigger: but,
  content: (
    <div style={{ width: '266px' }}>
      点击/鼠标移入元素，弹出气泡浮层，内容文案超出长度后允许自动换行。
    </div>
  ),
};

export default () => {
  return (
    <Balloon
      align="l"
      closable={false}
      trigger={baseWithPureText.trigger}
      triggerType="click"
    >
      {baseWithPureText.content}
    </Balloon>
  );
};

export const meta = {
  title: '纯文本Tooltip',
  describe: '通过设置align属性设置气泡出现方向，气泡内容通过Children自定义。',
};

```

### 额外形态

```tsx
import React from 'react';
import { Balloon, Button } from '@alicloud/console-components';

const titleStyle = {
  fontSize: '12px',
  fontWeight: 500,
  lineHeight: '20px',
  marginBottom: '8px',
};
const centerStyle = {
  lineHeight: '20px',
  fontSize: '12px',
  fontWeight: 'normal',
};

const but = (
  <Button
    id="topRight"
    style={{
      margin: '25px 0 25px 400px',
      background: '#E5E5E5',
    }}
  />
);
const ExtraWithOperation = {
  trigger: but,
  content: (
    <div style={{ width: '266px' }}>
      <div style={titleStyle}>第一步标题</div>
      <span style={centerStyle}>
        点击/鼠标移入元素，弹出气泡浮层，内容文案超出长度后允许自动换行。点击/鼠标移入元素，弹出气泡浮层，内容文案超出长度后允许自动换行。
      </span>
      <div style={{ marginTop: 8 }}>
        <Button type="primary" size="small">
          下一步
        </Button>
      </div>
    </div>
  ),
};

export default () => {
  return (
    <Balloon align="l" trigger={ExtraWithOperation.trigger} triggerType="click">
      {ExtraWithOperation.content}
    </Balloon>
  );
};

export const meta = {
  title: '操作型',
  describe: '通过设置align属性设置气泡出现方向，气泡内容通过Children自定义。',
};

```

```tsx
import React from 'react';
import { Balloon, Button } from '@alicloud/console-components';

const titleStyle = {
  fontSize: '12px',
  fontWeight: 500,
  lineHeight: '20px',
  marginBottom: '8px',
};

const but = (
  <Button
    id="topRight"
    style={{
      margin: '25px 0 25px 400px',
      background: '#E5E5E5',
    }}
  />
);

const ExtraWithPicture = {
  trigger: but,
  content: (
    <div style={{ width: '266px' }}>
      <div style={titleStyle}>第一步标题</div>
      <div
        style={{
          backgroundColor: '#F6F6F6',
          width: 'auto',
          height: '106px',
          marginBottom: '8px',
        }}
      />
      <span>
        点击/鼠标移入元素，弹出气泡浮层，内容文案超出长度后允许自动换行。点击/鼠标移入元素，弹出气泡浮层，内容文案超出长度后允许自动换行。
      </span>
    </div>
  ),
};

export default () => {
  return (
    <Balloon triggerType="click" align="l" trigger={ExtraWithPicture.trigger}>
      {ExtraWithPicture.content}
    </Balloon>
  );
};

export const meta = {
  title: '图文型',
  describe: '通过设置align属性设置气泡出现方向，气泡内容通过Children自定义。',
};

```

```tsx
import React from 'react';
import { Balloon, Button } from '@alicloud/console-components';

const titleStyle = {
  fontSize: '12px',
  fontWeight: 500,
  lineHeight: '20px',
  marginBottom: '8px',
};
const centerStyle = {
  lineHeight: '20px',
  fontSize: '12px',
  fontWeight: 'normal',
};

const but = (
  <Button
    id="topRight"
    style={{
      margin: '25px 0 25px 400px',
      background: '#E5E5E5',
    }}
  />
);
const ExtraWithOperation = {
  trigger: but,
  content: (
    <div style={{ width: '266px' }}>
      <div style={titleStyle}>第一步标题</div>
      <span style={centerStyle}>
        点击/鼠标移入元素，弹出气泡浮层，内容文案超出长度后允许自动换行。点击/鼠标移入元素，弹出气泡浮层，内容文案超出长度后允许自动换行。
      </span>
      <div style={{ marginTop: 8 }}>
        <Button type="primary" size="small">
          下一步
        </Button>
      </div>
    </div>
  ),
};

export default () => {
  return (
    <Balloon align="l" trigger={ExtraWithOperation.trigger} triggerType="click">
      {ExtraWithOperation.content}
    </Balloon>
  );
};

export const meta = {
  title: '操作型',
  describe: '通过设置align属性设置气泡出现方向，气泡内容通过Children自定义。',
};

```

## API

### Balloon V2

| 参数               | 说明                                                                                                                                                                                                                                                | 类型                                                               | 默认值                                                   | 是否必填 | 支持版本 |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------- | -------- | -------- |
| v2                 | 开启 v2 版本                                                                                                                                                                                                                                        | true                                                               | true                                                       |          | 1.25     |
| children           | 浮层的内容                                                                                                                                                                                                                                          | ReactNode                                                          | -                                                        |          | -        |
| type               | 样式类型                                                                                                                                                                                                                                            | 'normal' | 'primary'                                              | 'normal'                                                 |          | 1.23     |
| title              | 标题                                                                                                                                                                                                                                                | ReactNode                                                          | -                                                        |          | 1.23     |
| visible            | 弹层当前显示的状态                                                                                                                                                                                                                                  | boolean                                                            | -                                                        |          | -        |
| defaultVisible     | 弹层默认显示的状态                                                                                                                                                                                                                                  | boolean                                                            | false                                                    |          | -        |
| onVisibleChange    | 弹层切换状态（显示或隐藏）时触发的事件<br/><br/>**签名**:Function(visible: Boolean, type: String) => void <br/>**参数**:<br/>*visible*: 弹层是否隐藏和显示<br/>*type*: 触发弹层显示或隐藏的来源，closeClick 表示由自带的关闭按钮触发；fromTrigger 表示由 trigger 的点击触发；docClick 表示由 document 的点击触发 | (visible: boolean, type: string) => void                           | func.noop                                                        |          | -        |
| arrowPointToCenter | \[v2] 箭头是否指向目标元素的中心                                                                                                                                                                                                                     | boolean                                                            | false                                                    |          | 1.25     |
| placementOffset    | \[v2] 弹层偏离触发元素的像素值                                                                                                                                                                                                                       | number                                                             | -                                                        |          | -        |
| closable           | 是否显示关闭按钮                                                                                                                                                                                                                                    | boolean                                                            | true                                                     |          | -        |
| align              | 弹出层位置                                                                                                                                                                                                                                          | AlignType                                                          | 'b'                                                      |          | -        |
| offset             | 弹层相对于 trigger 的定位的微调，接收数组 \[hoz, ver], 表示弹层在 left / top 上的增量，e.g. \[100, 100] 表示往右 (RTL 模式下是往左) 、下分布偏移 100px                                                                                                | Array\<number>                                                     | \[0, 0]                                                   |          | -        |
| trigger            | 触发元素                                                                                                                                                                                                                                            | ReactElement | string                                             | <span/>                                                  |          | -        |
| triggerType        | 触发行为，鼠标悬浮，鼠标点击 ('hover','click') 或者它们组成的数组，如 \['hover', 'click'], 强烈不建议使用'focus'，若弹窗内容有复杂交互请使用 click                                                                                                   | 'hover' | 'click' | 'focus' | ('hover' | 'click' | 'focus')\[] | 'hover'                                                  |          | -        |
| onClose            | 任何 visible 为 false 时会触发的事件                                                                                                                                                                                                                | () => void                                                         | func.noop                                                       |          | -        |
| autoAdjust         | \[v2] 是否进行自动位置调整，默认自动开启                                                                                                                                                                                                             | boolean                                                            | true                                                        |          | 1.25     |
| delay              | 弹层在触发以后的延时显示，单位毫秒 ms                                                                                                                                                                                                               | number                                                             | -                                                        |          | -        |
| afterClose         | 浮层关闭后触发的事件，如果有动画，则在动画结束后触发                                                                                                                                                                                                | () => void                                                         | func.noop	                                                        |          | -        |
| autoFocus          | 弹层出现后是否自动 focus 到内部第一个元素                                                                                                                                                                                                           | boolean                                                            | true                                                     |          | -        |
| safeNode           | 安全节点：对于 triggetType 为 click 的浮层，会在点击除了浮层外的其它区域时关闭浮层.safeNode 用于添加不触发关闭的节点，值可以是 dom 节点的 id 或者是节点的 dom 对象                                                                                  | string | ReactNode                                                | -                                                        |          | -        |
| safeId             | 用来指定 safeNode 节点的 id，和 safeNode 配合使用                                                                                                                                                                                                   | string                                                             | null                                                     |          | -        |
| animation          | 配置动画的播放方式，格式是 { in: '', out: '' }                                                               | string | false | Record<'in' | 'out', string>                  | { in: 'fadeIn', out: 'fadeOut', } |          | -        |
| cache              | 弹层的 dom 节点关闭时是否删除                                                                                                                                                                                                                       | boolean                                                            | false                                                    |          | -        |
| popupContainer     | 指定浮层渲染的父节点，可以为节点 id 的字符串，也可以返回节点的函数。                                                                                                                                                                                | PopupProps\['container']                                            | -                                                        |          | -        |
| popupStyle         | 弹层组件 style，透传给 Popup                                                                                                                                                                                                                        | CSSProperties                                                      | -                                                        |          | -        |
| popupClassName     | 弹层组件 className，透传给 Popup                                                                                                                                                                                                                    | string                                                             | -                                                        |          | -        |
| popupProps         | 弹层组件属性，透传给 Popup                                                                                                                                                                                                                          | ComponentPropsWithRef\<typeof Popup>                               | -                                                        |          | -        |
| followTrigger      | 是否跟随滚动                                                                                                                                                                                                                                            | boolean                                                            | -                                                        |          | -        |
| id                 | 弹层 id，传入值才会支持无障碍                                                                                                                                                                                                                       | string                                                             | -                                                        |          | -        |

### Balloon V1

| 参数            | 说明                                                                                                                                                                                                                                                | 类型                                                               | 默认值                                                   | 是否必填 | 支持版本 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------- | -------- | -------- |
| v2              | 开启 v2 版本                                                                                                                                                                                                                                        | false | undefined                                                 | -                                                        |          | 1.25     |
| children        | 浮层的内容                                                                                                                                                                                                                                          | ReactNode                                                          | -                                                        |          | -        |
| title           | 标题                                                                                                                                                                                                                                                | ReactNode                                                          | -                                                        |          | 1.23     |
| type            | 样式类型                                                                                                                                                                                                                                            | 'normal' | 'primary'                                              | 'normal'                                                 |          | 1.23     |
| visible         | 弹层当前显示的状态                                                                                                                                                                                                                                  | boolean                                                            | -                                                        |          | -        |
| defaultVisible  | 弹层默认显示的状态                                                                                                                                                                                                                                  | boolean                                                            | false                                                    |          | -        |
| onVisibleChange | 弹层在显示和隐藏触发的事件<br/><br/>**签名**:Function(visible: Boolean, type: String) => void<br/>**参数**:<br/>*visible*: 弹层是否隐藏和显示<br/>*type*: 触发弹层显示或隐藏的来源，closeClick 表示由自带的关闭按钮触发；fromTrigger 表示由 trigger 的点击触发；docClick 表示由 document 的点击触发 | (visible: boolean, type: string) => void                           | -                                                        |          | -        |
| closable        | 是否显示关闭按钮                                                                                                                                                                                                                                    | boolean                                                            | true                                                     |          | -        |
| align           | 弹出层位置                                                                                                                                                                                                                                          | AlignType                                                          | 'b'                                                      |          | -        |
| offset          | 弹层相对于 trigger 的定位的微调，接收数组 \[hoz, ver], 表示弹层在 left / top 上的增量，e.g. \[100, 100] 表示往右 (RTL 模式下是往左) 、下分布偏移 100px                                                                                                | Array\<number>                                                     | \[0, 0]                                                   |          | -        |
| trigger         | 触发元素                                                                                                                                                                                                                                            | ReactElement | string                                             | \<span/>                                                  |          | -        |
| triggerType     | 触发行为，鼠标悬浮，鼠标点击 ('hover','click') 或者它们组成的数组，如 \['hover', 'click'], 强烈不建议使用'focus'，若弹窗内容有复杂交互请使用 click                                                                                                   | 'hover' | 'click' | 'focus' | ('hover' | 'click' | 'focus')\[] | 'hover'                                                  |          | -        |
| onClose         | 任何 visible 为 false 时会触发的事件                                                                                                                                                                                                                | () => void                                                         | func.noop                                                        |          | -        |
| delay           | 弹层在触发以后的延时显示，单位毫秒 ms                                                                                                                                                                                                               | number                                                             | -                                                        |          | -        |
| afterClose      | 浮层关闭后触发的事件，如果有动画，则在动画结束后触发                                                                                                                                                                                                | () => void                                                         | -                                                        |          | -        |
| autoFocus       | 弹层出现后是否自动 focus 到内部第一个元素                                                                                                                                                                                                           | boolean                                                            | true                                                     |          | -        |
| safeNode        | 安全节点：对于 triggetType 为 click 的浮层，会在点击除了浮层外的其它区域时关闭浮层。safeNode 用于添加不触发关闭的节点，值可以是 dom 节点的 id 或者是节点的 dom 对象                                                                                  | string | ReactNode                                                | -                                                        |          | -        |
| safeId          | 用来指定 safeNode 节点的 id，和 safeNode 配合使用                                                                                                                                                                                                   | string                                                             | null                                                     |          | -        |
| animation       | 配置动画的播放方式，格式是 { in: '', out: '' }，常用的动画 class 请查看 Animate 组件文档<br/><br/>**签名**:<br/>**参数**:<br/>*in*: 进场动画<br/>*out*: 出场动画                                                                                  | string | false | Record<'in' | 'out', string>                  | { in: 'fadeIn', out: 'fadeOut', } |          | -        |
| cache           | 弹层的 dom 节点关闭时是否删除                                                                                                                                                                                                                       | boolean                                                            | false                                                    |          | -        |
| popupContainer  | 指定浮层渲染的父节点，可以为节点 id 的字符串，也可以返回节点的函数。                                                                                                                                                                                | PopupProps\['container']                                            | -                                                        |          | -        |
| popupStyle      | 弹层组件 style，透传给 Popup                                                                                                                                                                                                                        | CSSProperties                                                      | -                                                        |          | -        |
| popupClassName  | 弹层组件 className，透传给 Popup                                                                                                                                                                                                                    | string                                                             | -                                                        |          | -        |
| popupProps      | 弹层组件属性，透传给 Popup                                                                                                                                                                                                                          | ComponentPropsWithRef\<typeof Popup>                               | -                                                        |          | -        |
| followTrigger   | 跟随滚动                                                                                                                                                                                                                                            | boolean                                                            | -                                                        |          | -        |
| id              | 弹层 id, 传入值才会支持无障碍                                                                                                                                                                                                                       | string                                                             | -                                                        |          | -        |

### Balloon.Tooltip V2

| 参数               | 说明                                                                                                                                                                          | 类型                                                               | 默认值  | 是否必填 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------- | -------- |
| v2                 | 开启 v2                                                                                                                                                                       | true                                                               | -       |          |
| children           | tooltip 的内容                                                                                                                                                                | ReactNode                                                          | -       |          |
| align              | 弹出层位置                                                                                                                                                                    | AlignType                                                          | 'b'     |          |
| trigger            | 触发元素                                                                                                                                                                      | ReactElement | string                                             | <span/> |          |
| triggerType        | 触发行为，鼠标悬浮，鼠标点击 ('hover', 'click') 或者它们组成的数组，如 \['hover', 'click'], 强烈不建议使用'focus'，若有复杂交互，推荐使用 triggerType 为 click 的 Balloon 组件 | 'hover' | 'click' | 'focus' | ('hover' | 'click' | 'focus')\[] | 'hover' |          |
| popupStyle         | 弹层组件 style，透传给 Popup                                                                                                                                                  | CSSProperties                                                      | -       |          |
| popupClassName     | 弹层组件 className，透传给 Popup                                                                                                                                              | string                                                             | -       |          |
| popupProps         | 弹层组件属性，透传给 Popup                                                                                                                                                    | ComponentPropsWithRef\<typeof Popup>                               | -       |          |
| pure               | 是否 pure render                                                                                                                                                              | boolean                                                            | -       |          |
| popupContainer     | 指定浮层渲染的父节点，可以为节点 id 的字符串，也可以返回节点的函数。                                                                                                          | PopupProps\['container']                                            | -       |          |
| followTrigger      | 是否跟随滚动                                                                                                                                                                  | boolean                                                            | -       |          |
| id                 | 弹层 id, 传入值才会支持无障碍                                                                                                                                                 | string                                                             | -       |          |
| delay              | 弹层在触发以后的延时显示，单位为毫秒 ms	 | number                                                             | 150      |          |
| arrowPointToCenter | \[v2] 箭头是否指向目标元素的中心                                                                                                                                               | boolean                                                            | false   |          |

### Balloon.Tooltip V1

| 参数           | 说明                                                                                                                                                                          | 类型                                                               | 默认值  | 是否必填 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------- | -------- |
| v2             | 开启 v2                                                                                                                                                                       | true | undefined                                                 | -       |          |
| children       | tooltip 的内容                                                                                                                                                                | ReactNode                                                          | -       |          |
| align          | 弹出层位置                                                                                                                                                                    | AlignType                                                          | 'b'     |          |
| trigger        | 触发元素                                                                                                                                                                      | ReactElement | string                                             | <span/> |          |
| triggerType    | 触发行为，鼠标悬浮，鼠标点击 ('hover', 'click') 或者它们组成的数组，如 \['hover', 'click'], 强烈不建议使用'focus'，若有复杂交互，推荐使用 triggerType 为 click 的 Balloon 组件 | 'hover' | 'click' | 'focus' | ('hover' | 'click' | 'focus')\[] | 'hover' |          |
| popupStyle     | 弹层组件 style，透传给 Popup                                                                                                                                                  | CSSProperties                                                      | -       |          |
| popupClassName | 弹层组件 className，透传给 Popup                                                                                                                                              | string                                                             | -       |          |
| popupProps     | 弹层组件属性，透传给 Popup                                                                                                                                                    | ComponentPropsWithRef\<typeof Popup>                               | -       |          |
| pure           | 是否 pure render                                                                                                                                                              | boolean                                                            | -       |          |
| popupContainer | 指定浮层渲染的父节点，可以为节点 id 的字符串，也可以返回节点的函数。                                                                                                          | PopupProps\['container']                                            | -       |          |
| followTrigger  | 是否跟随滚动                                                                                                                                                                  | boolean                                                            | -       |          |
| id             | 弹层 id, 传入值才会支持无障碍                                                                                                                                                 | string                                                             | -       |          |
| delay          | 弹层在触发以后的延时显示，单位毫秒 ms	  | number                                                             | 150      |          |

## 无障碍键盘操作指南

| 按键  | 说明                                      |
| :---- | :---------------------------------------- |
| SPACE | 当`triggerType=‘click’`时，点击会弹出提示 |
| Enter | 当`triggerType=‘click’`时，点击会弹出提示 |