Dialog 对话框

对话框。

使用场景#

需要用户处理事务，又不希望跳转页面以致打断工作流程时，可以使用 Dialog 在当前页面正中打开一个浮层，承载相应的操作。

另外当需要一个简洁的确认框询问用户时，可以使用 Dialog.confirm() 等快捷调用方法。

特性介绍#

对话框定位#

通过 placement 可以指定对话框在容器内的位置。对话框提供以下 9 种定位方式，默认为 <Dialog placement="center" />

container

top-left

top

top-right

left

center

right

bottom-left

bottom

bottom-right

在 placement 的基础上，可以通过 offset={[offsetX, offsetY]} 设置对话框的偏移量。

组件内部结构#

组件提供了一个简单的对话框结构，分为 header / main / footer 三个部分，每个部分都支持在上层进行覆盖。

<Dialog title={title}>
 {children}
</Dialog>

// 对应的 DOM 结构如下

<div className="rex-dialog">
  <div className="rex-dialog-header">{title}</div>
  <div className="rex-dialog-body">{children}</div>
  <div className="rex-dialog-footer">
    <button>取消</button>
    <button>确认</button>
  </div>
</div>

代码示例#

基本对话框#

作为普通组件使用时，对话框是否展示由 visible 进行控制。

noInline

const hippoIntroduction =
  '盒马是阿里巴巴集团旗下，以数据和技术驱动的新零售平台。盒马希望为消费者打造社区化的一站式新零售体验中心，用科技和人情味带给人们“鲜美生活”。';

function Basic() {
  const [state, setState] = useState({ visible: false, width: 400 });

  return (
    <div>
      <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap' }}>
        <Button onClick={() => setState({ visible: true, width: 300 })}>打开小号对话框(300px)</Button>
        <Button onClick={() => setState({ visible: true, width: 450 })}>打开中号对话框(450px)</Button>
        <Button onClick={() => setState({ visible: true, width: 800 })}>打开大号对话框(800px)</Button>
      </div>
      <Dialog
        title="盒马"
        visible={state.visible}
        onRequestClose={() => setState({ visible: false, width: state.width })}
        style={{ width: state.width }}
      >
        {hippoIntroduction}
      </Dialog>
    </div>
  );
}

render(<Basic />)

const hippoIntroduction =
  '盒马是阿里巴巴集团旗下，以数据和技术驱动的新零售平台。盒马希望为消费者打造社区化的一站式新零售体验中心，用科技和人情味带给人们“鲜美生活”。';

function Basic() {
  const [state, setState] = useState({ visible: false, width: 400 });

  return (
    <div>
      <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap' }}>
        <Button onClick={() => setState({ visible: true, width: 300 })}>打开小号对话框(300px)</Button>
        <Button onClick={() => setState({ visible: true, width: 450 })}>打开中号对话框(450px)</Button>
        <Button onClick={() => setState({ visible: true, width: 800 })}>打开大号对话框(800px)</Button>
      </div>
      <Dialog
        title="盒马"
        visible={state.visible}
        onRequestClose={() => setState({ visible: false, width: state.width })}
        style={{ width: state.width }}
      >
        {hippoIntroduction}
      </Dialog>
    </div>
  );
}

render(<Basic />)

非模态对话框#

对于一些非必选/不紧急的对话框，我们建议设置 canCloseByEsc={true} 和 canCloseByOutSideClick={true} 来使用非模态对话框。

noInline

const hippoIntroduction =
  '盒马是阿里巴巴集团旗下，以数据和技术驱动的新零售平台。盒马希望为消费者打造社区化的一站式新零售体验中心，用科技和人情味带给人们“鲜美生活”。';

function NonModal() {
  const [state, setState] = useState({ visible: false });

  return (
    <div>
      <Button onClick={() => setState({ visible: true })}>打开非模态对话框</Button>
      <Dialog
        title="盒马"
        visible={state.visible}
        onRequestClose={() => setState({ visible: false })}
        canCloseByEsc
        canCloseByIcon
        canCloseByOutSideClick
      >
        {hippoIntroduction}
      </Dialog>
    </div>
  );
}

render(<NonModal />)

