Loongship UI

Appearance

快速开始 ​

Loongship UI 面向 Vue 3 + Vite，通过 CLI 将所需组件源码复制到项目中，无需安装完整的运行时组件库。

1. 项目初始化 ​

在 Vue 3 + Vite 项目根目录运行初始化命令：

bash
npx @loongship-kit/ui init

初始化命令会：

  • 创建 loongship.json 和本地 JSON Schema
  • 从 npm 包内复制全局主题变量样式表 theme.css 和全局主题入口 theme.ts
  • 验证当前项目使用 Vue 3

依赖需要手动安装

CLI 只提示 npm 依赖，不会自动安装。日期与时间组件使用以下版本基线：

bash
pnpm add reka-ui@^2.10.1 @internationalized/date@^3.12.2

2. 添加组件 ​

使用 add 添加一个或多个组件：

bash
# 添加单个组件
npx @loongship-kit/ui add button

# 一次性添加多个组件
npx @loongship-kit/ui add button input

3. 在项目中使用组件 ​

组件源码会写入项目目录，例如 src/components/loongship/button。按本地组件导入即可：

vue
<script setup lang="ts">
import { Button } from '@/components/loongship/button'
</script>

<template>
  <Button variant="default">确认提交</Button>
</template>

在应用入口导入初始化生成的主题文件：

ts
import '@/styles/loongship.css'

主题入口位于 src/styles/theme.ts：

ts
import { setTheme } from '@/styles/theme'

setTheme('dark')

主题职责

setTheme 只接受 'light' | 'dark'，默认使用 Light。应用负责检测系统主题、保存用户偏好以及决定是否展示切换按钮。

SSR 首屏主题

SSR 应用应在首屏 HTML 输出 <html data-theme="light|dark">，避免客户端挂载后再切换造成闪烁。

已有文件不会被覆盖

CLI 会跳过已有文件。如需更新已存在的组件，请先自行处理本地文件。