shadcn-svelte Spinner 组件指南安装、用法与加载状态实战【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte导读Spinner是 shadcn-svelte 组件库中用于展示加载状态的指示器indicator组件本质是一个带旋转动画的图标可嵌入按钮、徽章、输入框、空状态卡片等任意场景。本文以 spinner.md 为骨架结合仓库内的组件源码与注册表配置完整讲解 Spinner 的安装方式、基础用法、自定义方法以及尺寸、颜色、按钮、徽章、Input Group、Empty、Item 等七类实战示例帮助你在一分钟内为 Svelte 应用接入统一的加载状态视觉语言。什么是 SpinnerSpinner 在 shadcn-svelte 中的定位是一个加载状态指示器用于告知用户内容正在处理中。它不承载业务逻辑只负责渲染一个持续旋转的图标并通过默认属性保证无障碍可读性。从源码看Spinner组件的实现非常轻量核心代码如下spinner.sveltescript langts import { cn } from $lib/utils.js; import type { SVGAttributes } from svelte/elements; let { class: className, role status, aria-label: ariaLabel Loading, ...restProps }: SVGAttributesSVGSVGElement $props(); /script !-- 实际渲染一个带动画的内联 SVG --组件将全部剩余属性透传给底层 SVG因此你可以像使用普通 SVG 元素一样传递class、style、aria-*等属性。几个值得注意的默认值与设计意图属性默认值说明rolestatus告知屏幕阅读器这是一个状态提示区域内容更新时会被播报aria-labelLoading无障碍替代文本无文字场景下读屏软件可朗读class默认注入size-4 animate-spin默认 1rem 尺寸 Tailwind 旋转动画图标Loader2Lucide等图标库的 Loader/Spinner 系列由图标库解析层按设计系统选择需要说明的是仓库文档站内的 spinner.svelte 是文档站源码形态它会根据当前设计系统的图标库配置lucide / tabler / hugeicons / phosphor / remixicon 之一参见 icon-placeholder.svelte选择对应图标。而实际通过 CLI 安装到用户项目中的版本则更直接注册表文件 spinner.json 中记录的是基于 LucideLoader2Icon的实现script langts import { cn } from $UTILS$.js; import Loader2Icon from lucide/svelte/icons/loader-2; import type { ComponentProps } from svelte; let { class: className, ...restProps }: ComponentPropstypeof Loader2Icon $props(); /script Loader2Icon rolestatus aria-labelLoading class{cn(size-4 animate-spin, className)} {...restProps} /该注册表文件同时声明了devDependencies: [lucide/svelte^0.561.0]即安装 Spinner 会一并引入 Lucide 图标库作为图标来源。整个组件的核心机制可概括为一个旋转动画类animate-spin 一个可继承尺寸的 SVG 图标 无障碍属性极简且无运行时依赖。安装Spinner 的安装方式与其他 shadcn-svelte 组件一致提供 CLI 与手动两种途径。通过 CLI 安装推荐在项目根目录执行npx shadcn-sveltelatest add spinner命令会自动完成以下工作解析注册表项 spinner.json、将spinner/index.ts与spinner/spinner.svelte写入你项目的组件目录、将lucide/svelte添加为开发依赖。若你的项目尚未初始化组件配置可先运行npx shadcn-sveltelatest init或参考 安装文档 了解不同框架SvelteKit / Vite / Astro的初始化差异。手动安装手动方式分为两步第一步安装图标库依赖npm install lucide/svelte -D使用 pnpm 或 yarn 时替换为pnpm add -D lucide/svelte或yarn add -D lucide/svelte第二步复制源码将注册表文件 spinner.json 中files字段包含的两个文件复制到你的项目spinner/spinner.svelte——组件本体spinner/index.ts——统一导出入口内容为export { default as Spinner } from ./spinner.svelte;复制后调整文件内的$UTILS$别名即你项目中的$lib/utils.js为实际路径即可使用。基本用法在 Svelte 组件中引入并渲染 Spinnerscript langts import { Spinner } from $lib/components/ui/spinner/index.js; /scriptSpinner /渲染结果是一个默认 1remsize-4大小的旋转图标。由于组件继承了SVGAttributesSVGSVGElement的全部属性你可以直接传入任意 SVG 属性!-- 指定无障碍文本 -- Spinner aria-label正在加载数据 / !-- 自定义尺寸 -- Spinner classsize-8 /rolestatus与aria-labelLoading两个默认值共同保证了在无伴生文本的纯图标场景下屏幕阅读器依然能向用户播报加载状态当 Spinner 旁已有说明文字时建议通过aria-label覆盖默认文案或使用aria-hidden避免重复播报。自定义 Spinner原文档明确指出你可以通过编辑Spinner组件本身将默认图标替换为任意其他图标。这一设计源于 Spinner 刻意保持薄封装它没有内置开关或 API 来切换图标风格自定义的直接途径就是修改spinner.svelte中引用的图标组件。文档站内置的 spinner-custom-demo.svelte 给出了一个完整的替换范例——用 Lucide 的LoaderIcon替换默认图标script langts import LoaderIcon from lucide/svelte/icons/loader; import { cn } from $lib/utils.js; import type { ComponentProps } from svelte; type Props ComponentPropstypeof LoaderIcon; let { class: className, ...restProps }: Props $props(); /script LoaderIcon rolestatus aria-labelLoading class{cn(size-4 animate-spin, className)} {...restProps} /替换时只需遵循两条约定即可保持与其他组件按钮、徽章等的协作体验一致保留旋转动画类名中必须包含animate-spin否则图标不会旋转保留无障碍属性rolestatus与aria-labelLoading建议原样保留。如果你使用的是非 Lucide 图标库参照文档站 icon-placeholder.svelte 中lucide / tabler / hugeicons / phosphor / remixicon五套图标名的映射关系将对应库的加载图标替换进去即可。实战示例尺寸SizeSpinner 的尺寸完全由 Tailwind 的size-*工具类控制内部已默认注入size-4追加的类会覆盖它。文档站示例 spinner-size-demo.svelte 演示了从最小到最大的四档div classflex items-center gap-6 Spinner classsize-3 / Spinner classsize-4 / Spinner classsize-6 / Spinner classsize-8 / /div颜色Color加载指示器使用当前文本颜色渲染因此直接使用text-*工具类即可改变颜色。参考示例 spinner-color-demo.sveltediv classflex items-center gap-6 Spinner classsize-6 text-red-500 / Spinner classsize-6 text-green-500 / Spinner classsize-6 text-blue-500 / Spinner classsize-6 text-yellow-500 / Spinner classsize-6 text-purple-500 / /div在实际主题化场景中更推荐使用语义化颜色 token如text-primary、text-muted-foreground以自动适配明暗主题参见 theming.md。按钮Button在按钮中嵌入 Spinner 是加载状态最常见的应用。组件库的Button /源码见 button.svelte会处理好 Spinner 与文字之间的间距你只需把 Spinner 作为子节点传入div classflex flex-col items-center gap-4 Button disabled sizesm Spinner / Loading... /Button Button variantoutline disabled sizesm Spinner / Please wait /Button Button variantsecondary disabled sizesm Spinner / Processing /Button /div完整示例见 spinner-button-demo.svelte。按钮加载态的推荐实践是同时使用disabled阻止重复提交若希望 Spinner 与文字之间产生固定间隔可在 Spinner 上使用data-iconinline-start标记组件库新示例中按钮与徽章的图标间距即依赖此约定参见 button-icon-left.svelte 与 spinner-in-buttons.svelte。对于纯图标按钮记得补充sr-only文本保证可访问性Button variantoutline sizeicon disabled Spinner / span classsr-onlyLoading.../span /Button徽章BadgeSpinner 同样适合放进徽章Badge用于同步中更新中等状态提示。徽章组件badge.svelte默认对子 SVG 做了pointer-events-none处理不会拦截点击。参考示例 spinner-badge-demo.sveltediv classflex items-center gap-2 Badge Spinner / Syncing /Badge Badge variantsecondary Spinner / Updating /Badge Badge variantoutline Spinner / Loading /Badge /divInput Group输入框组Input Group允许在InputGroup.Addon中嵌入 Spinner常用于发送中校验中等输入场景。参考示例 spinner-input-group-demo.svelteInputGroup.Root InputGroup.Input placeholderSend a message... disabled / InputGroup.Addon aligninline-end Spinner / /InputGroup.Addon /InputGroup.Root InputGroup.Root InputGroup.Textarea placeholderSend a message... disabled / InputGroup.Addon alignblock-end Spinner / Validating... InputGroup.Button classms-auto variantdefault ArrowUpIcon / span classsr-onlySend/span /InputGroup.Button /InputGroup.Addon /InputGroup.RootAddon的align属性支持inline-end行尾与block-end块尾部两种对齐方式加载指示器可与提示文字、操作按钮在同一 Addon 内混排。空状态EmptySpinner 可以作为空状态卡片Empty的图标位表达处理中的过渡态。示例 spinner-empty-demo.svelte 展示了将 Spinner 放入Empty.Media varianticonEmpty.Root classw-full border md:p-6 Empty.Header Empty.Media varianticon Spinner / /Empty.Media Empty.TitleProcessing your request/Empty.Title Empty.Description Please wait while we process your request. Do not refresh the page. /Empty.Description /Empty.Header Empty.Content Button variantoutline sizesmCancel/Button /Empty.Content /Empty.RootItem列表项在列表项Item的媒体位使用 Spinner可以表达下载中处理中等单行状态并可与进度条组合。参考示例 spinner-item-demo.svelteItem.Root variantoutline Item.Media varianticon Spinner / /Item.Media Item.Content Item.TitleDownloading.../Item.Title Item.Description129 MB / 1000 MB/Item.Description /Item.Content Item.Actions classhidden sm:flex Button variantoutline sizesmCancel/Button /Item.Actions Item.Footer Progress value{75} / /Item.Footer /Item.Root文档站主页的 spinner-demo.svelte 还展示了一个Processing payment...的支付处理场景将 Spinner、标题与金额排版在同一 Item 中可作为列表内加载态的参考模板。此外新组件示例页见 new-components-01.md中的 spinner.svelte 区块将以上场景汇总展示适合整体预览。小结Spinner 旋转图标 无障碍属性实现依赖 Tailwind 的animate-spin动画类无额外运行时开销安装推荐使用npx shadcn-sveltelatest add spinner手动安装则需同时引入lucide/svelte依赖尺寸用size-*、颜色用text-*控制换图标直接编辑spinner.svelte并保留动画与无障碍属性七类官方示例尺寸、颜色、按钮、徽章、Input Group、Empty、Item覆盖了绝大多数加载状态场景源码均可在 examples 目录下找到可按需复制组合。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考