opencoredev/islandcn

项目介绍

islandcn 为任意 React 应用提供一个灵动岛（Dynamic Island）风格的 UI 组件，以 shadcn registry 条目的形式分发，而不是常规 npm 包。应用顶部的单个岛可以展示上传、计时、正在播放、配送预计到达、来电、录音等活动，每个活动都围绕应用自身的动作来组织 (1)。

项目分为三层：引擎（lib/island/）负责活动栈、四种呈现形态（idle、compact、split、expanded）、弹簧动画、长按、提醒和减弱动效；预设（components/islandcn/）提供上述活动各自单文件实现及共享内容套件；playground 用于组合岛、触发各动作、调节动画，并复制安装命令和代码 (3)。引擎仅依赖 React，站点与文档也在同一仓库内。

它适合已经使用 shadcn、希望直接获得一套动画化活动状态层、而不想自行实现表现和动效的 React 团队。

快速使用

主要安装方式是通过 shadcn CLI 拉取项目站点上的 registry 条目：

npx shadcn@latest add https://islandcn.dev/r/island-core.json

然后在应用根部挂载一次 Provider 和 Island，并可在其内部的任意组件中启动活动：

"use client";

import { Island, IslandProvider, useIsland } from "@/lib/island";

<IslandProvider>
  <Island placement="viewport" />
  <App />
</IslandProvider>;

const island = useIsland();
const upload = island.start({
  id: "upload",
  label: "Uploading report.pdf",
  compact: { leading: <CloudIcon />, trailing: <ProgressRing value={0.4} /> },
  expanded: { center: <span>report.pdf</span>, bottom: <Progress value={0.4} /> },
});
upload.update({ compact: { trailing: <ProgressRing value={0.8} /> } });
upload.end();

示例中的 CloudIcon、ProgressRing 和 Progress 需要来自你自己的图标与 UI 组件。想交互式体验预设并生成代码，可打开项目站点的 /playground 路由。

本地开发

仓库使用 pnpm：

pnpm install
pnpm dev           # http://localhost:3000
pnpm typecheck
pnpm build         # builds the registry into public/r, then the site

pnpm dev 下 /lab 会用内置序列回放全部过渡。用于拟合动画的逐帧录像未纳入仓库，因此 /compare 没有内容可展示，读取这些录像的测试会被跳过 (3)。修改前需阅读 AGENTS.md。

使用约束

• 组件面向能够消费 shadcn registry 条目的 React 应用；README 未说明最低 React 或 Next.js 版本。
• 核心通过托管在项目域名下的 registry URL 安装，安装过程需要能访问该站点。
• 视觉与动效模仿 Apple 灵动岛，但仓库不含 Apple 的任何素材，项目与 Apple 无关联；Dynamic Island 是 Apple 的商标。
• 项目以 MIT 许可证分发，版权归 2026 Leo (3)。

HotRepo 点评

该项目于 2026-11-13 进入 HotRepo 新项目榜记录，在 11:50 至 19:46 UTC 约八小时窗口内新增 115 个 Star 和 5 个 Fork。目前没有 GitHub 全语言日榜名次记录，因此这只是一次早期快照，不足以说明持续增长。技术上值得关注的是 shadcn registry 的分发方式：引擎被复制进使用方项目，而预设和 playground 降低了组合自定义岛屿的成本。动效录像缺失意味着仅凭仓库开发的贡献者只能看到不完整的开发面。