const hippoIntroduction =
  '盒马是阿里巴巴集团旗下，以数据和技术驱动的新零售平台。盒马希望为消费者打造社区化的一站式新零售体验中心，用科技和人情味带给人们“鲜美生活”。';

function NonModal() {
  const [state, setState] = useState({ visible: false });

  return (
    <div>
      <Button onClick={() => setState({ visible: true })}>打开非模态对话框</Button>
      <Dialog
        title="盒马"
        visible={state.visible}
        onRequestClose={() => setState({ visible: false })}
        canCloseByEsc
        canCloseByIcon
        canCloseByOutSideClick
      >
        {hippoIntroduction}
      </Dialog>
    </div>
  );
}

render(<NonModal />)

快捷调用#

inline

function QuickTools() {
  return (
    <div style={{ display: 'flex', gap: 16 }}>
      <Button
        onClick={() => {
          Dialog.show({
            title: '确认删除',
            content: '你确认要删除这些内容吗？',
            canCloseByEsc: true,
            onOk() {
              console.log('继续删除');
            },
            onCancel() {
              console.log('取消');
            },
          });
        }}
      >
        打开对话框 show
      </Button>
      <Button
        onClick={() => {
          Dialog.alert({
            title: '删除失败',
            content: '关闭文件后再重新尝试删除文件',
          }).then((alertResult) => {
            console.log('alertResult:', alertResult);
          });
        }}
      >
        打开 alert 对话框
      </Button>
      <Button
        onClick={() => {
          Dialog.confirm({
            title: '确认删除',
            content: '是否要删除《小作坊的自我修养》这个文件夹么？该操作无法撤销.',
          }).then((confirmResult) => {
            console.log('confirmResult', confirmResult);
          });
        }}
      >
        打开 confirm 对话框
      </Button>
      <Button onClick={Dialog.closeAll}>关闭所有对话框</Button>
    </div>
  );
}

function QuickTools() {
  return (
    <div style={{ display: 'flex', gap: 16 }}>
      <Button
        onClick={() => {
          Dialog.show({
            title: '确认删除',
            content: '你确认要删除这些内容吗？',
            canCloseByEsc: true,
            onOk() {
              console.log('继续删除');
            },
            onCancel() {
              console.log('取消');
            },
          });
        }}
      >
        打开对话框 show
      </Button>
      <Button
        onClick={() => {
          Dialog.alert({
            title: '删除失败',
            content: '关闭文件后再重新尝试删除文件',
          }).then((alertResult) => {
            console.log('alertResult:', alertResult);
          });
        }}
      >
        打开 alert 对话框
      </Button>
      <Button
        onClick={() => {
          Dialog.confirm({
            title: '确认删除',
            content: '是否要删除《小作坊的自我修养》这个文件夹么？该操作无法撤销.',
          }).then((confirmResult) => {
            console.log('confirmResult', confirmResult);
          });
        }}
      >
        打开 confirm 对话框
      </Button>
      <Button onClick={Dialog.closeAll}>关闭所有对话框</Button>
    </div>
  );
}

tip

Dialog.alert(...) 与 Dialog.confirm(...) 会返回一个 Promise，该 Promise 会 resolve 一个布尔值，表示用户进行了「确认」或「取消」.

嵌套对话框#

noInline

const alibabaIntroduction =
  '阿里巴巴集团创立于1999年，是一家提供电子商务在线交易平台的中国公司，实行位于杭州与北京的双总部制度。\n' +
  '服务范围包括B2B贸易、网上零售、购物搜索引擎、第三方支付和云计算服务。';

const hippoIntroduction =
  '盒马是阿里巴巴集团旗下，以数据和技术驱动的新零售平台。盒马希望为消费者打造社区化的一站式新零售体验中心，用科技和人情味带给人们“鲜美生活”。';

function Nested() {
  const [visible, setVisible] = useState(false);
  const [innerVisible, setInnerVisible] = useState(false);

  return (
    <div>
      <Button onClick={() => setVisible(true)}>打开对话框</Button>
      <Dialog title="阿里巴巴" visible={visible} onRequestClose={() => setVisible(false)} canCloseByEsc>
        <p>{alibabaIntroduction}</p>
        <Button onClick={() => setInnerVisible(true)}>打开嵌套对话框</Button>

        <Dialog
          title="嵌套对话框-盒马"
          visible={innerVisible}
          onRequestClose={() => setInnerVisible(false)}
          canCloseByEsc
          style={{ width: 720 }}
        >
          <p style={{ marginBottom: 0 }}>{hippoIntroduction}</p>
        </Dialog>
      </Dialog>
    </div>
  );
}

