跳到正文
目录与搜索
⌘K

原语 / Animate UI

Pinned List · Animate UI

在置顶组与普通组之间滑动的列表,条目换组时其余条目自动让位。

安装

自有原语直接来自 @animate-ui/react,不依赖 Radix UI、Base UI 或 React Aria;装上包即可使用。

终端
bun add @animate-ui/react motion

用法

直接从 @animate-ui/react 的对应子路径引入,下面就是完整示例;样式由你的类名决定。

pinned-list.tsx
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—
childrenReact.ReactNode—
…propsHTMLMotionProps<'div'>—
asChildbooleanfalse
hidebooleanfalse
transitionTransition{ duration: 0.22, ease: [0.23, 1, 0.32, 1], layout: { type: 'spring', stiffness: 320, damping: 25, mass: 0.8 } }
…propsHTMLMotionProps<'p'>—
asChildbooleanfalse
idstring—
customTriggerbooleanfalse
transitionTransition{ type: 'spring', stiffness: 320, damping: 25, mass: 0.8 }
childrenReact.ReactNode—
…propsHTMLMotionProps<'div'>—
asChildbooleanfalse
…propsHTMLMotionProps<'button'>—

未列出的属性与上游 API 完全一致,可在 官方文档 查阅。

内容对应官方文档 2026-10-18 版本。