107 lines
3.0 KiB
Markdown
107 lines
3.0 KiB
Markdown
# @g3soft/ui
|
||
|
||
G3Soft 通用 UI 组件库（Vue 3 + TypeScript）。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
pnpm add @g3soft/ui @g3soft/tokens
|
||
```
|
||
|
||
`vue` 通过 `peerDependencies` 声明，由宿主项目提供，请确保宿主已安装 Vue 3。
|
||
|
||
## 使用
|
||
|
||
样式变量来自 `@g3soft/tokens`，在应用入口引入一次：
|
||
|
||
```ts
|
||
import '@g3soft/tokens'
|
||
```
|
||
|
||
按需引入组件：
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { G3Button } from '@g3soft/ui'
|
||
</script>
|
||
|
||
<template>
|
||
<G3Button type="primary" @click="handleClick">主要按钮</G3Button>
|
||
</template>
|
||
```
|
||
|
||
也可以全量注册：
|
||
|
||
```ts
|
||
import { G3UI } from '@g3soft/ui'
|
||
import { createApp } from 'vue'
|
||
|
||
createApp(App).use(G3UI).mount('#app')
|
||
```
|
||
|
||
## 主题
|
||
|
||
只暴露一个主色 `primary`，色阶、交互态、`on-primary`、氛围色与中性灰全部自动派生
|
||
（OKLab 空间计算，`success` / `warning` / `danger` 为独立固定语义色，不参与派生）：
|
||
|
||
```vue
|
||
<G3ConfigProvider :theme="{ primary: '#18181b' }">
|
||
<App />
|
||
</G3ConfigProvider>
|
||
```
|
||
|
||
- `theme.scope` 默认 `local`：变量挂到子树根，支持同页多主题；传 `global` 则挂到 `:root` 做整站换肤。
|
||
- `theme.dark` 复用同一派生算法切换到暗色。
|
||
- 不传 `theme` 时，`@g3soft/tokens` 的静态默认值即权威来源，外观零漂移。
|
||
|
||
## 命名空间（前缀）
|
||
|
||
类名 / CSS 变量 / `@keyframes` 前缀统一由编译期 `$namespace`（默认 `g3`）派生，
|
||
消费方不能单独配置 CSS 变量前缀。换前缀需重编译样式：
|
||
|
||
```scss
|
||
// 你的样式桥接文件，例如 src/styles/g3.scss
|
||
@forward '@g3soft/tokens/scss' with ($namespace: 'xx');
|
||
```
|
||
|
||
```ts
|
||
// vite.config.ts
|
||
// additionalData 只能 @use 桥接文件；with 不能写在 additionalData 里（会被重复配置而报错）
|
||
css: { preprocessorOptions: { scss: { additionalData: `@use "@/styles/g3.scss" as *;` } } },
|
||
```
|
||
|
||
再用相同的 `$namespace` 重编译 `@g3soft/ui` 源码，并设置运行时命名空间：
|
||
|
||
```ts
|
||
import { G3UI } from '@g3soft/ui'
|
||
G3UI.config({ namespace: 'xx' })
|
||
```
|
||
|
||
> dev 模式下运行时前缀与编译期前缀不一致会告警。该校验是启发式：能发现「改了运行时前缀却
|
||
> 仍在用预编译 g3 样式」，但无法感知「重编译了 SCSS 却跑预编译 JS」——两者必须手动保持一致。
|
||
|
||
## 全局配置
|
||
|
||
组件树外的实例（未来 `Message.xxx()` 等）拿不到 inject 上下文，用静态方法写全局兜底：
|
||
|
||
```ts
|
||
import { G3UI, zhCN } from '@g3soft/ui'
|
||
|
||
G3UI.config({ namespace: 'g3', zIndex: 2000, locale: zhCN })
|
||
```
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
pnpm build
|
||
```
|
||
|
||
产物在 `dist/`，包含 ESM 入口与类型声明。发布前会由 `prepublishOnly` 执行 `publint` 校验包结构。
|
||
|
||
## 约定
|
||
|
||
- 样式**不写 `scoped`**，统一用命名空间前缀（默认 `g3-`）+ BEM 命名，便于消费方覆盖。
|
||
- 组件内部拼类名一律走 `useNamespace()`，不在模板里硬编码前缀。
|
||
- 每个 CSS 变量都带兜底值，保证未引入 tokens 时组件仍可正常显示。
|
||
- 组件不写死颜色与尺寸，一律引用 `--g3-*` 变量；文案一律走 `useLocale()`。
|