sard-uniapp 1.19.5 → 1.20.0

package/components/sticky/README.md

@@ -0,0 +1,92 @@
+---
+nav: 组件
+title: Sticky
+subtitle: 粘性布局
+group: 布局
+version: 1.20+
+---
+
+## 介绍
+
+粘性布局组件，用于在页面滚动时将元素固定在指定位置。
+
+css 的粘性定位有更好的性能和体验，如果能满足需求，则不需要使用 `Sticky` 组件。
+
+`Sticky` 组件通常用于需要粘性定位的元素受父元素范围限制的情景，因为 `Sticky` 组件能跳脱父元素的范围限制。
+
+@info
+
+需在模拟器或移动设备上查看效果，因为 `uni.createIntersectionObserver` 在 pc 端获取的数据是不正确的。
+
+@endinfo
+
+## 引入
+
+```ts
+import Sticky from 'sard-uniapp/components/sticky/sticky.vue'
+import StickyBox from 'sard-uniapp/components/sticky-box/sticky-box.vue'
+```
+
+## 代码演示
+
+### 吸顶
+
+使用 `offset-top` 设置粘性定位元素距离视窗顶部的距离。
+
+如果是自定义导航栏，则需要自行加上状态栏和导航栏的高度。
+
+黏住视窗状态时使用的是 `fixed` 定位。
+
+@code('${DEMO_PATH}/sticky/demo/OffsetTop.vue')
+
+### 动态插入
+
+即使是动态插入的数据，`Sticky` 组件也能重新计算其位置。
+
+@code('${DEMO_PATH}/sticky/demo/Dynamic.vue')
+
+### 吸底
+
+使用 `offset-bottom` 设置粘性定位元素距离视窗底部的距离。
+
+@code('${DEMO_PATH}/sticky/demo/OffsetBottom.vue')
+
+### 吸顶和吸底
+
+可以同时使用 `offset-top` 和 `offset-bottom` 设置粘性定位元素距离视窗顶部和底部的距离。
+
+@code('${DEMO_PATH}/sticky/demo/OffsetTopBottom.vue')
+
+### 容器中的吸顶
+
+如果要将元素限制在某个范围之内，可以使用 `StickyBox` 组件包裹着 `Sticky` 组件。
+
+黏住 `StickyBox` 组件状态时使用的是 `absolute` 定位，因此 `Sticky` 组件不能被其他含有响应其绝对定位于 `StickyBox` 的定位样式的元素包裹。
+
+@code('${DEMO_PATH}/sticky/demo/BoxTop.vue')
+
+### 容器中的吸底
+
+@code('${DEMO_PATH}/sticky/demo/BoxBottom.vue')
+
+### 容器中的吸顶和吸底
+
+@code('${DEMO_PATH}/sticky/demo/BoxTopBottom.vue')
+
+## API
+
+### StickyProps
+
+| 属性          | 描述             | 类型       | 默认值 |
+| ------------- | ---------------- | ---------- | ------ |
+| root-class    | 组件根元素类名   | string     | -      |
+| root-style    | 组件根元素样式   | StyleValue | -      |
+| offset-top    | 吸顶距离，单位px | number     | -      |
+| offset-bottom | 吸底距离，单位px | number     | -      |
+| z-index       | 粘性元素的层级   | number     | -      |
+
+### StickySlots
+
+| 插槽    | 描述           | 属性 |
+| ------- | -------------- | ---- |
+| default | 自定义默认内容 | -    |

package/components/sticky/common.d.ts

@@ -0,0 +1,15 @@
+import { type StyleValue } from 'vue';
+export interface StickyProps {
+    rootStyle?: StyleValue;
+    rootClass?: string;
+    offsetTop?: number;
+    offsetBottom?: number;
+    zIndex?: number | string;
+}
+export interface StickySlots {
+    default?(props: Record<string, never>): any;
+}
+export interface StickyEmits {
+}
+export interface StickyExpose {
+}

package/components/sticky/common.js

@@ -0,0 +1 @@
+export {};

