Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion docs/developer-guide/plugin/api-reference/ui/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,16 @@
"api-request",
"formkit",
"shared",
{
"type": "dir",
"name": "base-components",
"label": "基础组件",
"collapsed": true
},
{
"type": "dir",
"name": "components",
"label": "组件",
"label": "业务组件",
"collapsed": true
}
]
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
[
"button",
"space",
"card",
"description",
"header",
"tag",
"status",
"avatar",
"empty",
"loading",
"alert",
"switch",
"tabs",
"menu",
"pagination",
"dropdown",
"modal",
"dialog",
"toast",
"tooltip",
"entity",
"icons"
]
147 changes: 147 additions & 0 deletions docs/developer-guide/plugin/api-reference/ui/base-components/alert.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
---
title: VAlert 提示
description: 使用 VAlert 在 Halo 插件页面中展示成功、信息、警告和错误等提示信息,支持关闭、自定义图标和操作按钮
---

`VAlert` 用于在页面内展示需要用户注意的信息,提供比 Toast 更持久、比 Dialog 更轻量的提示方式。

## 引入

```ts
import { VAlert } from "@halo-dev/components";
```

## 示例

### 基础用法

```vue preview
<script lang="ts" setup>
import { VAlert } from "@halo-dev/components";
</script>

<template>
<VAlert
type="info"
title="内容已保存为草稿"
description="发布前仍可继续编辑,草稿会保留最近一次保存的内容。"
/>
</template>
```

### 不同类型

```vue preview
<script lang="ts" setup>
import { VAlert, VSpace } from "@halo-dev/components";
</script>

<template>
<VSpace direction="column" align="stretch">
<VAlert
type="success"
title="站点配置已更新"
description="新的 SEO 和缓存设置已经生效。"
/>
<VAlert
type="info"
title="发现新版本"
description="Halo 2.27.0 已发布,包含若干问题修复。"
/>
<VAlert
type="warning"
title="插件需要重新加载"
description="检测到插件配置发生变化,重新加载后才能应用到前台页面。"
/>
<VAlert
type="error"
title="同步失败"
description="远程内容源暂时不可用,请检查网络连接后重试。"
/>
</VSpace>
</template>
```

### 带操作按钮

```vue preview
<script lang="ts" setup>
import { VAlert, VButton, VSpace } from "@halo-dev/components";
</script>

<template>
<VAlert type="warning" title="存在未保存的更改">
<template #actions>
<VSpace spacing="sm">
<VButton size="sm" type="primary">保存</VButton>
<VButton size="sm">放弃</VButton>
</VSpace>
</template>
</VAlert>
</template>
```

### 不可关闭

```vue preview
<script lang="ts" setup>
import { VAlert } from "@halo-dev/components";
</script>

<template>
<VAlert
type="default"
title="只读模式"
description="当前账号没有修改权限。"
:closable="false"
/>
</template>
```

### 监听关闭事件

`VAlert` 不会自行隐藏,需要在 `close` 事件中控制显示状态。

```vue preview
<script lang="ts" setup>
import { ref } from "vue";
import { VAlert, VButton } from "@halo-dev/components";

const visible = ref(true);
</script>

<template>
<VSpace direction="column" align="start">
<VAlert
v-if="visible"
title="点击右侧关闭按钮可关闭此提示"
@close="visible = false"
/>
<VButton v-if="!visible" @click="visible = true">重新显示</VButton>
</VSpace>
</template>
```

## Props

| 属性 | 类型 | 默认值 | 说明 |
| ------------- | ---------------------------------------------------------- | ----------- | ------------------------ |
| `type` | `"default" \| "success" \| "info" \| "warning" \| "error"` | `"default"` | 提示类型,决定图标和配色 |
| `title` | `string` | `""` | 标题 |
| `description` | `string` | `""` | 描述内容 |
| `closable` | `boolean` | `true` | 是否显示关闭按钮 |

## Emits

| 事件 | 参数 | 说明 |
| ------- | ---- | ------------------------------------ |
| `close` | - | 点击关闭按钮时触发,不会自动隐藏提示 |

## Slots