render(<Nested />)

const alibabaIntroduction =
  '阿里巴巴集团创立于1999年，是一家提供电子商务在线交易平台的中国公司，实行位于杭州与北京的双总部制度。\n' +
  '服务范围包括B2B贸易、网上零售、购物搜索引擎、第三方支付和云计算服务。';

const hippoIntroduction =
  '盒马是阿里巴巴集团旗下，以数据和技术驱动的新零售平台。盒马希望为消费者打造社区化的一站式新零售体验中心，用科技和人情味带给人们“鲜美生活”。';

function Nested() {
  const [visible, setVisible] = useState(false);
  const [innerVisible, setInnerVisible] = useState(false);

  return (
    <div>
      <Button onClick={() => setVisible(true)}>打开对话框</Button>
      <Dialog title="阿里巴巴" visible={visible} onRequestClose={() => setVisible(false)} canCloseByEsc>
        <p>{alibabaIntroduction}</p>
        <Button onClick={() => setInnerVisible(true)}>打开嵌套对话框</Button>

        <Dialog
          title="嵌套对话框-盒马"
          visible={innerVisible}
          onRequestClose={() => setInnerVisible(false)}
          canCloseByEsc
          style={{ width: 720 }}
        >
          <p style={{ marginBottom: 0 }}>{hippoIntroduction}</p>
        </Dialog>
      </Dialog>
    </div>
  );
}

render(<Nested />)

动态尺寸与方位#

通过 placement 来控制对话框的方位，组件内部内置了 ResizeObserver，当对话框内的尺寸发生变化时，组件会自动调整位置。

noInline

// 以下变量从其他模块中引入：
//  fromEvent, getNextPlacement, getDialogOffsetFromPlacement

const standards = ['#4E7EF5', '#42ABFC', '#32CEE6', '#46CF9F', '#FFC147', '#FF7161', '#6782B5', '#FA82BA', '#977FF5'];

const colors = [0, 3, 4, 6, 5, 8, 2, 1, 7].map((index) => standards[index]);

function DynamicSizeAndPlacements() {
  const [visible, setVisible] = useState(false);
  const [width, setWidth] = useState(600);
  const [lineCount, setLineCount] = useState(3);
  const [placement, setPlacement] = useState('center');

  useEffect(() => {
    const subscription = fromEvent(document, 'keypress').subscribe((event) => {
      if (event.key.toLowerCase() === 'c') {
        setPlacement(getNextPlacement);
      }
    });

    return () => {
      subscription.unsubscribe();
    };
  }, []);

  return (
    <div>
      <Button onClick={() => setVisible(true)}>打开对话框</Button>
      <Dialog
        title="对话框标题"
        visible={visible}
        onRequestClose={() => setVisible(false)}
        style={{ width, transition: 'inset 200ms cubic-bezier(0.51, 1, 0.68, 1)' }}
        placement={placement}
        offset={getDialogOffsetFromPlacement(placement)}
      >
        <div>
          <p style={{ marginTop: 0 }}>
            当前方位 <code>placement={placement}</code>
          </p>
        </div>
        <div style={{ display: 'flex', gap: 16, overflow: 'auto' }}>
          <Button onClick={() => setWidth(width + 50)}>增加宽度</Button>
          <Button onClick={() => setWidth(width - 50)}>减小宽度</Button>
          <Button onClick={() => setLineCount(lineCount + 1)}>增加高度</Button>
          <Button onClick={() => setLineCount(lineCount - 1)}>减小高度</Button>
          <Button onClick={() => setPlacement(getNextPlacement)}>
            改变方位(快捷键<code>C</code>)
          </Button>
        </div>
        <br />
        {_.range(lineCount).map((i) => (
          <p key={i} style={{ margin: 0, padding: 8, background: colors[i % colors.length] }}>
            line {i + 1}
          </p>
        ))}
      </Dialog>
    </div>
  );
}

