尧图网站建设 
用 coss Empty 原语构建 Kaneo 的空状态与恢复式 UI 实战指南【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app空状态Empty State是列表类界面中最容易被忽略、却又直接影响用户留存体验的环节当项目列表、标签列表或搜索结果为空时用户需要的不是一行干巴巴的暂无数据而是明确的方向指引和可执行的动作。本文基于 Kaneoapp116开源项目仓库中skills/coss/references/primitives/empty.md的 coss Empty 原语规范结合apps/web/src/components/ui/empty.tsx的真实实现与页面级使用案例讲解如何在 React Tailwind CSS v4 项目中搭建语义完整、带恢复引导的空状态组件。读完本文你将掌握 coss Empty 的完整 API 结构、组合模式、真实项目落地写法以及容易踩中的三类陷阱。Empty 原语是什么何时使用、何时不用coss 是一套基于 Base UI、提供 shadcn 式开发体验的组件库仓库中的 coss skillskills/coss/SKILL.md为其 53 个原语各维护了一份参考指南empty.md是其中之一。它专门回答一个核心问题列表没有数据时界面该怎么呈现。按empty.md的When to use定义Empty 原语适用于两类场景无数据 / 无结果状态No-data/no-results列表、搜索结果、过滤结果为空的页面需要给出引导性说明面向行动恢复的 UIAction-oriented recovery空内容列表需要引导用户立刻执行某个恢复动作例如创建第一个项目。反过来说Empty 原语不是万能的容器——加载中和报错状态应使用专门的加载/错误原语如 skeleton、alert而不是复用空状态组件。这一点在Common pitfalls一节中被明确列为反面典型下文会展开。安装CLI 一键添加与手动依赖empty.md给出了两种安装方式。方式一shadcn CLI 安装推荐npx shadcnlatest add coss/empty这是 coss 组件注册表的标准安装入口与skills/coss/references/cli.md中的整体安装流程一致CLI 会把组件文件写入项目的components/ui目录。方式二手动安装# No extra runtime dependency required for this primitive.原语文档明确说明Empty 不需要任何额外的运行时依赖。这与许多需要 Radix 或 Base UI 包支撑的原语不同——Empty 本质上是纯展示型结构组件只依赖 React 与 Tailwind。手动安装时只需把组件文件复制到本地、并将导入路径改为当前应用的别名配置即可这也是skills/coss/SKILL.md中Quick manual pattern的通用流程。在 Kaneo 仓库中Empty 的落点正是apps/web/src/components/ui/empty.tsx导入别名是/components/ui/empty。组件 API 结构六个子组件与源码级剖析coss Empty 采用容器 语义子组件的组合式 APIempty.md给出的规范导入如下import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from /components/ui/empty对照apps/web/src/components/ui/empty.tsx的真实实现这六个导出都有明确的职责划分子组件DOM 元素职责关键样式要点源码确认Emptydiv整体容器flex flex-col items-center justify-center gap-6 text-center p-6 md:p-12带data-slotemptyEmptyHeaderdiv头部信息区max-w-sm限制宽度垂直居中EmptyMediadiv视觉媒体区图标基于cva的variant变体default透明与icon带边框小方块EmptyTitlediv标题font-heading font-semibold text-xlEmptyDescriptionp描述文字text-muted-foreground text-sm内嵌链接自动下划线EmptyContentdiv动作区max-w-sm子元素垂直排列gap-4值得注意的实现细节1.data-slot语义选择器。每个子组件都携带data-slot属性empty、empty-header、empty-media、empty-title、empty-description、empty-content这与 coss skill 的skills/coss/references/rules/styling.md中强调的>Empty EmptyHeader EmptyMedia varianticon Icon / /EmptyMedia EmptyTitleNo data/EmptyTitle EmptyDescriptionNo data found/EmptyDescription /EmptyHeader EmptyContent ButtonAdd data/Button /EmptyContent /Empty注意结构层次EmptyMedia / EmptyTitle / EmptyDescription必须统一放在EmptyHeader内动作按钮放在EmptyContent内这是组合式 API 的约定俗成破坏这个层次会导致布局与语义错乱。实战模式Kaneo 中的真实空状态用例empty.md提供了带图标与动作按钮的推荐模式而 Kaneo 仓库中正好有三个页面级实现可供对照其中两个值得逐行解读。用例一工作区无项目完整恢复式空状态apps/web/src/routes/_layout/_authenticated/dashboard/workspace/$workspaceId/index.tsx是empty.md中Always include an actionable next step原则的教科书级落地Empty classNamemin-h-[60vh] EmptyHeader EmptyMedia varianticon LayoutGrid / /EmptyMedia EmptyTitle{t(workspace:projects.emptyTitle)}/EmptyTitle EmptyDescription {canCreate ? t(workspace:projects.emptyDescription) : t(workspace:projects.emptyDescriptionReadOnly)} /EmptyDescription /EmptyHeader EmptyContent {canCreate ( Button onClick{handleCreateProject} Plus / {t(workspace:projects.createProject)} /Button )} /EmptyContent /Empty几个可以照抄到任何项目的细节classNamemin-h-[60vh]通过 className 透传撑高整个空状态区避免空页面显得头重脚轻这是Empty容器接受React.ComponentPropsdiv的灵活之处权限感知的文案与动作canCreate为 true 时显示创建项目按钮与创建引导文案无权限时只显示只读文案并隐藏按钮——空状态的下一步必须与用户实际权限匹配否则是无效引导图标语义LayoutGrid暗示项目的业务语义Plus表示新增均带aria-hidden由描述文字承担可访问性信息动作即跳转handleCreateProject会打开CreateProjectModal紧随其后的CreateProjectModal完成空状态 → 引导 → 创建 → 列表刷新的完整闭环。用例二无自定义角色引导性空状态apps/web/src/routes/_layout/_authenticated/dashboard/settings/workspace/roles.tsx展示了无动作按钮的变体——当创建动作以其他形式存在页面头部有新建入口时空状态只需提供图标 标题 描述Empty EmptyHeader EmptyMedia varianticon Shield / /EmptyMedia EmptyTitle {t(settings:workspaceRoles.emptyTitle)} /EmptyTitle EmptyDescription {t(settings:workspaceRoles.emptyDescription)} /EmptyDescription /EmptyHeader /Empty该文件还展示了正确的条件渲染顺序roles.tsxisLoading → 加载提示 → error → 错误提示 → 空列表 → Empty 组件 → 否则渲染真实列表即 Empty 只接管数据已加载且确认为空的分支绝不与加载态、错误态混用——这正是empty.mdCommon pitfalls 第 2 条的直接印证。同样的模式还出现在labels.tsx工作区标签为空时。常见陷阱三类高频失误与规避方案empty.md的Common pitfalls一节列出了三条高频错误结合 Kaneo 源码可以给出更具体的规避手段陷阱 1空状态没有可执行的下一步。只展示暂无数据四个字而不给按钮/链接用户会陷入死胡同。规避只要业务上允许就在EmptyContent中放入明确的恢复动作按钮、链接、快捷键提示即便动作放在页面其他位置也应如 roles.tsx 那样在描述中说明如何开始。陷阱 2用空状态组件冒充加载态 / 错误态。加载中应使用骨架屏skeleton错误应使用 alert/destructive 提示两者与空是语义不同的状态。规避如 roles.tsx 所示把isLoading、error、empty三个分支拆开渲染Empty 只负责data.length 0的场景。陷阱 3纯文案空状态缺少上下文相关的恢复指引。描述文字要因场景而异工作区空项目与搜索无结果、筛选无匹配的引导文案与动作完全不同。规避描述文案走 i18nKaneo 中统一使用t(workspace:projects.emptyDescription)这类翻译键且按canCreate等上下文动态切换确保每条空状态都回答为什么空 下一步干什么。延伸阅读原语规范skills/coss/references/primitives/empty.md本文的规范来源含p-empty-1核心粒子模式索引组件实现apps/web/src/components/ui/empty.tsx页面级用例工作区无项目、无自定义角色、无标签coss 技能总览与组件注册表skills/coss/SKILL.md、skills/coss/references/component-registry.md样式与组合规则skills/coss/references/rules/styling.md、skills/coss/references/rules/composition.md【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 coss Empty 原语构建 Kaneo 的空状态与恢复式 UI 实战指南
用 coss Empty 原语构建 Kaneo 的空状态与恢复式 UI 实战指南【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app空状态Empty State是列表类界面中最容易被忽略、却又直接影响用户留存体验的环节当项目列表、标签列表或搜索结果为空时用户需要的不是一行干巴巴的暂无数据而是明确的方向指引和可执行的动作。本文基于 Kaneoapp116开源项目仓库中skills/coss/references/primitives/empty.md的 coss Empty 原语规范结合apps/web/src/components/ui/empty.tsx的真实实现与页面级使用案例讲解如何在 React Tailwind CSS v4 项目中搭建语义完整、带恢复引导的空状态组件。读完本文你将掌握 coss Empty 的完整 API 结构、组合模式、真实项目落地写法以及容易踩中的三类陷阱。Empty 原语是什么何时使用、何时不用coss 是一套基于 Base UI、提供 shadcn 式开发体验的组件库仓库中的 coss skillskills/coss/SKILL.md为其 53 个原语各维护了一份参考指南empty.md是其中之一。它专门回答一个核心问题列表没有数据时界面该怎么呈现。按empty.md的When to use定义Empty 原语适用于两类场景无数据 / 无结果状态No-data/no-results列表、搜索结果、过滤结果为空的页面需要给出引导性说明面向行动恢复的 UIAction-oriented recovery空内容列表需要引导用户立刻执行某个恢复动作例如创建第一个项目。反过来说Empty 原语不是万能的容器——加载中和报错状态应使用专门的加载/错误原语如 skeleton、alert而不是复用空状态组件。这一点在Common pitfalls一节中被明确列为反面典型下文会展开。安装CLI 一键添加与手动依赖empty.md给出了两种安装方式。方式一shadcn CLI 安装推荐npx shadcnlatest add coss/empty这是 coss 组件注册表的标准安装入口与skills/coss/references/cli.md中的整体安装流程一致CLI 会把组件文件写入项目的components/ui目录。方式二手动安装# No extra runtime dependency required for this primitive.原语文档明确说明Empty 不需要任何额外的运行时依赖。这与许多需要 Radix 或 Base UI 包支撑的原语不同——Empty 本质上是纯展示型结构组件只依赖 React 与 Tailwind。手动安装时只需把组件文件复制到本地、并将导入路径改为当前应用的别名配置即可这也是skills/coss/SKILL.md中Quick manual pattern的通用流程。在 Kaneo 仓库中Empty 的落点正是apps/web/src/components/ui/empty.tsx导入别名是/components/ui/empty。组件 API 结构六个子组件与源码级剖析coss Empty 采用容器 语义子组件的组合式 APIempty.md给出的规范导入如下import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from /components/ui/empty对照apps/web/src/components/ui/empty.tsx的真实实现这六个导出都有明确的职责划分子组件DOM 元素职责关键样式要点源码确认Emptydiv整体容器flex flex-col items-center justify-center gap-6 text-center p-6 md:p-12带data-slotemptyEmptyHeaderdiv头部信息区max-w-sm限制宽度垂直居中EmptyMediadiv视觉媒体区图标基于cva的variant变体default透明与icon带边框小方块EmptyTitlediv标题font-heading font-semibold text-xlEmptyDescriptionp描述文字text-muted-foreground text-sm内嵌链接自动下划线EmptyContentdiv动作区max-w-sm子元素垂直排列gap-4值得注意的实现细节1.data-slot语义选择器。每个子组件都携带data-slot属性empty、empty-header、empty-media、empty-title、empty-description、empty-content这与 coss skill 的skills/coss/references/rules/styling.md中强调的>Empty EmptyHeader EmptyMedia varianticon Icon / /EmptyMedia EmptyTitleNo data/EmptyTitle EmptyDescriptionNo data found/EmptyDescription /EmptyHeader EmptyContent ButtonAdd data/Button /EmptyContent /Empty注意结构层次EmptyMedia / EmptyTitle / EmptyDescription必须统一放在EmptyHeader内动作按钮放在EmptyContent内这是组合式 API 的约定俗成破坏这个层次会导致布局与语义错乱。实战模式Kaneo 中的真实空状态用例empty.md提供了带图标与动作按钮的推荐模式而 Kaneo 仓库中正好有三个页面级实现可供对照其中两个值得逐行解读。用例一工作区无项目完整恢复式空状态apps/web/src/routes/_layout/_authenticated/dashboard/workspace/$workspaceId/index.tsx是empty.md中Always include an actionable next step原则的教科书级落地Empty classNamemin-h-[60vh] EmptyHeader EmptyMedia varianticon LayoutGrid / /EmptyMedia EmptyTitle{t(workspace:projects.emptyTitle)}/EmptyTitle EmptyDescription {canCreate ? t(workspace:projects.emptyDescription) : t(workspace:projects.emptyDescriptionReadOnly)} /EmptyDescription /EmptyHeader EmptyContent {canCreate ( Button onClick{handleCreateProject} Plus / {t(workspace:projects.createProject)} /Button )} /EmptyContent /Empty几个可以照抄到任何项目的细节classNamemin-h-[60vh]通过 className 透传撑高整个空状态区避免空页面显得头重脚轻这是Empty容器接受React.ComponentPropsdiv的灵活之处权限感知的文案与动作canCreate为 true 时显示创建项目按钮与创建引导文案无权限时只显示只读文案并隐藏按钮——空状态的下一步必须与用户实际权限匹配否则是无效引导图标语义LayoutGrid暗示项目的业务语义Plus表示新增均带aria-hidden由描述文字承担可访问性信息动作即跳转handleCreateProject会打开CreateProjectModal紧随其后的CreateProjectModal完成空状态 → 引导 → 创建 → 列表刷新的完整闭环。用例二无自定义角色引导性空状态apps/web/src/routes/_layout/_authenticated/dashboard/settings/workspace/roles.tsx展示了无动作按钮的变体——当创建动作以其他形式存在页面头部有新建入口时空状态只需提供图标 标题 描述Empty EmptyHeader EmptyMedia varianticon Shield / /EmptyMedia EmptyTitle {t(settings:workspaceRoles.emptyTitle)} /EmptyTitle EmptyDescription {t(settings:workspaceRoles.emptyDescription)} /EmptyDescription /EmptyHeader /Empty该文件还展示了正确的条件渲染顺序roles.tsxisLoading → 加载提示 → error → 错误提示 → 空列表 → Empty 组件 → 否则渲染真实列表即 Empty 只接管数据已加载且确认为空的分支绝不与加载态、错误态混用——这正是empty.mdCommon pitfalls 第 2 条的直接印证。同样的模式还出现在labels.tsx工作区标签为空时。常见陷阱三类高频失误与规避方案empty.md的Common pitfalls一节列出了三条高频错误结合 Kaneo 源码可以给出更具体的规避手段陷阱 1空状态没有可执行的下一步。只展示暂无数据四个字而不给按钮/链接用户会陷入死胡同。规避只要业务上允许就在EmptyContent中放入明确的恢复动作按钮、链接、快捷键提示即便动作放在页面其他位置也应如 roles.tsx 那样在描述中说明如何开始。陷阱 2用空状态组件冒充加载态 / 错误态。加载中应使用骨架屏skeleton错误应使用 alert/destructive 提示两者与空是语义不同的状态。规避如 roles.tsx 所示把isLoading、error、empty三个分支拆开渲染Empty 只负责data.length 0的场景。陷阱 3纯文案空状态缺少上下文相关的恢复指引。描述文字要因场景而异工作区空项目与搜索无结果、筛选无匹配的引导文案与动作完全不同。规避描述文案走 i18nKaneo 中统一使用t(workspace:projects.emptyDescription)这类翻译键且按canCreate等上下文动态切换确保每条空状态都回答为什么空 下一步干什么。延伸阅读原语规范skills/coss/references/primitives/empty.md本文的规范来源含p-empty-1核心粒子模式索引组件实现apps/web/src/components/ui/empty.tsx页面级用例工作区无项目、无自定义角色、无标签coss 技能总览与组件注册表skills/coss/SKILL.md、skills/coss/references/component-registry.md样式与组合规则skills/coss/references/rules/styling.md、skills/coss/references/rules/composition.md【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考