halo/docs
1
0
Fork 0
mirror of https://github.com/halo-dev/docs.git synced 2025-10-21 10:17:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update documentation for Halo 2.20 (#429)

Browse Source 
为 [Halo 2.20](https://github.com/halo-dev/halo/releases/tag/v2.20.0) 更新文档。

/kind documentation

```release-note
None
```
This commit is contained in:
Ryan Wang
2024-10-14 11:33:15 +08:00
committed by GitHub
parent f752dd74d7
commit 9876911e3a
185 changed files with 15652 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/annotations-form.md Normal file
View File

@@ -0,0 +1,55 @@
---
title: AnnotationsForm
description: 元数据表单组件
---
此组件用于提供统一的 [Annotations 表单](../../../../annotations-form.md)，可以根据 `group` 和 `kind` 属性自动渲染对应的表单项。
## 使用示例
```html
<script lang="ts" setup>
import { ref } from "vue"
const annotationsFormRef = ref()
const currentAnnotations = ref()
function handleSubmit () {
annotationsFormRef.value?.handleSubmit();
await nextTick();
const { customAnnotations, annotations, customFormInvalid, specFormInvalid } =
annotationsFormRef.value || {};
// 表单验证不通过
if (customFormInvalid || specFormInvalid) {
return;
}
// 合并自定义数据和表单提供的数据
const newAnnotations = {
...annotations,
...customAnnotations,
};
}
</script>
<template>
<AnnotationsForm
ref="annotationsFormRef"
:value="currentAnnotations"
kind="Post"
group="content.halo.run"
/>
<VButton @click="handleSubmit">提交</VButton>
</template>
```
## Props
| 属性名 | 类型 | 默认值 | 描述 |
|---------|------------------------------------|---------|-----------------------------------------|
| `group` | string | 无，必填 | 定义组件所属的分组。 |
| `kind` | string | 无，必填 | 定义组件的种类。 |
| `value` | \{ [key: string]: string; \} \| null \| null | 可选，包含键值对的对象或空值，用于存储数据。 |

25
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/attachment-file-type-icon.md Normal file
View File

@@ -0,0 +1,25 @@
---
title: AttachmentFileTypeIcon
description: 附件文件类型图标组件
---
此组件用于根据文件名显示文件类型图标。
## 使用示例
```html
<script lang="ts" setup></script>
<template>
<AttachmentFileTypeIcon fileName="example.png" />
</div>
```
## Props
| 属性名 | 类型 | 默认值 | 描述 |
|--------------|---------------------|-----------|------------------------------------|
| `fileName` | string \| undefined | undefined | 文件名，可以是字符串或未定义。 |
| `displayExt` | boolean | true | 可选，是否显示文件扩展名，默认为 true。 |
| `width` | number | 10 | 可选，组件宽度，默认为 10。 |
| `height` | number | 10 | 可选，组件高度，默认为 10。 |

50
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/attachment-selector-modal.md Normal file
View File

@@ -0,0 +1,50 @@
---
title: AttachmentSelectorModal
description: 附件选择组件
---
此组件用于调出附件选择器，以供用户选择附件。
:::info 注意
此组件当前仅在 Console 中可用。
:::
## 使用示例
```html
<script lang="ts" setup>
import { ref } from "vue"
const visible = ref(false)
function onAttachmentSelect (attachments: AttachmentLike[]) {
console.log(attachments)
}
</script>
<template>
<VButton @click="visible = true">选择附件</VButton>
<AttachmentSelectorModal
v-model:visible="visible"
@select="onAttachmentSelect"
/>
</template>
```
## Props
| 属性名 | 类型 | 默认值 | 描述 |
|-----------|----------|---------------|--------------------------|
| `visible` | boolean | false | 控制组件是否可见。 |
| `accepts` | string[] | () => ["*/*"] | 可选，定义可接受的文件类型。 |
| `min` | number | undefined | 可选，定义最小选择数量。 |
| `max` | number | undefined | 可选，定义最大选择数量。 |
## Emits
| 事件名称 | 参数 | 描述 |
|----------------|---------------------------------------------------|---------------------|
| update:visible | `visible`: boolean 类型，表示可见状态。 | 当可见状态更新时触发。 |
| close | 无 | 当弹框关闭时触发。 |
| select | `attachments`: AttachmentLike[] 类型，表示附件数组。 | 当选择确定按钮时触发。 |

18
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/filter-clean-button.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: FilterCleanButton
description: 过滤器清除按钮组件
---
## 使用示例
```html
<script lang="ts" setup>
function onClear () {
console.log("clear")
}
</script>
<template>
<FilterCleanButton @click="onClear" />
</template>
```

48
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/filter-dropdown.md Normal file
View File

@@ -0,0 +1,48 @@
---
title: FilterDropdown
description: 过滤器下拉组件
---
此组件为通用的下拉筛选组件，可以接收一个对象数组作为选项，并使用 `v-model` 绑定选择的值。
## 使用示例
```html
<script lang="ts" setup>
import { ref } from "vue"
const value = ref("")
const items = [
{
label: "最近创建",
value: "creationTimestamp,desc"
},
{
label: "较晚创建",
value: "creationTimestamp,asc"
}
]
</script>
<template>
<FilterDropdown
v-model="value"
label="排序"
:items="items"
/>
</template>
```
## Props
| 属性名 | 类型 | 默认值 | 描述 |
|--------------|-----------------------------------------------------------|-----------|--------------------------------------------------|
| `items` | \{ label: string; value?: string \| boolean \| number; \}[] | 无，必填 | 包含 `label` 和可选 `value` 的对象数组。 |
| `label` | string | 无，必填 | 组件的标签文本。 |
| `modelValue` | string \| boolean \| number | undefined | 可选，用于绑定到组件的值，可以是字符串、布尔值或数字。 |
## Emits
| 事件名称 | 参数 | 描述 |
|-------------------|--------------------------------------------------------|-------------------|
| update:modelValue | `modelValue`: string \| boolean \| number \| undefined | 当模型值更新时触发。 |

26
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/has-permission.md Normal file
View File

@@ -0,0 +1,26 @@
---
title: HasPermission
description: 权限判断组件
---
此组件用于根据权限控制元素的显示与隐藏。
## 使用方式
```html
<script lang="ts" setup>
import { VButton } from "@halo-dev/components"
</script>
<template>
<HasPermission :permissions="['system:posts:manage']">
<VButton type="danger">删除</VButton>
</HasPermission>
</template>
```
## Props
| 属性名 | 类型 | 默认值 | 描述 |
|---------------|----------|------|-----------------------|
| `permissions` | string[] | 无，必填 | 定义组件所需的权限列表。 |

42
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/index.md Normal file
View File

@@ -0,0 +1,42 @@
---
title: 组件
description: 在 Halo UI 中可使用的组件。
---
此文档将介绍所有在插件中可用的组件，以及它们的使用方法和区别。
## 基础组件库
我们为 Halo 的前端封装了一个基础组件的库，你可以在插件中使用这些组件。
安装方式：
```bash
pnpm install @halo-dev/components
```
在 Vue 组件中：
```html
<script lang="ts" setup>
import { VButton } from "@halo-dev/components";
</script>
<template>
<VButton>Hello</VButton>
</template>
```
所有可用的基础组件以及文档可查阅：[https://halo-ui-components.pages.dev](https://halo-ui-components.pages.dev)
## 业务组件和指令
除了基础组件库，我们还为 Halo 的前端封装了一些业务组件和指令，这些组件已经在全局注册，你可以直接在插件中使用这些组件和指令。
以下是所有可用的业务组件和指令：
```mdx-code-block
import DocCardList from '@theme/DocCardList';
<DocCardList />
```

30
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/plugin-detail-modal.md Normal file
View File

@@ -0,0 +1,30 @@
---
title: PluginDetailModal
description: 插件详情弹窗组件
---
此组件可以在 UI 部分的任意组件中打开差价的详情和设置弹窗，可以用于实现在不打断正常操作流程的情况下让用户查看和修改插件的详细信息。
## 使用方式
```html
<script lang="ts" setup>
import { ref } from "vue"
const modalVisible = ref(false)
function onPluginDetailModalClose() {
// Do something
}
</script>
<template>
<PluginDetailModal v-if="modalVisible" @close="onPluginDetailModalClose" name="starter" />
</template>
```
## Props
| 属性名 | 类型 | 默认值 | 描述 |
| ------ | ------ | -------- | --------------------------------------------- |
| `name` | string | 无，必填 | 插件名称，即 plugin.yaml 中的 `metadata.name` |

33
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/search-input.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: SearchInput
description: 搜索输入框组件
---
此组件适用于关键词搜索场景，输入数据的过程中不会触发搜索，只有在输入完成后，点击回车才会触发搜索。
## 使用方式
```html
<script lang="ts" setup>
import { ref } from "vue"
const keyword = ref("")
</script>
<template>
<SearchInput v-model="keyword" placeholder="请输入关键字" />
</template>
```
## Props
| 属性名 | 类型 | 默认值 | 描述 |
|---------------|--------|-----------|----------------------------------|
| `placeholder` | string | undefined | 可选，用于指定输入字段的占位符文本。 |
| `modelValue` | string | 无，必填 | 用于绑定输入字段的值。 |
## Emits
| 事件名称 | 参数 | 描述 |
|-------------------|-------------------------------------|-------------------|
| update:modelValue | `modelValue`: string 类型，表示模型值。 | 当模型值更新时触发。 |

47
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/uppy-upload.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: UppyUpload
description: 文件上传组件
---
## 使用方式
```html
<script lang="ts" setup>
const policyName = ref('my-test-policy')
const groupName = ref('my-test-group')
</script>
<template>
<UppyUpload
endpoint="/apis/api.console.halo.run/v1alpha1/attachments/upload"
:meta="{
policyName: policyName,
groupName: groupName,
}"
/>
</template>
```
## Props
| 属性名 | 类型 | 默认值 | 描述 |
|---------------------|----------------------------------------------------------------|-----------|------------------------------|
| `restrictions` | Restrictions | undefined | 可选，指定任何限制。 |
| `meta` | Record\<string, unknown\> | undefined | 可选，要发送的额外元数据。 |
| `autoProceed` | boolean | false | 可选，在某些操作后自动继续。 |
| `allowedMetaFields` | string[] | undefined | 可选，指定允许的元数据字段。 |
| `endpoint` | string | 无，必填 | 数据发送到的端点URL。 |
| `name` | string | file | 可选，用于上传的表单字段的名称。 |
| `note` | string | undefined | 可选，任何备注或描述。 |
| `method` | "GET" \| "POST" \| "PUT" \| "HEAD" \| "get" \| "post" \| "put" | post | 可选，用于请求的HTTP方法。 |
| `disabled` | boolean | false | 可选，如果为真，则禁用组件。 |
| `width` | string | 750px | 可选，组件的宽度。 |
| `height` | string | 550px | 可选，组件的高度。 |
| `doneButtonHandler` | () => void | undefined | 可选，完成时调用的处理函数。 |
## Emits
| 事件名称 | 参数 | 描述 |
|----------|------------------------------------------------------|---------------------|
| uploaded | `response`: SuccessResponse 类型，表示上传成功的响应。 | 当文件上传成功时触发。 |
| error | `file`: 出错的文件。<br />`response`: 出错时的响应数据。 | 当文件上传出错时触发。 |

36
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/v-codemirror.md Normal file
View File

@@ -0,0 +1,36 @@
---
title: VCodemirror
description: 代码编辑器组件
---
此组件封装了 Codemirror 代码编辑器，适用于一些需要编辑代码的场景。
## 使用方式
```html
<script lang="ts" setup>
import { ref } from "vue"
const value = ref("")
</script>
<template>
<VCodemirror v-model="value" height="300px" language="html" />
</template>
```
## Props
| 属性名 | 类型 | 默认值 | 描述 |
|--------------|-------------------------------------------------|----------|-------------------------------------------|
| `modelValue` | string | "" | 可选，绑定到组件的字符串值，默认为空字符串。 |
| `height` | string | auto | 可选，组件的高度，默认为 `"auto"`。 |
| `language` | keyof typeof presetLanguages \| LanguageSupport | yaml | 代码编辑器的语言支持，默认为 `"yaml"`。 |
| `extensions` | EditorStateConfig["extensions"] | () => [] | 可选，编辑器状态配置的扩展，默认为一个空数组。 |
## Emits
| 事件名称 | 参数 | 描述 |
|-------------------|----------------------------------|-------------------|
| update:modelValue | `value`: string 类型，表示模型值。 | 当模型值更新时触发。 |
| change | `value`: string 类型，表示变更的值。 | 当值发生变化时触发。 |

18
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/v-permission.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: v-permission
description: 权限指令
---
与 [HasPermission](./has-permission.md) 组件相同，此指令也是用于根据权限控制元素的显示与隐藏。
## 使用方式
```html
<script lang="ts" setup>
import { VButton } from "@halo-dev/components"
</script>
<template>
<VButton type="danger" v-permission="['system:posts:manage']">删除</VButton>
</template>
```

18
versioned_docs/version-2.20/developer-guide/plugin/api-reference/ui/components/v-tooltip.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: v-tooltip
description: Tooltip 指令
---
此指令用于在任何元素上添加一个提示框。
## 使用方式
```html
<script lang="ts" setup>
import { IconDeleteBin } from "@halo-dev/components"
</script>
<template>
<IconDeleteBin v-tooltip="'删除此文档'" />
</template>
```