第31期| 如何用vue3+ts封装一个将页面元素固定在特定可视区域的组件？

前言

    提到将元素固定在页面的特定区域，聪明的小伙伴们相信已经想到用固定定位fixed实现了，那如何用vue3+ts封装一个可以固定显示并且可视区域可以指定的组件呢？下面跟着element-plus的源码来实现一下~

组件介绍

• 功能
  【ElAffix】将页面元素固定在特定可视区域。
• 属性及方法

• 效果预览

源码下载

 git clone https://github.com/element-plus/element-plus.git
 cd element-plus
 pnpm install
 // 本地打开文档
 pnpm docs:dev
 // 本地运行例子
 pnpm run dev

源码分析

• vue-devtools打开源码
  

    首先运行 pnpm docs:dev本地打开文档，接着利用vue-devtools【版本为6.5.0】打开源码位置，如果是ts文件可以借助debugger调试，若是vue组件则借助vue-devtools会更直观一些~

• 入口文件index.ts

import { withInstall } from '@element-plus/utils'
import Affix from './src/affix.vue'
export const ElAffix = withInstall(Affix)
export default ElAffix
export * from './src/affix'

    入口文件的作用很简单，注册全局组件ElAffix，并且把相关属性暴露给外界使用

• affix.vue

<template>
  <!-- 组件 -->
  <div ref="root" :class="ns.b()" :style="rootStyle">
  <!-- 添加el-affix--fixed类名 -->
    <div :class="{ [ns.m('fixed')]: fixed }" :style="affixStyle">
      <!-- 内容插槽 -->
      <slot />
    </div>
  </div>
</template>

<script lang="ts" setup>
// 引入相关依赖
import { computed, onMounted, ref, shallowRef, watch, watchEffect } from 'vue'
import {
  useElementBounding,
  useEventListener,
  useWindowSize,
} from '@vueuse/core'
import { addUnit, getScrollContainer, throwError } from '@element-plus/utils'
import { useNamespace } from '@element-plus/hooks'
import { affixEmits, affixProps } from './affix'
import type { CSSProperties } from 'vue'
// 定义组件名
const COMPONENT_NAME = 'ElAffix'
defineOptions({
  name: COMPONENT_NAME,
})
// 支持属性
const props = defineProps(affixProps)
const emit = defineEmits(affixEmits)
// el-affix类名
const ns = useNamespace('affix')

const target = shallowRef<HTMLElement>()
const root = shallowRef<HTMLDivElement>()
const scrollContainer = shallowRef<HTMLElement | Window>()
const { height: windowHeight } = useWindowSize()
const {
  height: rootHeight,
  width: rootWidth,
  top: rootTop,
  bottom: rootBottom,
  update: updateRoot,
} = useElementBounding(root, { windowScroll: false })
const targetRect = useElementBounding(target)

const fixed = ref(false)
const scrollTop = ref(0)
const transform = ref(0)

const rootStyle = computed<CSSProperties>(() => {
  return {
    height: fixed.value ? `${rootHeight.value}px` : '',
    width: fixed.value ? `${rootWidth.value}px` : '',
  }
})

const affixStyle = computed<CSSProperties>(() => {
  if (!fixed.value) return {}

  const offset = props.offset ? addUnit(props.offset) : 0
  return {
    height: `${rootHeight.value}px`,
    width: `${rootWidth.value}px`,
    top: props.position === 'top' ? offset : '',
    bottom: props.position === 'bottom' ? offset : '',
    transform: transform.value ? `translateY(${transform.value}px)` : '',
    zIndex: props.zIndex,
  }
})

const update = () => {
  if (!scrollContainer.value) return
 // 这个元素的内容顶部（卷起来的）到它的视口可见内容（的顶部）的距离
  scrollTop.value =
    scrollContainer.value instanceof Window
      ? document.documentElement.scrollTop
      : scrollContainer.value.scrollTop || 0
// 改变translateY的值以及动态添加固定定位
  if (props.position === 'top') {
    if (props.target) {
      const difference =
        targetRect.bottom.value - props.offset - rootHeight.value
      fixed.value = props.offset > rootTop.value && targetRect.bottom.value > 0
      transform.value = difference < 0 ? difference : 0
    } else {
      fixed.value = props.offset > rootTop.value
    }
  } else if (props.target) {
    const difference =
      windowHeight.value -
      targetRect.top.value -
      props.offset -
      rootHeight.value
    fixed.value =
      windowHeight.value - props.offset < rootBottom.value &&
      windowHeight.value > targetRect.top.value
    transform.value = difference < 0 ? -difference : 0
  } else {
    fixed.value = windowHeight.value - props.offset < rootBottom.value
  }
}
// 滚动事件
const handleScroll = () => {
  updateRoot()
  emit('scroll', {
    scrollTop: scrollTop.value,
    fixed: fixed.value,
  })
}

watch(fixed, (val) => emit('change', val))

onMounted(() => {
  if (props.target) {
    target.value =
      document.querySelector<HTMLElement>(props.target) ?? undefined
    if (!target.value)
      throwError(COMPONENT_NAME, `Target is not existed: ${props.target}`)
  } else {
    target.value = document.documentElement
  }
  scrollContainer.value = getScrollContainer(root.value!, true)
  updateRoot()
})

useEventListener(scrollContainer, 'scroll', handleScroll)
watchEffect(update)
// 暴露update、updateRoot方法
defineExpose({
  /** @description update affix status */
  update,
  /** @description update rootRect info */
  updateRoot,
})
</script>

    通过分析affix.vue我们可以发现其原理主要是通过监听容器【不指定则为document】滚动事件动态给固定内容添加fixed定位来实现的，当在指定容器内滚动时，它主要做了以下事情【看gif图可能会更直观一些】：

1. 给根元素添加行内样式宽高
2. 给固钉元素添加固定定位，并添加行内样式width、height、top、bottom、transform、zIndex

值得一提的是，这里有用到vueuse的几个api，它们分别是：

• 获取边框的信息useElementBounding【height、width、bottom、top、left、right、x、y、update函数，对应的元素api为 Element.getBoundingClientRect()】
  
• 使用事件监听器useEventListener【其实就是EventTarget.addEventListener()】
• 使用窗口大小useWindowSize

总结

    今天阅读分析了ElAffix的源码实现，日常开发中可以借鉴的点是借助vueuse来加快开发效率，整体读下来其实就是咱们日常开发常用的一些方法，动态改style肯定都接触过，添加事件监听应该也不在话下，每一个强大的功能都是由日常的代码片段构成，阅读的代码量多了更利于理解各式各样的源码，实现更复杂的功能，正所谓“知道为何，就能迎接任何”。