package/components/sticky/index.d.ts

@@ -0,0 +1 @@
+export type { StickyProps, StickySlots, StickyEmits, StickyExpose, } from './common';

package/components/sticky/index.js

@@ -0,0 +1 @@
+export {};

package/components/sticky/index.scss

@@ -0,0 +1,18 @@
+@use '../style/base' as *;
+
+@include bem(sticky) {
+  @include b() {
+    display: block;
+  }
+
+  @include e(fixation) {
+    position: relative;
+    z-index: 1;
+  }
+
+  @include e(bound) {
+    position: absolute;
+    min-width: 1px;
+    min-height: 1px;
+  }
+}

package/components/sticky/sticky.d.ts

@@ -0,0 +1,10 @@
+import { type StickyProps, type StickySlots } from './common';
+declare function __VLS_template(): Readonly<StickySlots> & StickySlots;
+declare const __VLS_component: import("vue").DefineComponent<StickyProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<StickyProps> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, ReturnType<typeof __VLS_template>>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/components/sticky/sticky.vue

@@ -0,0 +1,190 @@
+<template>
+  <view :class="stickyClass" :style="stickyStyle">
+    <view :class="observeClass" :style="observeStyle">
+      <view :class="fixationClass" :style="fixationStyle">
+        <view :class="boundClass" :style="boundStyle">
+          <slot></slot>
+          <sar-resize-sensor initial :threshold="0" @resize="onResize" />
+        </view>
+      </view>
+    </view>
+  </view>
+</template>
+
+<script>
+import { defineComponent as _defineComponent } from "vue";
+import {
+  computed,
+  inject,
+  onBeforeMount,
+  onUnmounted,
+  reactive,
+  ref,
+  toRef
+} from "vue";
+import {
+  classNames,
+  stringifyStyle,
+  createBem,
+  uniqid,
+  isNumber
+} from "../../utils";
+import { useIntersectionObserver } from "../../use";
+import SarResizeSensor from "../resize-sensor/resize-sensor.vue";
+import { stickyContextSymbol } from "../sticky-box/common";
+/**
+ * @property {string} rootClass 组件根元素类名，默认值：-。
+ * @property {StyleValue} rootStyle 组件根元素样式，默认值：-。
+ * @property {number} offsetTop 吸顶距离，单位px，默认值：-。
+ * @property {number} offsetBottom 吸底距离，单位px，默认值：-。
+ * @property {number} zIndex 粘性元素的层级，默认值：-。
+ */
+export default  _defineComponent({
+  components: {
+    SarResizeSensor,
+  },
+  ...{
+    options: {
+      virtualHost: true,
+      styleIsolation: "shared"
+    }
+  },
+  __name: "sticky",
+  props: {
+    rootStyle: { type: [Boolean, null, String, Object, Array], required: false, skipCheck: true },
+    rootClass: { type: String, required: false },
+    offsetTop: { type: Number, required: false },
+    offsetBottom: { type: Number, required: false },
+    zIndex: { type: [Number, String], required: false }
+  },
+  setup(__props, { expose: __expose }) {
+    const props = __props;
+    const bem = createBem("sticky");
+    const observeId = uniqid();
+    const positionStyle = reactive({
+      position: "relative",
+      top: "",
+      bottom: ""
+    });
+    const boundingBox = ref("none");
+    const width = ref(null);
+    const height = ref(null);
+    const context = inject(stickyContextSymbol, null);
+    const size = computed(() => {
+      return {
+        width: width.value !== null ? width.value + "px" : "",
+        height: height.value !== null ? height.value + "px" : ""
+      };
+    });
+    const { recreate } = useIntersectionObserver(
+      (res) => {
+        const { intersectionRatio, relativeRect, boundingClientRect } = res;
+        Object.assign(positionStyle, {
+          position: "relative",
+          top: "",
+          bottom: ""
+        });
+        if (intersectionRatio < 1) {
+          if (isNumber(props.offsetTop) && boundingClientRect.top < relativeRect.top) {
+            positionStyle.position = "fixed";
+            positionStyle.top = props.offsetTop + "px";
+          } else if (isNumber(props.offsetBottom) && boundingClientRect.bottom > relativeRect.bottom) {
+            positionStyle.position = "fixed";
+            positionStyle.bottom = props.offsetBottom + "px";
+          }
+        }
+      },
+      {
+        selector: `.${observeId}`,
+        thresholds: [1],
+        offsetTop: toRef(() => props.offsetTop),
+        offsetBottom: toRef(() => props.offsetBottom)
+      }
+    );
+    let boxRecreate = null;
+    if (context) {
+      const { recreate: recreate2 } = useIntersectionObserver(
+        (res) => {
+          const { relativeRect, boundingClientRect } = res;
+          if (boundingClientRect.top > relativeRect.bottom) {
+            boundingBox.value = "top";
+          } else if (boundingClientRect.bottom < relativeRect.top) {
+            boundingBox.value = "bottom";
+          } else {
+            boundingBox.value = "none";
+          }
+        },
+        {
+          selector: `.${context.boxId}`,
+          thresholds: [0],
+          instance: context.instance,
+          offsetTop: toRef(() => (props.offsetTop || 0) + (height.value || 0)),
+          offsetBottom: toRef(
+            () => (props.offsetBottom || 0) + (height.value || 0)
+          )
+        }
+      );
+      boxRecreate = recreate2;
+    }
+    const onResize = (res) => {
+      width.value = res.width;
+      height.value = res.height;
+      recreate();
+    };
+    const onBoxResize = () => {
+      boxRecreate?.();
+    };
+    onBeforeMount(() => {
+      context?.onResize(onBoxResize);
+    });
+    onUnmounted(() => {
+      context?.offResize(onBoxResize);
+    });
+    __expose({});
+    const stickyClass = computed(() => {
+      return classNames(bem.b(), props.rootClass);
+    });
+    const stickyStyle = computed(() => {
+      return stringifyStyle(size.value, props.rootStyle);
+    });
+    const observeClass = computed(() => {
+      return classNames(bem.e("observe"), observeId);
+    });
+    const observeStyle = computed(() => {
+      return stringifyStyle(size.value);
+    });
+    const fixationClass = computed(() => {
+      return classNames(bem.e("fixation"));
+    });
+    const fixationStyle = computed(() => {
+      return stringifyStyle(
+        size.value,
+        {
+          zIndex: props.zIndex
+        },
+        boundingBox.value === "none" ? positionStyle : {
+          position: "absolute",
+          top: boundingBox.value === "top" ? 0 : "",
+          bottom: boundingBox.value === "bottom" ? 0 : ""
+        }
+      );
+    });
+    const boundClass = computed(() => {
+      return classNames(bem.e("bound"));
+    });
+    const boundStyle = computed(() => {
+      return stringifyStyle();
+    });
+    const __returned__ = { props, bem, observeId, positionStyle, boundingBox, width, height, context, size, recreate, get boxRecreate() {
+      return boxRecreate;
+    }, set boxRecreate(v) {
+      boxRecreate = v;
+    }, onResize, onBoxResize, stickyClass, stickyStyle, observeClass, observeStyle, fixationClass, fixationStyle, boundClass, boundStyle, SarResizeSensor };
+    return __returned__;
+  }
+});
+</script>
+
+<style lang="scss">
+@import './index.scss';
+</style>