render(<DynamicSizeAndPlacements />)

// 以下变量从其他模块中引入：
//  fromEvent, getNextPlacement, getDialogOffsetFromPlacement

const standards = ['#4E7EF5', '#42ABFC', '#32CEE6', '#46CF9F', '#FFC147', '#FF7161', '#6782B5', '#FA82BA', '#977FF5'];

const colors = [0, 3, 4, 6, 5, 8, 2, 1, 7].map((index) => standards[index]);

function DynamicSizeAndPlacements() {
  const [visible, setVisible] = useState(false);
  const [width, setWidth] = useState(600);
  const [lineCount, setLineCount] = useState(3);
  const [placement, setPlacement] = useState('center');

  useEffect(() => {
    const subscription = fromEvent(document, 'keypress').subscribe((event) => {
      if (event.key.toLowerCase() === 'c') {
        setPlacement(getNextPlacement);
      }
    });

    return () => {
      subscription.unsubscribe();
    };
  }, []);

  return (
    <div>
      <Button onClick={() => setVisible(true)}>打开对话框</Button>
      <Dialog
        title="对话框标题"
        visible={visible}
        onRequestClose={() => setVisible(false)}
        style={{ width, transition: 'inset 200ms cubic-bezier(0.51, 1, 0.68, 1)' }}
        placement={placement}
        offset={getDialogOffsetFromPlacement(placement)}
      >
        <div>
          <p style={{ marginTop: 0 }}>
            当前方位 <code>placement={placement}</code>
          </p>
        </div>
        <div style={{ display: 'flex', gap: 16, overflow: 'auto' }}>
          <Button onClick={() => setWidth(width + 50)}>增加宽度</Button>
          <Button onClick={() => setWidth(width - 50)}>减小宽度</Button>
          <Button onClick={() => setLineCount(lineCount + 1)}>增加高度</Button>
          <Button onClick={() => setLineCount(lineCount - 1)}>减小高度</Button>
          <Button onClick={() => setPlacement(getNextPlacement)}>
            改变方位(快捷键<code>C</code>)
          </Button>
        </div>
        <br />
        {_.range(lineCount).map((i) => (
          <p key={i} style={{ margin: 0, padding: 8, background: colors[i % colors.length] }}>
            line {i + 1}
          </p>
        ))}
      </Dialog>
    </div>
  );
}

render(<DynamicSizeAndPlacements />)

极简样式#

设置 minimal={true} 后，对话框只会保留最基本的定位功能与背景色，其余内容完全由上层进行控制。此时 title 和 footer 属性无效。

noInline

const hippoIntroduction =
  '盒马是阿里巴巴集团旗下，以数据和技术驱动的新零售平台。盒马希望为消费者打造社区化的一站式新零售体验中心，用科技和人情味带给人们“鲜美生活”。';

function Minimal() {
  const [visible, setVisible] = useState(false);

  return (
    <div>
      <Button onClick={() => setVisible(true)}>打开对话框</Button>
      <Dialog
        visible={visible}
        onRequestClose={() => setVisible(false)}
        style={{ width: 300, height: 250, padding: '1rem 2rem 1rem 1rem' }}
        canCloseByOutSideClick
        canCloseByEsc
        canCloseByIcon
        renderChildren={({ ref }) => (
          <Dialog.Panel ref={ref } style={{ width: '80%', padding: 16 }}>
            {hippoIntroduction}
          </Dialog.Panel>
        )}
      />
    </div>
  );
}

render(<Minimal />)

const hippoIntroduction =
  '盒马是阿里巴巴集团旗下，以数据和技术驱动的新零售平台。盒马希望为消费者打造社区化的一站式新零售体验中心，用科技和人情味带给人们“鲜美生活”。';

function Minimal() {
  const [visible, setVisible] = useState(false);

  return (
    <div>
      <Button onClick={() => setVisible(true)}>打开对话框</Button>
      <Dialog
        visible={visible}
        onRequestClose={() => setVisible(false)}
        style={{ width: 300, height: 250, padding: '1rem 2rem 1rem 1rem' }}
        canCloseByOutSideClick
        canCloseByEsc
        canCloseByIcon
        renderChildren={({ ref }) => (
          <Dialog.Panel ref={ref } style={{ width: '80%', padding: 16 }}>
            {hippoIntroduction}
          </Dialog.Panel>
        )}
      />
    </div>
  );
}

