改进组件，并且添加文档

InfernalAzazel · Sep 29, 2024 · 305ccfc · 305ccfc
1 parent 56e73f1
commit 305ccfc
Show file tree

Hide file tree

Showing 18 changed files with 309 additions and 62 deletions.
diff --git a/docs/cn/other/background.md b/docs/cn/other/background.md
@@ -1,5 +1,5 @@
 # ProBackground
 
-> 高级头像用于快速构建登陆页面背景
+> ProBackground 是一个 Vue 3 组件，用于在应用中创建一个带有动态波浪动画的背景。该组件根据当前主题（浅色模式或深色模式）动态调整背景和波浪的颜色，为页面提供一种美观的视觉效果。
 
 <demo path="./components/DemoProBackground" />
diff --git a/docs/cn/other/components/DemoProBackground.vue b/docs/cn/other/components/DemoProBackground.vue
@@ -5,10 +5,13 @@ title: 基础用法
 </docs>
 <script setup lang="ts"></script>
 <template>
-  <div>
-    <pro-background><div>这里可以是登陆表单内容</div></pro-background>
-  </div>
-
+  <pro-background>
+    <!-- 您的内容 -->
+    <div class="text-center text-white">
+      <h1>欢迎来到我的网站</h1>
+      <p>这是一个带有动态背景的示例页面</p>
+    </div>
+  </pro-background>
 </template>
 
 

diff --git a/docs/cn/other/components/DemoProTabs.vue b/docs/cn/other/components/DemoProTabs.vue
@@ -5,18 +5,27 @@ title: 基础用法
 </docs>
 <script lang="ts" setup>
 import {ref} from "vue";
+import type { ProTabData } from 'k-naiveui-pro'
+import {createDiscreteApi} from "naive-ui";
 
