原语 / Animate UI
Pinned List · Animate UI
在置顶组与普通组之间滑动的列表,条目换组时其余条目自动让位。
安装
自有原语直接来自 @animate-ui/react,不依赖 Radix UI、Base UI 或 React Aria;装上包即可使用。
bun add @animate-ui/react motion用法
直接从 @animate-ui/react 的对应子路径引入,下面就是完整示例;样式由你的类名决定。
import * as React from 'react';
import {
PinnedList,
PinnedListItem,
PinnedListItems,
PinnedListLabel,
PinnedListPinned,
PinnedListTrigger,
PinnedListUnpinned,
} from '@animate-ui/react/primitives/pinned-list';
export function Folders() {
const [items, setItems] = React.useState(ITEMS);
const toggle = (id: string) =>
setItems((prev) =>
prev.map((i) => (i.id === id ? { ...i, pinned: !i.pinned } : i)),
);
const pinned = items.filter((i) => i.pinned);
const unpinned = items.filter((i) => !i.pinned);
return (
<PinnedList onPinnedChange={toggle}>
<PinnedListPinned>
<PinnedListLabel hide={pinned.length === 0}>Pinned</PinnedListLabel>
<PinnedListItems>
{pinned.map((item) => (
<PinnedListItem key={item.id} id={item.id} customTrigger>
{item.name}
<PinnedListTrigger aria-label={`Unpin ${item.name}`}>
…
</PinnedListTrigger>
</PinnedListItem>
))}
</PinnedListItems>
</PinnedListPinned>
<PinnedListUnpinned>
<PinnedListLabel hide={unpinned.length === 0}>All</PinnedListLabel>
<PinnedListItems>
{unpinned.map((item) => (
<PinnedListItem key={item.id} id={item.id} customTrigger>
{item.name}
<PinnedListTrigger aria-label={`Pin ${item.name}`}>
…
</PinnedListTrigger>
</PinnedListItem>
))}
</PinnedListItems>
</PinnedListUnpinned>
</PinnedList>
);
}动效
- 条目以 stiffness 320 / damping 25 / mass 0.8 的共享布局动画滑向新位置,轻微过冲,移动时位于其他条目之上。
- 其余条目同步让位;减少动效下直接重排。
所有时长都会乘以 AnimateUIProvider 的 tempo,并遵守系统的减少动效设置。
API
动效相关的 transition 与 exitTransition 是 Animate UI 唯一新增的属性;其余 props 见上表。
| 属性 | 类型 | 默认值 |
|---|---|---|
| onPinnedChange | (id: string) => void | — |
| children | React.ReactNode | — |
| …props | HTMLMotionProps<'div'> | — |
| asChild | boolean | false |
| hide | boolean | false |
| transition | Transition | { duration: 0.22, ease: [0.23, 1, 0.32, 1], layout: { type: 'spring', stiffness: 320, damping: 25, mass: 0.8 } } |
| …props | HTMLMotionProps<'p'> | — |
| asChild | boolean | false |
| id | string | — |
| customTrigger | boolean | false |
| transition | Transition | { type: 'spring', stiffness: 320, damping: 25, mass: 0.8 } |
| children | React.ReactNode | — |
| …props | HTMLMotionProps<'div'> | — |
| asChild | boolean | false |
| …props | HTMLMotionProps<'button'> | — |
未列出的属性与上游 API 完全一致,可在 官方文档 查阅。
内容对应官方文档 2026-10-18 版本。