| 插槽 | 说明 |
| ------------- | ---------------------------------------- |
| `icon` | 自定义图标,默认根据 `type` 显示对应图标 |
| `title` | 自定义标题 |
| `description` | 自定义描述内容 |
| `actions` | 操作区域,显示在描述下方 |
138 changes: 138 additions & 0 deletions docs/developer-guide/plugin/api-reference/ui/base-components/avatar.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
---
title: VAvatar 头像
description: 使用 VAvatar 和 VAvatarGroup 在 Halo 插件界面中展示用户或应用头像,支持尺寸、圆形、加载失败占位和头像组
---

头像用于展示用户、应用或站点的图片标识。`VAvatar` 在图片加载失败时会显示 `alt` 的首字母作为占位,`VAvatarGroup` 用于把多个头像组合在一起。

## 引入

```ts
import { VAvatar, VAvatarGroup } from "@halo-dev/components";
```

## 示例

### 基础用法

```vue preview
<script lang="ts" setup>
import { VAvatar } from "@halo-dev/components";

const avatar = "https://www.halo.run/logo";
</script>

<template>
<VAvatar :src="avatar" alt="Halo" />
</template>
```

### 不同尺寸

```vue preview
<script lang="ts" setup>
import { VAvatar, VSpace } from "@halo-dev/components";

const avatar = "https://www.halo.run/logo";
</script>

<template>
<VSpace>
<VAvatar :src="avatar" alt="Halo" size="xs" />
<VAvatar :src="avatar" alt="Halo" size="sm" />
<VAvatar :src="avatar" alt="Halo" size="md" />
<VAvatar :src="avatar" alt="Halo" size="lg" />
</VSpace>
</template>
```

### 圆形头像

```vue preview
<script lang="ts" setup>
import { VAvatar } from "@halo-dev/components";

const avatar = "https://www.halo.run/logo";
</script>

<template>
<VAvatar :src="avatar" alt="Halo" circle />
</template>
```

### 无图片或加载失败

没有图片地址或图片无法加载时,会显示 `alt` 的首字母;没有 `alt` 时显示警告图标。

```vue preview
<script lang="ts" setup>
import { VAvatar, VSpace } from "@halo-dev/components";
</script>

<template>
<VSpace>
<VAvatar alt="Halo" />
<VAvatar />
</VSpace>
</template>
```

### 自定义尺寸

```vue preview
<script lang="ts" setup>
import { VAvatar } from "@halo-dev/components";

const avatar = "https://www.halo.run/logo";
</script>

<template>
<VAvatar :src="avatar" alt="Halo" width="64px" height="64px" circle />
</template>
```

### 头像组

`VAvatarGroup` 会统一应用尺寸和形状,并让相邻头像产生重叠效果。

```vue preview
<script lang="ts" setup>
import { VAvatar, VAvatarGroup } from "@halo-dev/components";

const avatar = "https://www.halo.run/logo";
</script>

<template>
<VAvatarGroup size="sm" circle>
<VAvatar :src="avatar" alt="Halo" />
<VAvatar :src="avatar" alt="Halo" />
<VAvatar :src="avatar" alt="Halo" />
</VAvatarGroup>
</template>
```

## VAvatar Props

| 属性 | 类型 | 默认值 | 说明 |
| -------- | ------------------------------ | ----------- | ------------------------------------------ |
| `src` | `string` | `undefined` | 图片地址 |
| `alt` | `string` | `undefined` | 图片替代文本,加载失败时取其首字母作为占位 |
| `size` | `"lg" \| "md" \| "sm" \| "xs"` | `"md"` | 头像尺寸 |
| `width` | `string` | `undefined` | 自定义宽度,优先级高于 `size` |
| `height` | `string` | `undefined` | 自定义高度,优先级高于 `size` |
| `circle` | `boolean` | `false` | 是否显示为圆形 |

## VAvatarGroup Props

| 属性 | 类型 | 默认值 | 说明 |
| -------- | ------------------------------ | ----------- | ----------------------------------------- |
| `size` | `"lg" \| "md" \| "sm" \| "xs"` | `"md"` | 组内头像尺寸,会覆盖 `VAvatar` 的同名属性 |
| `width` | `string` | `undefined` | 组内头像宽度 |
| `height` | `string` | `undefined` | 组内头像高度 |
| `circle` | `boolean` | `false` | 组内头像是否显示为圆形 |

## Slots

| 组件 | 插槽 | 说明 |
| -------------- | --------- | -------- |
| `VAvatarGroup` | `default` | 头像内容 |
Loading
Loading