-const generateTabs = () => {
-  return Array.from({ length: 20 }, (_, i) => ({
-    icon: 'ion:ellipsis-vertical-sharp',
-    title: `Title ${i + 1}`
-  }))
+const { message} = createDiscreteApi(
+    ['message'],
+)
+
+const tabs = ref<ProTabData[]>([
+  { icon: 'mdi:home', title: '首页', path: '/home' },
+  { icon: 'mdi:account', title: '我的账户', path: '/account' },
+  { icon: 'mdi:settings', title: '设置', path: '/settings' }
+])
+
+function handleTabSelect(path: string) {
+  message.info(path)
 }
-const tabs = ref(generateTabs())
+
 </script>
 
 <template>
-  <ProTabs v-model="tabs"/>
+  <ProTabs v-model="tabs" @select="handleTabSelect" />
 </template>
 
 <style scoped>

diff --git a/docs/cn/other/components/DemoProTabs2.vue b/docs/cn/other/components/DemoProTabs2.vue
@@ -0,0 +1,27 @@
+<docs lang="md">
+---
+title: 自定义 `storageKey`
+---
+</docs>
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { ProTabData } from 'k-naiveui-pro'
+import {createDiscreteApi} from "naive-ui";
+
+const { message} = createDiscreteApi(
+    ['message'],
+)
+
+const tabs = ref<ProTabData[]>([
+  { icon: 'mdi:home', title: '首页', path: '/home' },
+  { icon: 'mdi:account', title: '我的账户', path: '/account' },
+  { icon: 'mdi:settings', title: '设置', path: '/settings' }
+])
+
+function handleTabSelect(path: string) {
+  message.info(path)
+}
+</script>
+<template>
+  <ProTabs v-model="tabs" storageKey="my-custom-tabs" @select="handleTabSelect" />
+</template>
diff --git a/docs/cn/other/components/DemoProToggleFullScreen.vue b/docs/cn/other/components/DemoProToggleFullScreen.vue
@@ -4,17 +4,10 @@ title: 基础用法
 ---
 </docs>
 <script lang="ts" setup>
-import {ref} from "vue";
-
-const fullscreenRef = ref<HTMLElement | null>(null)
 </script>
 
 <template>
-
-
-  <div ref="fullscreenRef">
-    <pro-toggle-full-screen :target="fullscreenRef"/>
-  </div>
+  <pro-toggle-full-screen/>
 </template>
 
 <style scoped>

diff --git a/docs/cn/other/components/DemoProToggleFullScreen2.vue b/docs/cn/other/components/DemoProToggleFullScreen2.vue
@@ -0,0 +1,22 @@
+<docs lang="md">
+---
+title: 指定需要全屏的元素
+---
+</docs>
+<script lang="ts" setup>
+import { ref } from 'vue'
+const fullscreenTarget = ref<HTMLElement | null>(null)
+
+</script>
+
+<template>
+  <pro-toggle-full-screen/>
+  <div ref="fullscreenTarget">
+    <!-- 需要全屏的内容 -->
+    <p>这是需要全屏显示的内容。</p>
+  </div>
+</template>
+
+<style scoped>
+
+</style>
diff --git a/docs/cn/other/components/DemoProToggleFullScreen3.vue b/docs/cn/other/components/DemoProToggleFullScreen3.vue
@@ -0,0 +1,17 @@
+<docs lang="md">
+---
+title: 自定义全屏和退出全屏的图标
+---
+</docs>
+<script lang="ts" setup></script>
+
+<template>
+  <pro-toggle-full-screen
+      fullScreenIcon="mdi:fullscreen"
+      exitFullScreenIcon="mdi:fullscreen-exit"
+  />
+</template>
+
+<style scoped>
+
+</style>
diff --git a/docs/cn/other/components/DemoProToggleLanguage.vue b/docs/cn/other/components/DemoProToggleLanguage.vue
@@ -4,21 +4,27 @@ title: 基础用法
 ---
 </docs>
 <script lang="ts" setup>
-const languageOptions = [
-  {
-    label: '中文',
-    key: 'zh-CN',
-  },
-  {
-    label: 'English',
-    key: 'en-US',
-  },
-]
+import {ref} from "vue";
+import  type {DropdownOption} from "naive-ui";
+import {createDiscreteApi} from "naive-ui";
 
+const { message} = createDiscreteApi(
+    ['message'],
+)
+
+const languageOptions = ref<DropdownOption[]>([
+  { label: 'English', key: 'en' },
+  { label: '中文', key: 'zh' },
+  { label: 'Español', key: 'es' }
+])
+function handleLanguageSelect(key: string | number) {
+  message.info(`选择的语言键值为：${key}`)
+  // 在这里处理语言切换的逻辑
+}
 </script>
 
 <template>
-  <pro-toggle-language :options="languageOptions"/>
+  <pro-toggle-language :options="languageOptions" @select="handleLanguageSelect"/>
 </template>
 
 <style scoped>

diff --git a/docs/cn/other/index.md b/docs/cn/other/index.md
@@ -1,5 +1,25 @@
 # ProAvatar
 
-> 高级头像用于快速构建用户或者管理员
+> `ProAvatar` 组件是一个包含头像和下拉菜单的组合组件，常用于导航栏的用户信息展示。它封装了 `n-avatar` 和 `n-dropdown` 组件，提供了自定义头像、用户名显示、下拉菜单选项等功能，支持灵活的配置和扩展。
+
+<demo path="./components/DemoProAvatar" />
+
+
+## Props
+
+| 参数      | 类型                                                                                              | 可选值                                   | 默认值             | 说明          |
+|---------|-------------------------------------------------------------------------------------------------|---------------------------------------|-----------------|-------------|
+| name    | `string`                                                                                        | —                                     | —               | 用户名，显示在头像旁边 |
+| options | `Array<DropdownOption \| DropdownGroupOption \| DropdownDividerOption \| DropdownRenderOption>` | —                                     | **必填**          | 下拉菜单的选项列表   |
+| src     | `string` \| `any`                                                                               | —                                     | `defaultAvatar` | 头像图片的资源地址   |
+| size    | `'small'` \| `'medium'` \| `'large'` \| `number`                                                | `'small'`、`'medium'`、`'large'`、number | `'medium'`      | 头像的尺寸       |
+| lazy    | `boolean`                                                                                       | `true`、`false`                        | `false`         | 是否开启图片懒加载   |
+| round   | `boolean`                                                                                       | `true`、`false`                        | `false`         | 头像是否为圆形     |
+
+## 事件
+
+| 事件名    | 回调参数                      | 说明                   |
+|--------|---------------------------|----------------------|
+| select | `(key: string \| number)` | 当选择下拉菜单项时触发，返回所选项的键值 |
+
 
-<demo path="./components/DemoProAvatar" />
diff --git a/docs/cn/other/tabs.md b/docs/cn/other/tabs.md
@@ -1,5 +1,30 @@
 # ProTabs
 
-> 高级选项用于快速构建Admin的选项部件
+> `ProTabs` 是一个用于显示和管理标签页的 Vue 3 组件，支持标签页的添加、切换、关闭等功能。组件支持持久化标签页状态，使用本地存储保存标签页的数据和选中的标签页索引，即使刷新页面，标签页的状态也能被恢复。
 
-<demo path="./components/DemoProTabs" />
+<demo path="./components/DemoProTabs" />
+
+<demo path="./components/DemoProTabs2" />
+
+## Props
+
+| 参数         | 类型             | 可选值 | 默认值         | 说明                             |
+|------------|----------------|-----|-------------|--------------------------------|
+| modelValue | `ProTabData[]` | —   | `[]`        | 绑定的标签页数据数组，使用 `v-model` 进行双向绑定 |
+| storageKey | `string`       | —   | `'proTabs'` | 本地存储的键名，用于保存标签页数据和选中状态         |
+
+## ProTabData 数据结构
+
+`ProTabData` 是表示单个标签页的数据结构，其属性如下：
+
+| 属性    | 类型       | 可选值 | 默认值 | 说明                |
+|-------|----------|-----|-----|-------------------|
+| icon  | `string` | —   | —   | 标签页的 iconify 图标名称 |
+| title | `string` | —   | —   | 标签页的标题文字          |
+| path  | `string` | —   | —   | 标签页对应的路由路径        |
+
+## 事件
+
+| 事件名    | 回调参数             | 说明                   |
+|--------|------------------|----------------------|
+| select | `(path: string)` | 当选择标签页时触发，返回所选标签页的路径 |
diff --git a/docs/cn/other/toggleFullScreen.md b/docs/cn/other/toggleFullScreen.md
@@ -1,5 +1,69 @@
 # ProToggleFullScreen
 
-> 高级选项用于快速构建Admin的选项部件
+> `ProToggleFullScreen` 是一个用于切换全屏状态的 Vue 3 组件。它依赖于 `@vueuse/core` 的 `useFullscreen` 组合式函数，实现对指定元素的全屏控制。组件会根据当前的全屏状态显示不同的图标，点击图标即可在全屏和退出全屏之间切换。
+
+<demo path="./components/DemoProToggleFullScreen" />
+
+
+## Props
+
+| 参数                 | 类型                | 可选值 | 默认值                                     | 说明                 |
+|--------------------|-------------------|-----|-----------------------------------------|--------------------|
+| target             | `MaybeElementRef` | —   | —                                       | 可选，需要全屏的目标元素，默认为文档 |
+| height             | `number`          | —   | `24`                                    | 图标的高度，单位为像素        |
+| width              | `number`          | —   | `24`                                    | 图标的宽度，单位为像素        |
+| fullScreenIcon     | `string`          | —   | `'ant-design:fullscreen-outlined'`      | 进入全屏状态时显示的图标       |
+| exitFullScreenIcon | `string`          | —   | `'ant-design:fullscreen-exit-outlined'` | 退出全屏状态时显示的图标       |
+
+
+
+## 使用示例
+
+### 基本用法
+
+```vue
+<template>
+  <ProToggleFullScreen />
+</template>
+
+<script setup lang="ts">
+import ProToggleFullScreen from './ProToggleFullScreen.vue'
+</script>
+```
+
+### 自定义全屏和退出全屏的图标
+
+```vue
+<template>
+  <ProToggleFullScreen
+    fullScreenIcon="mdi:fullscreen"
+    exitFullScreenIcon="mdi:fullscreen-exit"
+  />
+</template>
+
+<script setup lang="ts">
+import ProToggleFullScreen from './ProToggleFullScreen.vue'
+</script>
+```
+
+### 指定需要全屏的元素
+
+```vue
+<template>
+  <div ref="fullscreenTarget">
+    <!-- 需要全屏的内容 -->
+    <p>这是需要全屏显示的内容。</p>
+  </div>
+  <ProToggleFullScreen :target="fullscreenTarget" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import ProToggleFullScreen from './ProToggleFullScreen.vue'
+
+const fullscreenTarget = ref<HTMLElement | null>(null)
+</script>
+```
+
+---
 
-<demo path="./components/DemoProToggleFullScreen" />
diff --git a/docs/cn/other/toggleLanguage.md b/docs/cn/other/toggleLanguage.md
@@ -1,5 +1,21 @@
 # ProToggleLanguage
 
-> 高级选项用于快速构建Admin的选项部件
+> `ProToggleLanguage` 是一个用于语言切换的 Vue 3 组件。它使用 `naive-ui` 的 `n-dropdown` 组件和 `@iconify/vue` 的图标来显示语言选择菜单。用户可以通过点击图标打开下拉菜单，选择需要的语言。
 
-<demo path="./components/DemoProToggleLanguage" />
+<demo path="./components/DemoProToggleLanguage" />
+
+## Props
+
+| 参数      | 类型                                                                                              | 可选值 | 默认值              | 说明                 |
+|---------|-------------------------------------------------------------------------------------------------|-----|------------------|--------------------|
+| options | `Array<DropdownOption \| DropdownGroupOption \| DropdownDividerOption \| DropdownRenderOption>` | —   | `[]`             | 下拉菜单的选项列表          |
+| icon    | `string`                                                                                        | —   | `'mdi:language'` | 显示在语言切换按钮上的图标，可自定义 |
+| height  | `number`                                                                                        | —   | `24`             | 图标的高度，单位为像素        |
+| width   | `number`                                                                                        | —   | `24`             | 图标的宽度，单位为像素        |
+
+
+## 事件
+
+| 事件名    | 回调参数                      | 说明                   |
+|--------|---------------------------|----------------------|
+| select | `(key: string \| number)` | 当选择下拉菜单项时触发，返回所选项的键值 |
diff --git a/docs/cn/other/toggleTheme.md b/docs/cn/other/toggleTheme.md
@@ -1,4 +1,16 @@
-## ProToggleTheme
-> 高级选项用于快速构建Admin项部件
+# ProToggleTheme
 
-<demo path="./components/DemoProToggleTheme" />
+> `ProToggleTheme` 是一个用于切换主题（浅色模式和深色模式）的 Vue 3 组件。它使用 `@vueuse/core` 的 `useDark` 组合式函数，实现对应用主题的切换。组件会根据当前的主题状态显示不同的图标，用户可以自定义在不同主题状态下显示的图标。点击图标即可在浅色模式和深色模式之间切换。
+
+
+<demo path="./components/DemoProToggleTheme" />
+
+
+## Props
+
+| 参数       | 类型       | 可选值 | 默认值                          | 说明                 |
+|----------|----------|-----|------------------------------|--------------------|
+| moonIcon | `string` | —   | `'ant-design:moon-outlined'` | 深色模式下显示的图标，表示为月亮图标 |
+| sunIcon  | `string` | —   | `'ant-design:sun-outlined'`  | 浅色模式下显示的图标，表示为太阳图标 |
+| height   | `number` | —   | `24`                         | 图标的高度，单位为像素        |
+| width    | `number` | —   | `24`                         | 图标的宽度，单位为像素        |