recurve-ui v0.1.4-beta.0

🍎 推荐的 IDE 环境

VSCode + Volar (并禁用 Vetur) + TypeScript Vue 插件 (Volar).

⛅ 环境支持

由于 Vue 3 不再支持 IE11，RecurveUI 也不再支持 IE 浏览器

✨ 使用方法

📦 包管理器

👉 我们强烈建议您使用 pnpm 作为您项目的包管理器

🏆 目前我们的大部分基础组件都是基于 Element Plus，使用 recurve-ui 前应先确保你的项目已经安装了 element-plus

• pnpm add element-plus

🎯 按需导入

一、首先你需要安装 recurve-ui

• pnpm add recurve-ui @recurve-ui/icons

二、然后安装 Tailwind CSS

• pnpm add -D tailwindcss postcss autoprefixer
• 使用 npx tailwindcss init -p 来生成 tailwind.config.js、postcss.config.js 文件
• 我们提供了一个符合品牌设计规范的默认文件 tailwind.presets.config.js
• 你需要添加 @/styles/tailwind.css 文件，然后在你的tailwind.config.js 中使用 presets: [require('recurve-ui/tailwind.presets.config.js')] 来引入默认配置（注：请将 content 字段调整为你项目所需要的路径）
• 在项目的 @/main.ts 文件中使用 import '@/styles/tailwind.css' 来引入 Tailwind CSS（建议放在引入其他样式之前）

三、组件样式

• recurve-ui 样式分为基础变量： _variable.scss 和组件样式：element-plus 两个部分
• 首先在你项目的样式目录（如：@/styles）下新建一个 recurve-ui.scss 文件

• 如果你不需要自定义主题，直接引入 recurve-ui 样式文件

  // styles/recurve-ui.scss
  @import 'recurve-ui/styles/recurve-ui.scss';

• 如果需要自定义主题，

  • 你需要先在 recurve-ui.scss 引入 @import 'recurve-ui/styles/_variable.scss';

  • 自定义基础变量，新建一个样式文件（如 @/styles/_variable.scss），然后在 recurve-ui.scss 里引入你新建的文件

    // styles/_variable.scss
    :root {
      --color-brand-500: #02030A;
    };

  • 自定义组件样式，新建一个样式文件（如 @/styles/element-plus.scss），然后在 recurve-ui.scss 里引入你新建的文件

    // styles/element-plus.scss
    @forward 'recurve-ui/styles/element-plus.scss' with (
      $--color-primary: #02030A,
    );

  • 最终你的 recurve-ui.scss 文件可能是这样

    // styles/recurve-ui.scss
    @import 'recurve-ui/styles/_variable.scss';
    
    // 仅自定义基础变量
    @import 'variable';
    @import 'recurve-ui/styles/element-plus.scss';
    
    // 仅自定义组件样式
    @import './element-plus';

四、在 Vite 的配置文件 vite.config.ts 中添加：

export default defineConfig({
  // ...
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "@/styles/recurve-ui.scss" as *;`,
      },
    },
  },
})

五、🚚 添加 @recurve-ui/plugins 以支持自动导入组件和组件样式文件

• pnpm add -D vite-plugin-style-import unplugin-vue-components consola sass
• pnpm add -D @recurve-ui/plugins

• import Components from 'unplugin-vue-components/vite'
  import { createStyleImportPlugin } from 'vite-plugin-style-import'
  import { RecurveUIResolver, RecurveUIStyleResolver } from '@recurve-ui/plugins'
  
  export default defineConfig({
    // ...
    plugins: [
      // ...
      Components({
        resolvers: [
          RecurveUIResolver({
            importStyle: 'sass',
          }),
        ],
      }),
      // 注意：`createStyleImportPlugin` 需要放在 `Components` 后
      createStyleImportPlugin({
        resolves: [
          RecurveUIStyleResolver(),
        ],
      }),
    ],
  })

六、pnpm dev

📦 全量引入

// main.ts
import { createApp } from 'vue'
import RecurveUI from 'recurve-ui'
import 'recurve-ui/dist/index.css'
import App from './App.vue'

const app = createApp(App)

app.use(RecurveUI)
app.mount('#app')

🍊 Volar 支持

• 破坏性改动

  • 目前 types 需要 vue 为 v3.2.47 ("vue": "^3.2.47") 及以上

• 如果您使用 Volar，请在 tsconfig.json 中通过 compilerOptions.types 指定全局组件类型。

// tsconfig.json
{
  "compilerOptions": {
    // ...
    "types": ["recurve-ui/global.d.ts"]
  }
}

• 如果你使用 Pnpm 作为项目的包管理工具，那么你需要在项目的 .npmrc 文件中添加 public-hoist-pattern[]=@vue/runtime-core 来将 @vue/runtime-core 提升为顶级依赖，然后再重新安装依赖包（必要时可重启下编辑器），使用 pnpm 命令创建的 vite 项目无法在 VS Code 中获得组件类型提示
• 推荐使用："typescript": "^4.8.4" 和 "@vue/tsconfig": "^0.1.3"，注意若使用 "typescript": "^5.0.0" 和 "@vue/tsconfig": "^0.4.0" 可能会存在组件属性值提示错误的问题。
• 从 TypeScript < 5.0 迁移过来

🔔 注意事项

🔑 提示

一、🎨 自定义命名空间，需要安装 Tailwind CSS，并参考 自定义命名空间来配置，并且需要引入 Element Plus 的样式变量。

• 使用方式:

// styles/element-plus.scss
@forward 'element-plus/theme-chalk/src/mixins/config.scss' with (
  $namespace: 'rd'
);

@forward 'element-plus/theme-chalk/src/common/var.scss';

<!-- App.vue -->
<template>
  <el-config-provider namespace="rd">
    <app />
  </el-config-provider>
</template>

<script lang="ts" setup>
import { ElConfigProvider } from 'element-plus'
</script>

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  // ...
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "~/styles/recurve-ui/index.scss" as *;`,
      },
    },
  },
  // ...
})

二、🌍 国际化，需要安装 @recurve-ui/locale，详见：README

🔮 其他问题

1. Tailwind CSS 默认样式冲突？

• 可在项目的 tailwind.config.js 中禁用 Preflight，然后改用：Preflight
• 可参考 tailwind.css

❓ 问题

如果你遇到任何问题，你可以在 issues 联系我们

📝 更新日志

每个版本的详细更改都记录在发布说明中

🎁 致谢

• Vue: 易学易用，性能出色，适用场景丰富的 Web 前端框架
• Element Plus: 基于 Vue 3，面向设计师和开发者的组件库
• PNPM: 快速的，节省磁盘空间的包管理工具
• Storybook: 一个用于独立构建 UI 组件和页面的前端工具