前言
Zag 和 PandaCSS 都是出自 chakra 团队之手，Zag 聚焦于处理组件的逻辑，而 PandaCSS 聚焦于通过 ts 来维护样式，将两者进行搭配会有怎么样的使用体验呢？这篇文章将继续以 vuesax 中 dialog 组件的样式作为参考，结合 Zag 和 PandaCSS 进行 vue3 版本的重构，实现一个超丝滑的对话窗组件。
如果你想学习有关 PandaCSS 和 Vue TSX 的前置知识，也可以参考以往的文章，前文回顾：
pandaCSS 介绍
先放一段官方介绍：
Panda 是一个样式引擎，可生成样式基元，以类型安全和可读的方式编写原子 CSS 和配方。 Panda 结合了 CSS-in-JS 的开发者体验和原子 CSS 的性能。它利用静态分析来扫描 JavaScript 和 TypeScript 文件中的 JSX 样式属性和函数调用，按需生成样式（也称为即时生成 JIT）
它的基础使用方式如下：
ts
<script setup lang="ts">
import { css } from "../styled-system/css";
</script>
<template>
<div :class="css({ fontSize: '5xl', fontWeight: 'bold' })">Hello 🐼!</div>
</template> 可以看到我们通过在 class 中使用函数 css 并传入一个样式对象作为参数，上面这段代码在 pandaCSS 解析后会生成如下样式，解析都是在构建的过程中执行的：
css
@layer utilities {
.fs_5xl {
font-size: var(--font-sizes-5xl);
}
.font_bold {
font-weight: var(--font-weights-bold);
}
}Zag 介绍
Zag 是一个与框架无关的工具包，用于在设计系统和 Web 应用程序中实现复杂、交互式且可访问的 UI 组件。借助 Zag，您可以在 React、Solid 和 Vue 中构建可访问的 UI 组件，而无需担心逻辑。
具体的使用方式在下面的实现过程中进行介绍，这里不展开太多。
组件实现
逻辑实现
通常如果我们要实现一个对话窗组件，它的核心逻辑就一个，那就是打开 和关闭 ，我们需要创建一个状态来管理对话框是否展示。这里我们直接使用 Zag 来实现对话框的逻辑，Zag 中有一个 Dialog 组件的实现，首先我们安装下依赖：
bash
npm install @zag-js/dialog @zag-js/vue
# or
yarn add @zag-js/dialog @zag-js/vue然后直接复制官方提供的 tsx 示例：
tsx
import * as dialog from "@zag-js/dialog"
import { normalizeProps, useMachine } from "@zag-js/vue"
import { computed, defineComponent, h, Fragment, Teleport } from "vue"
export default defineComponent({
name: "Dialog",
setup() {
const [state, send] = useMachine(dialog.machine({ id: "1" }))
const apiRef = computed(() =>
dialog.connect(state.value, send, normalizeProps),
)
return () => {
const api = apiRef.value
return (
<>
<button {...api.triggerProps}>
Open Dialog
</button>
{api.isOpen && (
<Teleport to="body">
<div {...api.backdropProps} />
<div {...api.containerProps}>
<div {...api.contentProps}>
<h2 {...api.titleProps}>Edit profile</h2>
<p {...api.descriptionProps}>
Make changes to your profile here. Click save when you are
done.
</p>
<button {...api.closeTriggerProps}>X</button>
<input placeholder="Enter name..." />
<button>Save Changes</button>
</div>
</div>
</Teleport>
)}
</>
)
}
},
})接下来我们分析一下这段代码做了什么事情，首先最直观的是创建了一个对话框组件的基本框架，在 chakra 团队的定义中，弹窗组件包含以下几个部分:
- 触发器 Trigger： 触发对话框的按钮
- 背景遮罩 Backdrop： 通常位于弹窗元素后面的暗色背景覆盖层。
- 容器 Container：对话框最外层的容器。
- 内容 Content：对话框内容的容器，用于放置对话框的内容。
而弹窗组件的内容中还包含以下几个部分：
- 标题 Title： 对话框的标题。
- 描述 Description： 支持标题的说明。
- 关闭按钮 Close： 用于关闭对话框的按钮。
ts
const [state, send] = useMachine(dialog.machine({ id: "1" }))dialog.machine({ id: "1" }) 为我们的对话框创建了一个基础状态机，其中的细节我们先不管，其中 machine 函数的参数除了 id 外，还有以下几个对话框的交互逻辑，这也就意味着我们使用 Zag 后这些功能就不需要自己去实现了：
ts
interface PublicContext extends DirectionProperty, CommonProperties, InteractOutsideHandlers {
/**
* 弹窗中元素的ID。用于组合使用。
*/
ids?: ElementIds;
/**
* 当弹窗打开时，是否将焦点限制在弹窗内部。
*/
trapFocus: boolean;
/**
* 当弹窗打开时，是否阻止后面内容滚动。
*/
preventScroll: boolean;
/**
* 是否阻止弹窗外部的指针交互，并隐藏其下方的所有内容。
*/
modal?: boolean;
/**
* 弹窗打开时接收焦点的元素。
*/
initialFocusEl?: MaybeElement | (() => MaybeElement);
/**
* 弹窗关闭时接收焦点的元素。
*/
finalFocusEl?: MaybeElement | (() => MaybeElement);
/**
* 弹窗打开前是否恢复焦点到打开前具有焦点的元素。
*/
restoreFocus?: boolean;
/**
* 弹窗打开或关闭时调用的回调函数。
*/
onOpenChange?: (details: OpenChangeDetails) => void;
/**
* 是否在单击弹窗外部时关闭弹窗。
*/
closeOnInteractOutside: boolean;
/**
* 是否在按下 Escape 键时关闭弹窗。
*/
closeOnEscapeKeyDown: boolean;
/**
* 当按下 Escape 键时调用的回调函数。
*/
onEscapeKeyDown?: (event: KeyboardEvent) => void;
/**
* 弹窗的人类可读标签，用于在没有弹窗标题的情况下显示。
*/
"aria-label"?: string;
/**
* 弹窗的角色。
* @default "dialog"
*/
role: "dialog" | "alertdialog";
/**
* 弹窗是否打开。
*/
open?: boolean;
}useMachine 函数会将我们传入的状态机转换为 当前的状态(State) 和一个向状态机 发送信号的函数(Send)
ts
const apiRef = computed(() =>
dialog.connect(state.value, send, normalizeProps),
)接下来我们使用 connect 函数将状态与事件进行连接，原理类似于当对话框关闭时，点击事件将触发状态变为 "a" ，而当对话框打开时，点击事件将触发状态变为 "b" 。所以可以将 connect 函数理解为建立事件与状态之间的映射关系。
normalizeProps 属性的作用是将组件的 props 转换为与各自框架兼容的格式。
通过调用 dialog.connect 方法，我们可以得到一个 api 对象，其中包含了这些属性：
ts
interface MachineApi<T extends PropTypes = PropTypes> {
/**
* 对话框是否打开
*/
isOpen: boolean;
/**
* 打开对话框的函数
*/
open(): void;
/**
* 关闭对话框的函数
*/
close(): void;
triggerProps: T["button"];
backdropProps: T["element"];
containerProps: T["element"];
contentProps: T["element"];
titleProps: T["element"];
descriptionProps: T["element"];
closeTriggerProps: T["button"];
}这里之所以使用了 computed 将函数进行包裹，是为了确保当上下文修改时，组件可以触发重新渲染，保证视图中的组件是最新的。接下来我们就可以将 apiRef 中所有的 props 使用展开符传递到对应的元素上：
tsx
<button {...api.triggerProps}> Open Dialog </button>Teleport 组件则可以将对话框直接挂载在 body 上，最终实现的效果如下图：
可以看到效果还非常简陋，仅仅只是展示了最基础的文本排版，但是功能相关的逻辑已经由 Zag 都实现了，因此接下来我们为对话框补充样式
样式实现
在 🖱️使用 Vue+pandaCSS+tsx 实现一个超精致的按钮组件 这篇文章中，我详细介绍了 pandaCSS 中配方（Recipes）的概念，它非常适合按钮这种存在比较多变体的组件。
而对于对话框来说，它通常没有很多的变体，且它的内部包含了很多子元素，因此我们可以使用 pandaCSS 中插槽配方（Slot Recipes），来实现对话框的样式。
官方对于插槽配方的介绍如下：
当你需要将样式变体应用于组件的多个部分时，插槽配方可以派上用场。虽然使用
cva或defineRecipe可能足以满足简单的情况，但插槽配方更适合更复杂的情况。插槽配方由以下属性组成：
slots：要设计样式的一组组件base：每个插槽的基本样式variants：每个插槽的不同视觉风格defaultVariants：组件的默认变体compoundVariants：每个插槽的复合变体组合和样式覆盖。
这里我实现的基础样式如下：
tsx
import { sva } from "@/styled-system/css";
const dialogRecipe = sva({
slots: [
"backdrop",
"container",
"content",
"title",
"description",
"close",
"closeIcon",
"footer",
],
base: {
backdrop: {
position: "fixed",
left: "0",
top: "0",
zIndex: "1",
width: "full",
height: "full",
py: "80px",
display: "flex",
alignItems: "center",
justifyContent: "center",
bgColor: "rgba(0,0,0,0.6)",
},
container: {
bgColor: "white",
minWidth: "400px",
maxWidth: "800px",
margin: "auto",
color: "gray.700",
transition: "all 0.25s ease",
position: "relative",
borderRadius: "20px",
boxShadow: "0px 5px 30px 0px rgba(0, 0, 0, 0.2)",
zIndex: 2,
},
title: {
py: "16px",
fontWeight: "bold",
fontSize: "xl",
color: "inherit",
},
content: {
px: "24px",
py: "8px",
width: "100%",
position: "relative",
borderRadius: "inherit",
},
footer: {
pt: "24px",
pb: "8px",
display: "flex",
justifyContent: "end",
gap: "8px",
},
close: {
position: "absolute",
top: "-6px",
right: "-6px",
display: "flex",
alignItems: "center",
justifyContent: "center",
borderRadius: "12px",
boxShadow: "0px 5px 20px 0px rgba(0, 0, 0, 0.1)",
transition: " all 0.25s ease",
width: "36px",
height: "36px",
zIndex: "200",
border: "none",
padding: "4px",
_hover: {
boxShadow: "0px 0px 4px 0px rgba(0, 0, 0, 0.1)",
transform: "translate(-2px, 2px)",
},
},
},
});
export default dialogRecipe;在 sva 函数中，我定义了对话框组件的所有子元素， 子元素的定义就是按照 Zag 中的规范进行区分的，并且为每一个子元素定义了样式。接下来在组件中使用配方：
ts
import { SystemStyleObject } from "@pandacss/dev";
import * as dialog from "@zag-js/dialog";
import { normalizeProps, useMachine } from "@zag-js/vue";
import { computed, defineComponent, Teleport, Transition, PropType } from "vue";
import dialogRecipe from "./recipe";
import Button from "../button";
import Close from "../icon/close";
import useId from "@/src/hooks/useId";
import { css } from "@/styled-system/css";
export default defineComponent({
name: "ZDialog",
props: {
title: {
type: String,
},
content: {
type: String,
},
preventScroll: {
type: Boolean as PropType<dialog.Context["preventScroll"]>,
default: true,
},
closeOnInteractOutside: {
type: Boolean as PropType<dialog.Context["closeOnEscapeKeyDown"]>,
default: true,
},
},
setup(props) {
const { id } = useId("dialog");
const classes = dialogRecipe();
const [state, send] = useMachine(dialog.machine({ id }));
const apiRef = computed(() =>
dialog.connect(state.value, send, normalizeProps),
);
return () => {
const api = apiRef.value;
return (
<>
<Button {...api.triggerProps}>Open Dialog</Button>
<Teleport to="body">
{api.isOpen && (
<div {...api.backdropProps} class={classes.backdrop}>
<div {...api.containerProps} class={classes.container}>
<div {...api.contentProps} class={classes.content}>
<Button
{...api.closeTriggerProps}
icon
variant="outline"
css={dialogRecipe.raw().close as SystemStyleObject}
>
<Close />
</Button>
<header {...api.titleProps} class={classes.title}>
Edit profile
</header>
<div {...api.descriptionProps}>
Make changes to your profile here. Click save when you
are done.
</div>
<footer class={classes.footer}>
<Button variant="outline" onClick={apiRef.value.close}>
Close
</Button>
<Button variant="primary">Save</Button>
</footer>
</div>
</div>
</div>
)}
</Teleport>
</>
);
};
},
});这里的 dialogRecipe() 执行后会返回配方中定义的所有元素的样式所生成的 className，如下图：
我们将 className 传入对应的元素中，按钮组件则替换为我们自己实现的按钮组件，加上样式后的效果如下图：
基本的样式都有了，但是对话框出现的效果似乎太僵硬了，接下来我们为对话框组件增加一个动画效果。
增加动画效果
在 vue 中增加动画效果，通常会使用 Transition 组件和 css 动画，首先，我们先定义一个弹窗弹出时的动画效果，在 pandaCSS 中，添加动画效果可以在配置文件的 keyframe 字段增加新的配置：
ts
import { defineConfig } from "@pandacss/dev"
export default defineConfig({
// Whether to use css reset
preflight: true,
// "presets": ["@pandacss/preset-base", "@pandacss/preset-panda"],
// Where to look for your css declarations
include: ["./src/**/*.{js,jsx,ts,tsx,vue}"],
// Files to exclude
exclude: [],
// Useful for theme customization
theme: {
extend: {
keyframes: {
rebound: {
'0%': { transform: 'scale(0.8)' },
'40%': { transform: 'scale(1.08)' },
'80%':{transform: 'scale(0.98)'},
'100%':{transform: 'scale(1)'}
}
}
}
},
// The output directory for your css system
outdir: "styled-system",
jsxFramework: 'vue'
})这里我在 keyframes 字段中增加了 rebound 属性定义了一个动画效果，接下来我们回到组件中，为组件包裹一个 Transition 组件：
tsx
<>
<Button {...api.triggerProps}>Open Dialog</Button>
<Teleport to="body">
<Transition
leaveToClass={css({
opacity: 0,
"& > [data-part='container']": {
transform: "scale(0.7)",
boxShadow: "0px 0px 0px 0px rgba(0, 0, 0, 0.3)",
},
})}
enterActiveClass={css({
opacity: 1,
transition: "all 0.25s ease",
"& > [data-part='container']": {
animation: "rebound 0.4s",
},
})}
leaveActiveClass={css({
transition: "all 0.15s ease",
"& > [data-part='container']": {
transition: "all 0.15s ease",
},
})}
>
{api.isOpen && (
<div {...api.backdropProps} class={classes.backdrop}>
<div {...api.containerProps} class={classes.container}>
<div {...api.contentProps} class={classes.content}>
<Button
{...api.closeTriggerProps}
icon
variant="outline"
css={dialogRecipe.raw().close as SystemStyleObject}
>
<Close />
</Button>
<header {...api.titleProps} class={classes.title}>
Edit profile
</header>
<div {...api.descriptionProps}>
Make changes to your profile here. Click save when you
are done.
</div>
<footer class={classes.footer}>
<Button variant="outline" onClick={apiRef.value.close}>
Close
</Button>
<Button variant="primary">Save</Button>
</footer>
</div>
</div>
</div>
)}
</Transition>
</Teleport>
</>在 Transition 组件中我们传递了三个 class 来定义动画不同阶段的效果，三个 class 都通过 pandaCSS 中的 css 函数生成的，这里我使用了一个选择器 & > [data-part='container'] ，&:代表父级选择器，而 [data-part='container'] 则是 Zag 为我们生成的组件参数中用于区别不同子元素的属性，dialog 对应的所有属性如下：
css
[data-part="trigger"] {
/* styles for the trigger element */
/* 触发器元素的样式 */
}
[data-part="backdrop"] {
/* styles for the backdrop element */
/* 背景元素的样式 */
}
[data-part="container"] {
/* styles for the container element */
/* 容器元素的样式 */
}
[data-part="content"] {
/* styles for the content element */
/* content 元素的样式 */
}
[data-part="title"] {
/* styles for the title element */
/* title 元素的样式 */
}
[data-part="description"] {
/* styles for the description element */
/* description 元素的样式 */
}
[data-part="close-trigger"] {
/* styles for the close trigger element */
/* 关闭触发器元素的样式 */
}添加上动画后的效果如下图，录制的 gif 图的帧数比较低，实际上动画效果会更加Q弹：
组件的基本效果实现了，接下来将提升一下组件的通用性和拓展性，为组件新增一些属性和插槽。
组件控制
首先我们提供一个 props 用于外部控制弹窗的打开和关闭，这里使用了 modelValue：
tsx
export default defineComponent({
name: "ZDialog",
props: {
modelValue: {
type: Boolean,
default: false,
},
// ...
},
},
emits: ["update:modelValue", "open", "close"],
setup(props, { slots, emit }) {
const { id } = useId("dialog");
const classes = dialogRecipe({ blur: props.backdropBlur });
const [state, send] = useMachine(
dialog.machine({
id,
//...
onOpenChange({ open }) {
emit("update:modelValue", open);
emit(open ? "open" : "close");
},
}),
);
const apiRef = computed(() =>
dialog.connect(state.value, send, normalizeProps),
);
watch(
() => props.modelValue,
() => {
apiRef.value[props.modelValue ? "open" : "close"]();
},
);
// ...render
},
});我们通过监听 props.modelValue 的改变去触发状态机的事件，当状态机的状态更改时又通过 emit 去更新 props.modelValue，这样就实现了一个双向绑定，我们可以通过 v-model 去控制对话框的展开或关闭，也可以在弹窗打开或者关闭的时候通过 emit 传递自定义的方法。
组件变体
对话框组件虽然相比组件来说变体比较少，但是也是有一些特殊样式的，例如对话框的大小，弹出时背景是否模糊等等，我们先在对话框组件的配方中新增变体 variants 属性：
tsx
import { RecipeVariantProps, sva } from "@/styled-system/css";
const dialogRecipe = sva({
slots: [
"backdrop",
"container",
"content",
"title",
"description",
"close",
"closeIcon",
"footer",
],
// ...base
variants: {
size: {
xs: { container: { width: "240px" } },
sm: { container: { width: "320px" } },
md: { container: { width: "480px" } },
lg: { container: { width: "600px" } },
xl: { container: { width: "960px" } },
},
blur: {
false: {},
true: {
backdrop: {
backdropFilter: "saturate(180%) blur(5px)",
},
},
},
},
});
export default dialogRecipe;
export type DialogVariants = Exclude<
RecipeVariantProps<typeof dialogRecipe>,
undefined
>;这里我们定义了 size 和 blur 变体，与上一篇文章中提到的按钮组件的变体不同，插槽配方在定义变体样式时需要嵌套多一层对象，指定样式是作用在哪一个插槽上的，这里的 size 作用在 container 元素上，blur 则作用在 backdrop 元素上。
最后我们将 porps 传入配方中：
tsx
const classesRef = computed(() =>
dialogRecipe({ blur: props.blur, size: props.size }),
);这里将 dialogRecip 也使用了 computed 进行包裹，目的也是为了实现在配方的中传入的变体属性更新时，组件可以实时重新渲染，效果如下图所示：
最后组件还需要补充 title，content，cancelText，confirmText 几个 props，用于定义对话框文本内容，showConfirm，showCancel，showClose，showFooter，用于判断对话框中的元素是否显示。这里代码比较多就不单独列出来了。感兴趣可以直接看源码： github.com/oil-oil/zax... , 后续的更新也都在这个仓库中, 快去点个 star 🌟
总结
Zag 和 PandaCSS 是 chakra 团队基于已有的组件库项目痛点抽象出的一种跨框架实践，基于我现在的使用，我认为 Zag 非常适合企业内部团队想要实现一个自己的组件库，但是实现组件库除了考虑业务和样式外，还有各种包括使用规范，可访问性的问题需要考虑，使用 Zag 除了大部分通用组件的逻辑不需要自己实现，还保障了组件库的基本规范不会差，并且它与样式没有任何绑定，不论你们团队的组件样式如何定制都没问题。
PandaCSS 则是提供了一种目前我认为在 TS 中使用最爽的样式实现方案，但是现在还处于早期阶段，文档不算很完善，各种 API 的功能在重叠的时候不知道有什么他们有什么区别，而且运行时的限制太多了，可能会为了组件开发的体验牺牲了组件使用的体验。
我将持续的使用 Zag 和 PandaCSS 去实现更多组件，探一探他们的实现组件时的边界在哪里，后续还有更多关于关于组件实现的文章，如果文章对你有帮助在收藏的同时也可以为我点个赞👍，respect！