快速开始

安装

# npm
npm i @cedarjs/ui @cedarjs/icons-vue

# pnpm
pnpm add @cedarjs/ui @cedarjs/icons-vue

自动按需引入（推荐）

Cedar 提供内部维护的 @cedarjs/resolver。配合 unplugin-vue-components，模板中使用到的组件、独立 SVG 图标、指令及组件样式会在编译时自动按需引入。

npm i @cedarjs/resolver unplugin-auto-import unplugin-vue-components -D

Vite

// vite.config.ts
import vue from "@vitejs/plugin-vue";
import AutoImport from "unplugin-auto-import/vite";
import Components from "unplugin-vue-components/vite";
import { CedarResolver } from "@cedarjs/resolver";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      resolvers: [CedarResolver()],
    }),
    Components({
      resolvers: [CedarResolver()],
    }),
  ],
});

配置后可直接使用，无需在组件中手动导入：

<template>
  <c-button status="primary">确认</c-button>
  <c-icon size="40" color="red">
    <c-icon-check-circle-fill />
  </c-icon>
</template>

Resolver 会分别生成：

import { Button, Icon } from "@cedarjs/ui";
import { IconCheckCircleFill } from "@cedarjs/icons-vue/icon-check-circle-fill";
import "@cedarjs/ui/button/style";
import "@cedarjs/ui/icon/style";

独立 SVG 图标通过 currentColor 继承容器颜色，因此图标子包不需要额外 CSS；c-icon 容器自身需要加载 @cedarjs/ui/icon/style。

动态名称与显式注册

<c-icon name="check-circle-fill" /> 只查询显式注册到 Vue 应用的图标，组件内部不会导入图标全集。建议只注册动态场景需要的图标：

// main.ts
import { createApp } from "vue";
import { IconCheckCircleFill, IconWarning } from "@cedarjs/icons-vue";
import App from "./App.vue";

const app = createApp(App);
app.component("IconCheckCircleFill", IconCheckCircleFill);
app.component("IconWarning", IconWarning);
app.mount("#app");

如果业务需要通过任意名称使用全部图标，也可以主动批量注册；这种写法会加载完整图标集合：

import * as CedarIconsVue from "@cedarjs/icons-vue";

for (const [name, component] of Object.entries(CedarIconsVue)) {
  if (name.startsWith("Icon")) app.component(name, component);
}

直接使用 SVG 图标

@cedarjs/icons-vue 中的每个 SVG 图标都是独立的 Vue 组件，也可以不使用 c-icon 容器直接渲染：

<script setup lang="ts">
import {
  IconDelete,
  IconEdit,
  IconSearch,
  IconShareExternal,
} from "@cedarjs/icons-vue";
</script>

<template>
  <!-- 直接使用 SVG 图标时不会自动提供业务布局属性 -->
  <!-- 请根据使用场景设置宽高、间距等属性 -->
  <IconEdit style="width: 1em; height: 1em; margin-right: 8px" />
  <IconShareExternal style="width: 1em; height: 1em; margin-right: 8px" />
  <IconDelete style="width: 1em; height: 1em; margin-right: 8px" />
  <IconSearch style="width: 1em; height: 1em; margin-right: 8px" />
</template>

这里的“布局属性”是指 width、height、margin 等业务样式；图标组件自身仍支持 size、color、rotate 和 spin。直接使用同样支持 Tree Shaking。需要统一控制布局、尺寸、颜色、旋转或交互区域时，推荐再使用 c-icon 包裹。

自动引入函数 API

上面的同一个 CedarResolver() 也会为 unplugin-auto-import 解析 Message、Dialog、Notification 等函数 API：

Message.success("保存成功");

importStyle 会统一控制模板组件、Icon 容器和函数 API 的样式导入。只有明确不希望解析函数 API 时，才需要设置 CedarResolver({ autoImport: false })。

自动引入指令

同一个 CedarResolver() 支持 v-c-loading 和 v-tooltip，无需配置第二个 Resolver。加载指令使用 c- 前缀，避免与其他组件库的同名指令冲突。可通过 CedarResolver({ directives: false }) 关闭。

手动按需引入

不使用自动导入插件时，可手动导入组件、图标和组件样式：

<script setup lang="ts">
import { Button } from "@cedarjs/ui";
import { IconCheckCircleFill } from "@cedarjs/icons-vue/icon-check-circle-fill";
import "@cedarjs/ui/button/style";
</script>

<template>
  <Button status="primary">确认</Button>
  <IconCheckCircleFill :size="24" />
</template>

完整引入

完整引入会注册全部 Cedar UI 组件和指令，并加载全部样式，适合原型或对包体积不敏感的项目：

import { createApp } from "vue";
import Cedar from "@cedarjs/ui";
import "@cedarjs/ui/style";
import App from "./App.vue";

createApp(App).use(Cedar).mount("#app");

独立 SVG 图标不会随 UI 包全部注册；请继续显式导入，或使用 CedarResolver() 自动按需引入。

TypeScript 配置

确保自动生成的声明文件被 TypeScript 包含：

{
  "include": ["src", "components.d.ts", "auto-imports.d.ts"]
}

样式控制

Resolver 默认自动引入组件样式。如项目已完整引入 Cedar 样式，可关闭重复的按需样式：

CedarResolver({ importStyle: false });