render(<Minimal />)

API#

快捷调用#

`Dialog.show(config): string`#

根据 config 打开一个快捷对话框，config.title 作为对话框的标题， config.content 作为对话框的内容，其他属性详见 Dialog Props

返回一个字符串 key 表示该对话框实例，调用 Dialog.close(key) 可以主动关闭该对话框。

`Dialog.confirm(config)`#

根据 config 打开一个快捷「确认」对话框，返回 Promise<boolean> 表示用户进行了「确认」或「取消」。

`Dialog.alert(config)`#

根据 config 打开一个快捷「警告」对话框，返回 Promise<true> 表示用户进行了「确认」。

`Dialog.close(key)`#

关闭一个对话框。

`Dialog.closeAll()`#

关闭所有对话框。

Dialog.useDialog()#

当你需要使用 Context 时，可以通过 Dialog.useDialog 创建一个 contextHolder 插入子节点中。通过 hooks 创建的临时 Dialog 将会得到 contextHolder 所在位置的所有上下文。创建的 dialog 对象拥有与 Dialog.method 相同的创建通知方法。

const [dialog, contextHolder] = Dialog.useDialog();

React.useEffect(() => {
  dialog.confirm({
    // ...
  });
}, []);

return <div>{contextHolder}</div>;

Dialog Props#

字段	描述
style	`CSSProperties`
className	`string`
visible	`boolean`
onRequestClose	`(reason: any) => void`
content	`ReactNode`
renderChildren	`(pass: { ref: Ref<Element>; }) => ReactNode` 使用 render prop 的形式指定弹层内容，用于精确控制 DOM 结构
title	`ReactNode`
footer	`null \| React.ReactElement \| Action[]`
onOk	`() => void`
onCancel	`() => void`
placement	`PositionPlacement` = center
offset	`PositionOffset`
canCloseByIcon	`boolean` = false 是否显示对话框关闭图标
浮层交互
canCloseByEsc	`boolean` = false 是否支持 esc 按键关闭弹层
canCloseByOutSideClick	`boolean` = false 点击弹层外部区域是否关闭弹层（注意背景层也被认为是外部）
浮层生命周期
beforeOpen	`(state?: any) => Promise<IOverlayAnimationProps>` 浮层即将被打开时的回调
onOpen	`() => void` 浮层打开时的回调
afterOpen	`() => void` 浮层打开时的回调
beforeClose	`() => IOverlayAnimationProps` 浮层即将被关闭时的回调
onClose	`() => void` 浮层关闭时的回调
afterClose	`() => void` 浮层关闭后的回调
背景层
hasBackdrop	`boolean` = true 是否展示背景层
backdropStyle	`CSSProperties`
backdropClassName	`string`
浮层动画
animationDuration	`string` = 200ms 动画持续时间（注意该 prop 会作为 CSS 变量的值，使用时要带上单位，例如 `'500ms'`)
animation	`false \| { in: string \| Keyframes; out: string \| Keyframes; }` 弹层的出现和消失的动画，可以用 Overlay.animations.{name} 来引用弹层组件内置的动画效果
浮层容器
usePortal	`boolean` 是否使用 portal 来渲染弹层内容
portalContainer	`HTMLElement \| "DOCUMENT_BODY"` 渲染组件的容器
disableScroll	`boolean \| "force"` = true 是否禁用容器的滚动

使用场景#

特性介绍#

对话框定位#

组件内部结构#

代码示例#

基本对话框#

非模态对话框#

快捷调用#

tip

嵌套对话框#

动态尺寸与方位#

极简样式#

API#

快捷调用#

Dialog.show(config): string#

Dialog.confirm(config)#

Dialog.alert(config)#

Dialog.close(key)#

Dialog.closeAll()#

Dialog.useDialog()#

Dialog Props#

`Dialog.show(config): string`#

`Dialog.confirm(config)`#

`Dialog.alert(config)`#

`Dialog.close(key)`#

`Dialog.closeAll()`#