package/components/sticky-box/common.d.ts

@@ -0,0 +1,19 @@
+import { type NodeRect } from '../../utils';
+import { type ComponentInternalInstance, type InjectionKey, type StyleValue } from 'vue';
+export interface StickyBoxProps {
+    rootStyle?: StyleValue;
+    rootClass?: string;
+}
+export interface StickyBoxSlots {
+    default?(props: Record<string, never>): any;
+}
+export interface StickyBoxEmits {
+}
+export interface StickyBoxExpose {
+}
+export declare const stickyContextSymbol: InjectionKey<{
+    boxId: string;
+    onResize: (callback: (res: NodeRect) => void) => void;
+    offResize: (callback: (res: NodeRect) => void) => void;
+    instance: ComponentInternalInstance;
+}>;

package/components/sticky-box/common.js

@@ -0,0 +1 @@
+export const stickyContextSymbol = Symbol('sticky-context');

package/components/sticky-box/index.d.ts

@@ -0,0 +1 @@
+export type { StickyBoxProps, StickyBoxSlots, StickyBoxEmits, StickyBoxExpose, } from './common';

package/components/sticky-box/index.js

@@ -0,0 +1 @@
+export {};

package/components/sticky-box/index.scss

@@ -0,0 +1,19 @@
+@use '../style/base' as *;
+
+@include bem(sticky-box) {
+  @include b() {
+    position: relative;
+    box-sizing: border-box;
+  }
+
+  @include e(observe) {
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    z-index: -9999;
+    pointer-events: none;
+    visibility: hidden;
+  }
+}

