开发预览更新于 2026-05-10

Modal 弹窗

弹窗 —— 内置 portal、focus trap、滚动锁、ESC / 遮罩关闭、进出动画。

基础用法

v-model:open / open + onOpenChange 双向绑定。组件内部自动处理：portal 到 body、focus trap、body 滚动锁、Esc 关闭、遮罩关闭、进出 fade + scale 动画。

<script setup lang="ts">
import { ref } from 'vue';
import { CfButton, CfModal } from '@chufix-design/vue';

const open = ref(false);
</script>

<template>
<CfButton @click="open = true">打开 Modal</CfButton>
<CfModal v-model:open="open" title="确认操作">
  <p>这是一个最简弹窗。</p>
  <template #footer>
    <CfButton variant="ghost" @click="open = false">取消</CfButton>
    <CfButton @click="open = false">确定</CfButton>
  </template>
</CfModal>
</template>

import { useState } from 'react';
import { CfButton, CfModal } from '@chufix-design/react';

export default function Demo() {
const [open, setOpen] = useState(false);
return (
  <>
    <CfButton onClick={() => setOpen(true)}>打开 Modal</CfButton>
    <CfModal
      open={open}
      onOpenChange={setOpen}
      title="确认操作"
      footer={
        <>
          <CfButton variant="ghost" onClick={() => setOpen(false)}>取消</CfButton>
          <CfButton onClick={() => setOpen(false)}>确定</CfButton>
        </>
      }
    >
      <p>这是一个最简弹窗。</p>
    </CfModal>
  </>
);
}

尺寸

size 控制弹窗最大宽度。full 几乎铺满视口（仍保留外边距），适合表单较多的设置面板。

<CfModal v-model:open="open" size="sm">…</CfModal>
<CfModal v-model:open="open" size="md">…</CfModal>
<CfModal v-model:open="open" size="lg">…</CfModal>
<CfModal v-model:open="open" size="xl">…</CfModal>
<CfModal v-model:open="open" size="full">…</CfModal>

<CfModal open={open} onOpenChange={setOpen} size="sm">…</CfModal>
<CfModal open={open} onOpenChange={setOpen} size="md">…</CfModal>
…
<CfModal open={open} onOpenChange={setOpen} size="full">…</CfModal>

关闭行为

默认任何操作都能关闭：遮罩点击、Esc、右上角 ×。可以通过 closeOnOverlay / closeOnEsc / showClose 单独禁用。

<CfModal v-model:open="a" :close-on-overlay="false">
点遮罩不会关闭，只能用 Esc 或 footer 按钮。
</CfModal>

<CfModal v-model:open="b" :show-close="false">
没有右上角 ×。
</CfModal>

<CfModal open={a} onOpenChange={setA} closeOnOverlay={false}>…</CfModal>
<CfModal open={b} onOpenChange={setB} showClose={false}>…</CfModal>

API

Prop	类型	默认值	说明
`open`	`boolean`	`false`	受控开关
`size`	`'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'`	`'md'`	最大宽度档位
`title`	`string`	—	渲染到默认 header（可被 slot 覆盖）
`closeOnOverlay`	`boolean`	`true`	点遮罩是否关闭
`closeOnEsc`	`boolean`	`true`	Esc 是否关闭
`showClose`	`boolean`	`true`	右上角 × 按钮
`to`	`string \| Element`	`'body'`	Teleport / Portal 目标容器

插槽 / Children

Vue：header / 默认 / footer 三个具名插槽。
React：title 或 header props + children + footer props。