docs(components): [affix] (#10345)

docs(components): [affix]

* Add lost exposed API to documentation.
* Refine code.
* Add descriptions for APIs.
* Refine implementation for `FunctionType` and `EnumType`.
* Update affix documentation based on the changes above.

Co-authored-by: JeremyWuuuuu <15975785+JeremyWuuuuu@users.noreply.github.com>

docs/.vitepress/vitepress/components/globals/vp-api-enum.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { computed } from 'vue'
+import { isString } from '@vue/shared'
 import ApiTyping from './vp-api-typing.vue'
 
 const props = defineProps({
@@ -9,7 +10,9 @@ const props = defineProps({
   },
 })
 
-const details = computed(() => props.values.join(' | '))
+const processString = (s: unknown) => (isString(s) ? `'${s}'` : s)
+
+const details = computed(() => props.values.map(processString).join(' | '))
 </script>
 
 <template>

docs/.vitepress/vitepress/components/globals/vp-api-function.vue

@@ -2,10 +2,17 @@
 import { computed } from 'vue'
 import ApiTyping from './vp-api-typing.vue'
 
+import type { PropType } from 'vue'
+
+type ParamType = [string, string]
+
 const props = defineProps({
+  /**
+   * @description params list, shape of Array<[key: string, value: string]>
+   */
   params: {
-    type: String,
-    default: '',
+    type: Array as PropType<Array<ParamType>>,
+    default: () => [],
   },
   returns: {
     type: String,
@@ -13,7 +20,16 @@ const props = defineProps({
   },
 })
 
-const details = computed(() => `(${props.params}) => ${props.returns}`)
+const mappedParams = computed(() =>
+  props.params
+    .reduce(
+      (params, [key, val]) => params.concat([`${key}: ${val}`]),
+      [] as string[]
+    )
+    .join(', ')
+)
+
+const details = computed(() => `(${mappedParams.value}) => ${props.returns}`)
 </script>
 
 <template>

docs/.vitepress/vitepress/components/globals/vp-api-typing.vue

@@ -9,11 +9,11 @@ defineProps({
 
 <template>
   <span class="flex items-center">
-    <code class="api-typing">
+    <code class="api-typing mr-1">
       {{ type }}
     </code>
     <el-tooltip effect="light" trigger="click">
-      <el-button text :icon="Warning" class="p-2 text-5" />
+      <el-button text :icon="Warning" class="p-2 text-4" />
       <template #content>
         <div class="m-1">
           <code>

docs/en-US/component/affix.md

@@ -41,25 +41,26 @@ affix/fixed
 
 ### Affix Attributes
 
-| Name       | Description                      | Type                | Default | Required |
-| ---------- | -------------------------------- | ------------------- | ------- | -------- |
-| `offset`   | offset distance.                 | `number`            | `0`     | No       |
-| `position` | position of affix.               | `'top' \| 'bottom'` | `'top'` | No       |
-| `target`   | target container. (CSS selector) | `string`            | —       | No       |
-| `z-index`  | `z-index` of affix               | `number`            | `100`   | No       |
+| Name       | Description                      | Type                                     | Default | Required |
+| ---------- | -------------------------------- | ---------------------------------------- | ------- | -------- |
+| `offset`   | offset distance.                 | `number`                                 | `0`     | No       |
+| `position` | position of affix.               | <EnumType :values="['top', 'bottom']" /> | `'top'` | No       |
+| `target`   | target container. (CSS selector) | `string`                                 | —       | No       |
+| `z-index`  | `z-index` of affix               | `number`                                 | `100`   | No       |
 
 ### Affix Events
 
-| Name     | Description                        | Type                                                     |
-| -------- | ---------------------------------- | -------------------------------------------------------- |
-| `change` | triggers when fixed state changed. | `(fixed: boolean) => void`                               |
-| `scroll` | triggers when scrolling.           | `(value: { scrollTop: number, fixed: boolean }) => void` |
+| Name     | Description                        | Type                                                                            |
+| -------- | ---------------------------------- | ------------------------------------------------------------------------------- |
+| `change` | triggers when fixed state changed. | <FunctionType :params="[['fixed', 'boolean']]" />                               |
+| `scroll` | triggers when scrolling.           | <FunctionType :params="[['value', '{ scrollTop: number, fixed: boolean }']]" /> |
 
 ### Affix Exposes
 
-| Method   | Description                 | Type         |
-| -------- | --------------------------- | ------------ |
-| `update` | update affix state manually | `() => void` |
+| Method       | Description                 | Type             |
+| ------------ | --------------------------- | ---------------- |
+| `update`     | update affix state manually | <FunctionType /> |
+| `updateRoot` | update rootRect info        | <FunctionType /> |
 
 ### Affix Slots
 

packages/components/affix/src/affix.ts

@@ -10,18 +10,30 @@ import type { ZIndexProperty } from 'csstype'
 import type Affix from './affix.vue'
 
 export const affixProps = buildProps({
+  /**
+   * @description affix element zIndex value
+   * */
   zIndex: {
     type: definePropType<ZIndexProperty>([Number, String]),
     default: 100,
   },
+  /**
+   * @description target container. (CSS selector)
+   */
   target: {
     type: String,
     default: '',
   },
+  /**
+   * @description offset distance
+   * */
   offset: {
     type: Number,
     default: 0,
   },
+  /**
+   * @description position of affix
+   * */
   position: {
     type: String,
     values: ['top', 'bottom'],

packages/components/affix/src/affix.vue

@@ -13,7 +13,7 @@ import {
   useEventListener,
   useWindowSize,
 } from '@vueuse/core'
-import { getScrollContainer, throwError } from '@element-plus/utils'
+import { addUnit, getScrollContainer, throwError } from '@element-plus/utils'
 import { useNamespace } from '@element-plus/hooks'
 import { affixEmits, affixProps } from './affix'
 import type { CSSProperties } from 'vue'
@@ -55,7 +55,7 @@ const rootStyle = computed<CSSProperties>(() => {
 const affixStyle = computed<CSSProperties>(() => {
   if (!fixed.value) return {}
 
-  const offset = props.offset ? `${props.offset}px` : 0
+  const offset = props.offset ? addUnit(props.offset) : 0
   return {
     height: `${rootHeight.value}px`,
     width: `${rootWidth.value}px`,