registry-item.json 模式用于定义您的自定义注册表项目。

registry-item.json

{
  "$schema": "https://shadcn-vue.com/schema/registry-item.json",
  "name": "hello-world",
  "type": "registry:block",
  "title": "Hello World",
  "description": "一个简单的 hello world 组件。",
  "files": [
    {
      "path": "registry/new-york/HelloWorld/HelloWorld.vue",
      "type": "registry:component"
    },
    {
      "path": "registry/new-york/HelloWorld/useHelloWorld.ts",
      "type": "registry:hook"
    }
  ]
}

定义

您可以在此处查看 registry-item.json 的 JSON 模式。

$schema

$schema 属性用于指定 registry-item.json 文件的模式。

registry-item.json

{
  "$schema": "https://shadcn-vue.com/schema/registry-item.json"
}

name

name 属性用于指定注册表项目的名称。

registry-item.json

{
  "name": "hello-world"
}

title

注册表项目的人类可读标题。保持简短且具有描述性。

registry-item.json

{
  "title": "Hello World"
}

description

注册表项目的描述。可以比 title 更长且更详细。

registry-item.json

{
  "description": "一个简单的 hello world 组件。"
}

type

type 属性用于指定注册表项目的类型。

registry-item.json

{
  "type": "registry:block"
}

支持以下类型：

类型	描述
registry:block	用于包含多个文件的复杂组件。
registry:component	用于简单组件。
registry:lib	用于库和工具函数。
registry:hook	用于组合式函数（hooks）。
registry:ui	用于 UI 组件和单文件基元。
registry:page	用于页面或基于文件的路由。
registry:file	用于杂项文件。

author

author 属性用于指定注册表项目的作者。

它可以特定于该注册表项目，也可以与注册表的作者相同。

registry-item.json

{
  "author": "John Doe <john@doe.com>"
}

dependencies

dependencies 属性用于指定注册表项目的依赖项。这是针对 npm 包的。

使用 @version 来指定注册表项目的版本。

registry-item.json

{
  "dependencies": [
    "reka-ui",
    "zod",
    "lucide-vue-next",
    "name@1.0.2"
  ]
}

registryDependencies

用于注册表依赖项。可以是名称或 URL。

• 对于 shadcn/ui 注册表项目，如 button、input、select 等，使用名称，例如 ['button', 'input', 'select']。
• 对于自定义注册表项目，使用注册表项目的 URL，例如 ['https://example.com/r/hello-world.json']。

registry-item.json

{
  "registryDependencies": [
    "button",
    "input",
    "select",
    "https://example.com/r/editor.json"
  ]
}

注意：CLI 将自动解析远程注册表依赖项。

files

files 属性用于指定注册表项目的文件。每个文件都有一个 path、type 和可选的 target 属性。

target 属性对于 registry:page 和 registry:file 类型是必需的。

registry-item.json

{
  "files": [
    {
      "path": "registry/new-york/HelloWorld/page.vue",
      "type": "registry:page",
      "target": "pages/hello/index.vue"
    },
    {
      "path": "registry/new-york/HelloWorld/HelloWorld.vue",
      "type": "registry:component"
    },
    {
      "path": "registry/new-york/HelloWorld/useHelloWorld.ts",
      "type": "registry:hook"
    },
    {
      "path": "registry/new-york/HelloWorld/.env",
      "type": "registry:file",
      "target": "~/.env"
    }
  ]
}

path

path 属性用于指定注册表中文件的路径。构建脚本使用此路径来解析、转换和构建注册表 JSON 负载。

type

type 属性用于指定文件的类型。更多信息请参阅 type 部分。

target

target 属性用于指示文件应放置在项目中的何处。这是可选的，仅对 registry:page 和 registry:file 类型必需。

默认情况下，shadcn-vue cli 将读取项目的 components.json 文件来确定目标路径。对于某些文件，例如路由或配置文件，您可以手动指定目标路径。

使用 ~ 来引用项目的根目录，例如 ~/foo.config.js。

tailwind

已弃用： 对于 Tailwind v4 项目，请改用 cssVars.theme。

tailwind 属性用于 Tailwind 配置，例如 theme、plugins 和 content。

您可以使用 tailwind.config 属性为注册表项目添加颜色、动画和插件。

registry-item.json

{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "brand": "hsl(var(--brand))"
          },
          "keyframes": {
            "wiggle": {
              "0%, 100%": { "transform": "rotate(-3deg)" },
              "50%": { "transform": "rotate(3deg)" }
            }
          },
          "animation": {
            "wiggle": "wiggle 1s ease-in-out infinite"
          }
        }
      }
    }
  }
}

cssVars

用于为注册表项目定义 CSS 变量。

registry-item.json

{
  "cssVars": {
    "light": {
      "brand": "20 14.3% 4.1%",
      "radius": "0.5rem"
    },
    "dark": {
      "brand": "20 14.3% 4.1%"
    }
  }
}

css

使用 css 向项目的 CSS 文件添加新规则，例如 @layer base、@layer components、@utility、@keyframes 等。

registry-item.json

{
  "css": {
    "@layer base": {
      "body": {
        "font-size": "var(--text-base)",
        "line-height": "1.5"
      }
    },
    "@layer components": {
      "button": {
        "background-color": "var(--color-primary)",
        "color": "var(--color-white)"
      }
    },
    "@utility text-magic": {
      "font-size": "var(--text-base)",
      "line-height": "1.5"
    },
    "@keyframes wiggle": {
      "0%, 100%": {
        "transform": "rotate(-3deg)"
      },
      "50%": {
        "transform": "rotate(3deg)"
      }
    }
  }
}

docs

使用 docs 在通过 CLI 安装注册表项目时显示自定义文档或消息。

registry-item.json

{
  "docs": "请记得将 FOO_BAR 环境变量添加到您的 .env 文件中。"
}

categories

使用 categories 来组织您的注册表项目。

registry-item.json

{
  "categories": ["sidebar", "dashboard"]
}

meta

使用 meta 向注册表项目添加额外的元数据。您可以添加任何希望注册表项目可用的键/值对。

registry-item.json

{
  "meta": { "foo": "bar" }
}