package/components/sticky-box/sticky-box.d.ts

@@ -0,0 +1,10 @@
+import { type StickyBoxProps, type StickyBoxSlots } from './common';
+declare function __VLS_template(): Readonly<StickyBoxSlots> & StickyBoxSlots;
+declare const __VLS_component: import("vue").DefineComponent<StickyBoxProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<StickyBoxProps> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, ReturnType<typeof __VLS_template>>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/components/sticky-box/sticky-box.vue

@@ -0,0 +1,82 @@
+<template>
+  <view :class="stickyBoxClass" :style="stickyBoxStyle">
+    <view :class="observeClass"></view>
+    <slot></slot>
+    <sar-resize-sensor initial :threshold="0" @resize="handleResize" />
+  </view>
+</template>
+
+<script>
+import { defineComponent as _defineComponent } from "vue";
+import { computed, getCurrentInstance, provide } from "vue";
+import {
+  classNames,
+  stringifyStyle,
+  createBem,
+  uniqid
+} from "../../utils";
+import {
+  stickyContextSymbol
+} from "./common";
+import SarResizeSensor from "../resize-sensor/resize-sensor.vue";
+export default  _defineComponent({
+  components: {
+    SarResizeSensor,
+  },
+  ...{
+    options: {
+      virtualHost: true,
+      styleIsolation: "shared"
+    }
+  },
+  __name: "sticky-box",
+  props: {
+    rootStyle: { type: [Boolean, null, String, Object, Array], required: false, skipCheck: true },
+    rootClass: { type: String, required: false }
+  },
+  setup(__props, { expose: __expose }) {
+    const props = __props;
+    const bem = createBem("sticky-box");
+    const boxId = uniqid();
+    const resizeHandlers = [];
+    const onResize = (handler) => {
+      const index = resizeHandlers.indexOf(handler);
+      if (index === -1) {
+        resizeHandlers.push(handler);
+      }
+    };
+    const offResize = (handler) => {
+      const index = resizeHandlers.indexOf(handler);
+      if (index !== -1) {
+        resizeHandlers.splice(index, 1);
+      }
+    };
+    const handleResize = (res) => {
+      resizeHandlers.forEach((handler) => handler(res));
+    };
+    const instance = getCurrentInstance();
+    provide(stickyContextSymbol, {
+      boxId,
+      onResize,
+      offResize,
+      instance
+    });
+    __expose({});
+    const stickyBoxClass = computed(() => {
+      return classNames(bem.b(), props.rootClass);
+    });
+    const stickyBoxStyle = computed(() => {
+      return stringifyStyle(props.rootStyle);
+    });
+    const observeClass = computed(() => {
+      return classNames(bem.e("observe"), boxId);
+    });
+    const __returned__ = { props, bem, boxId, resizeHandlers, onResize, offResize, handleResize, instance, stickyBoxClass, stickyBoxStyle, observeClass, SarResizeSensor };
+    return __returned__;
+  }
+});
+</script>
+
+<style lang="scss">
+@import './index.scss';
+</style>