@puresnake/snake-ui 0.0.0-stage → 0.0.1

package/components/snake-skeleton-item/types.ts

@@ -0,0 +1,30 @@
+import type { ComputedRef, InjectionKey } from 'vue';
+import type { StyleValue } from '../../types/global';
+
+/** SkeletonItem 的占位形态。 */
+export type SkeletonItemVariant = 'text' | 'rect' | 'circle' | 'image';
+
+/** SkeletonItem 组件的公开属性。 */
+export interface SkeletonItemProps {
+    /** 占位形态。 */
+    variant?: SkeletonItemVariant;
+    /** 占位宽度。 */
+    width?: number | string;
+    /** 占位高度。 */
+    height?: number | string;
+    /** 圆角尺寸。 */
+    radius?: number | string;
+    /** 是否启用流光动画；未传时继承 Skeleton 容器。 */
+    animated?: boolean;
+    /** 根节点自定义样式。 */
+    customStyle?: StyleValue;
+}
+
+/** Skeleton 向占位单元提供的上下文。 */
+export interface SkeletonContext {
+    /** 容器当前是否启用动画。 */
+    animated: ComputedRef<boolean>;
+}
+
+/** Skeleton 上下文注入键。 */
+export const SNAKE_SKELETON_CONTEXT: InjectionKey<SkeletonContext> = Symbol('snake-skeleton-context');

package/components/snake-slider/snake-slider.vue

@@ -0,0 +1,249 @@
+<template>
+    <view class="snake-slider" :class="[customClass, { 'is-disabled': disabled }]" :style="rootStyle">
+        <text v-if="showEdgeValue" class="snake-slider__edge">{{ minValue }}</text>
+        <view class="snake-slider__main">
+            <view
+                class="snake-slider__track"
+                :style="{ height: addUnit(height, 'rpx'), backgroundColor: inactiveColor }"
+                role="slider"
+                :aria-valuemin="minValue"
+                :aria-valuemax="maxValue"
+                :aria-valuenow="current"
+                :aria-disabled="disabled"
+                :tabindex="disabled ? -1 : 0"
+                @click="tap"
+                @keydown.left.prevent="adjust(-1)"
+                @keydown.down.prevent="adjust(-1)"
+                @keydown.right.prevent="adjust(1)"
+                @keydown.up.prevent="adjust(1)"
+                @touchstart.stop.prevent="start"
+                @touchmove.stop.prevent="move"
+                @touchend.stop.prevent="end"
+                @touchcancel.stop.prevent="end"
+            >
+                <view class="snake-slider__active" :style="activeStyle" />
+                <view class="snake-slider__block" :style="blockStyleValue">
+                    <slot v-if="useSlot || $slots.default" :value="current" />
+                </view>
+                <text
+                    v-if="showValue"
+                    class="snake-slider__value"
+                    :class="`is-${valuePosition}`"
+                    :style="{ left: `${percent}%` }"
+                >
+                    {{ current }}
+                </text>
+            </view>
+        </view>
+        <text v-if="showEdgeValue" class="snake-slider__edge">{{ maxValue }}</text>
+    </view>
+</template>
+<script setup lang="ts">
+/**
+ * @component Slider
+ * @description 通过轨道点击或触摸拖动选择数值，支持步长、数值气泡、边界值与自定义滑块。
+ * @see /components/slider
+ */
+
+import { computed, getCurrentInstance, inject, onMounted, ref, watch } from 'vue';
+import { addUnit } from '../../libs/function/unit';
+import { formItemKey } from '../snake-form-item/types';
+import type { SliderEmits, SliderExpose, SliderProps } from './types';
+defineOptions({ name: 'Slider', options: { virtualHost: true, styleIsolation: 'shared' } });
+const props = withDefaults(defineProps<SliderProps>(), {
+    modelValue: 0,
+    min: 0,
+    max: 100,
+    step: 1,
+    height: 6,
+    blockWidth: 30,
+    activeColor: 'var(--snake-color-primary,#06D290)',
+    inactiveColor: 'var(--snake-color-divider,#e4e7ed)',
+    blockColor: '#fff',
+    blockStyle: '',
+    disabled: false,
+    useSlot: false,
+    showValue: false,
+    valuePosition: 'top',
+    showEdgeValue: false,
+    customClass: '',
+    customStyle: ''
+});
+const emit = defineEmits<SliderEmits>();
+const formItem = inject(formItemKey, null);
+const instance = getCurrentInstance();
+const trackLeft = ref(0);
+const trackWidth = ref(0);
+const dragging = ref(false);
+const minValue = computed(() => Number(props.min) || 0);
+const maxValue = computed(() => Math.max(minValue.value, Number(props.max) || 0));
+const stepValue = computed(() => Math.max(Number(props.step) || 1, Number.EPSILON));
+function decimals(value: number) {
+    const text = String(value);
+    return text.includes('.') ? text.split('.')[1].length : 0;
+}
+function normalize(raw: unknown) {
+    const number = Number(raw);
+    const safe = Number.isFinite(number) ? number : minValue.value;
+    const stepped = minValue.value + Math.round((safe - minValue.value) / stepValue.value) * stepValue.value;
+    return Number(
+        Math.max(minValue.value, Math.min(maxValue.value, stepped)).toFixed(
+            Math.max(decimals(stepValue.value), decimals(minValue.value))
+        )
+    );
+}
+const current = ref(normalize(props.modelValue));
+watch(
+    () => props.modelValue,
+    value => {
+        if (!dragging.value) current.value = normalize(value);
+    }
+);
+const percent = computed(() =>
+    maxValue.value === minValue.value ? 0 : ((current.value - minValue.value) / (maxValue.value - minValue.value)) * 100
+);
+const rootStyle = computed(() => [
+    { padding: `${addUnit((Number.parseFloat(String(props.blockWidth)) || 30) / 2, 'rpx')} 0` },
+    props.customStyle
+]);
+const activeStyle = computed(() => ({ width: `${percent.value}%`, backgroundColor: props.activeColor }));
+const blockStyleValue = computed(() => [
+    {
+        left: `${percent.value}%`,
+        width: addUnit(props.blockWidth, 'rpx'),
+        height: addUnit(props.blockWidth, 'rpx'),
+        backgroundColor: props.blockColor
+    },
+    props.blockStyle
+]);
+async function update() {
+    if (typeof uni === 'undefined') return;
+    await new Promise<void>(resolve => {
+        uni.createSelectorQuery()
+            .in(instance?.proxy as any)
+            .select('.snake-slider__track')
+            .boundingClientRect((rect: any) => {
+                if (rect) {
+                    trackLeft.value = Number(rect.left) || 0;
+                    trackWidth.value = Number(rect.width) || 0;
+                }
+            })
+            .exec(() => resolve());
+    });
+}
+function clientX(event: any) {
+    return Number(
+        event.touches?.[0]?.clientX ?? event.changedTouches?.[0]?.clientX ?? event.detail?.x ?? event.clientX
+    );
+}
+function valueFromEvent(event: any) {
+    const x = clientX(event);
+    if (!Number.isFinite(x) || trackWidth.value <= 0) return current.value;
+    return normalize(minValue.value + ((x - trackLeft.value) / trackWidth.value) * (maxValue.value - minValue.value));
+}
+function setFromEvent(event: any, moving = false) {
+    const next = valueFromEvent(event);
+    if (next === current.value) return;
+    current.value = next;
+    emit('update:modelValue', next);
+    if (moving) emit('moving', next);
+}
+async function start(event: any) {
+    if (props.disabled) return;
+    if (!trackWidth.value) await update();
+    dragging.value = true;
+    setFromEvent(event);
+    emit('start', current.value);
+}
+function move(event: any) {
+    if (!dragging.value || props.disabled) return;
+    setFromEvent(event, true);
+}
+function end(event: any) {
+    if (!dragging.value || props.disabled) return;
+    setFromEvent(event);
+    dragging.value = false;
+    emit('end', current.value);
+    emit('change', current.value);
+    void formItem?.notify('change');
+}
+async function tap(event: any) {
+    if (props.disabled || dragging.value) return;
+    if (!trackWidth.value) await update();
+    setFromEvent(event);
+    emit('change', current.value);
+    void formItem?.notify('change');
+}
+function adjust(direction: -1 | 1) {
+    if (props.disabled) return;
+    const next = normalize(current.value + stepValue.value * direction);
+    if (next === current.value) return;
+    current.value = next;
+    emit('update:modelValue', next);
+    emit('change', next);
+    void formItem?.notify('change');
+}
+onMounted(() => void update());
+defineExpose<SliderExpose>({ update });
+</script>
+<style scoped>
+.snake-slider {
+    display: flex;
+    width: 100%;
+    align-items: center;
+    gap: 18rpx;
+}
+.snake-slider.is-disabled {
+    opacity: 0.45;
+}
+.snake-slider__main {
+    flex: 1;
+    min-width: 0;
+    padding: 28rpx 0;
+}
+.snake-slider__track {
+    position: relative;
+    border-radius: 999px;
+}
+.snake-slider__track:focus-visible {
+    outline: 2px solid var(--snake-color-primary, #06d290);
+    outline-offset: 8rpx;
+}
+.snake-slider__active {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    border-radius: inherit;
+}
+.snake-slider__block {
+    position: absolute;
+    top: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 50%;
+    box-shadow: 0 2rpx 12rpx rgba(15, 30, 24, 0.2);
+    transform: translate(-50%, -50%);
+}
+.snake-slider__value {
+    position: absolute;
+    padding: 4rpx 10rpx;
+    border-radius: 8rpx;
+    color: #fff;
+    font-size: 20rpx;
+    line-height: 1.2;
+    background: rgba(15, 30, 24, 0.76);
+    transform: translateX(-50%);
+}
+.snake-slider__value.is-top {
+    bottom: 22rpx;
+}
+.snake-slider__value.is-bottom {
+    top: 22rpx;
+}
+.snake-slider__edge {
+    color: var(--snake-color-text-muted, #909399);
+    font-size: 24rpx;
+}
+</style>

package/components/snake-slider/types.ts

@@ -0,0 +1,59 @@
+import type { UnitValue } from '../../libs/function/unit';
+import type { StyleValue } from '../../types/global';
+/** SliderValuePosition 类型定义。 */
+export type SliderValuePosition = 'top' | 'bottom';
+/** Slider 组件的公开属性。 */
+export interface SliderProps {
+    /** 双向绑定的当前值。 */
+    modelValue?: number | string;
+    /** 允许设置的最小值。 */
+    min?: number | string;
+    /** 允许设置的最大值。 */
+    max?: number | string;
+    /** 每次变化的步长。 */
+    step?: number | string;
+    /** 组件高度。 */
+    height?: UnitValue;
+    /** block width 配置。 */
+    blockWidth?: UnitValue;
+    /** 激活状态颜色。 */
+    activeColor?: string;
+    /** 未激活状态颜色。 */
+    inactiveColor?: string;
+    /** block color 配置。 */
+    blockColor?: string;
+    /** block style 配置。 */
+    blockStyle?: StyleValue;
+    /** 是否禁用交互。 */
+    disabled?: boolean;
+    /** 是否使用默认插槽替代文本。 */
+    useSlot?: boolean;
+    /** show value 配置。 */
+    showValue?: boolean;
+    /** value position 配置。 */
+    valuePosition?: SliderValuePosition;
+    /** show edge value 配置。 */
+    showEdgeValue?: boolean;
+    /** 根节点自定义类名。 */
+    customClass?: string;
+    /** 根节点自定义样式。 */
+    customStyle?: StyleValue;
+}
+/** Slider 组件的事件契约。 */
+export type SliderEmits = {
+    /** update:modelValue 事件携带的参数。 */
+    'update:modelValue': [value: number];
+    /** change 事件携带的参数。 */
+    change: [value: number];
+    /** start 事件携带的参数。 */
+    start: [value: number];
+    /** moving 事件携带的参数。 */
+    moving: [value: number];
+    /** end 事件携带的参数。 */
+    end: [value: number];
+};
+/** Slider 组件实例公开的方法和状态。 */
+export interface SliderExpose {
+    /** update 方法。 */
+    update(): Promise<void>;
+}

package/components/snake-sticky/snake-sticky.vue

@@ -0,0 +1,178 @@
+<template>
+    <view class="snake-sticky">
+        <view class="snake-sticky__wrap" :class="[elClass, customClass]" :style="placeholderStyle">
+            <view class="snake-sticky__content" :style="contentStyle">
+                <slot />
+            </view>
+        </view>
+    </view>
+</template>
+
+<script setup lang="ts">
+/**
+ * @component Sticky
+ * @description 通过 IntersectionObserver 相对视口观察占位层实现跨端吸顶，采用三层结构（外层容器 / 占位层 / 内容层），并在不支持 Observer 的环境降级为页面 scrollTop 定位。
+ * @see /components/sticky
+ */
+
+import { onPageScroll } from '@dcloudio/uni-app';
+import {
+    computed,
+    getCurrentInstance,
+    nextTick,
+    onBeforeUnmount,
+    onMounted,
+    ref,
+    watch,
+    type CSSProperties
+} from 'vue';
+import { getRect } from '../../libs/function/getRect';
+import { guid } from '../../libs/function/guid';
+import type { StickyEmits, StickyProps } from './types';
+
+defineOptions({ name: 'Sticky', options: { virtualHost: true, styleIsolation: 'shared' } });
+
+const props = withDefaults(defineProps<StickyProps>(), {
+    offsetTop: 0,
+    customNavHeight: 0,
+    zIndex: 10,
+    disabled: false,
+    bgColor: 'transparent',
+    scrollTop: 0,
+    index: 0,
+    customClass: '',
+    customStyle: ''
+});
+const emit = defineEmits<StickyEmits>();
+const instance = getCurrentInstance();
+
+const fixed = ref(false);
+const height = ref(0);
+const width = ref(0);
+const left = ref(0);
+// 页面绝对定位的原始位置，仅用于降级方案。
+const originTop = ref(0);
+const currentScrollTop = ref(props.scrollTop);
+
+// 每个实例唯一类名，用于测量和观察占位层，避免 CMS 循环中多个实例互相串扰。
+const elClass = guid('snake-sticky');
+// 是否支持 IntersectionObserver（H5 / 微信小程序 / App 均支持）。
+const supportsObserver = typeof uni !== 'undefined' && typeof uni.createIntersectionObserver === 'function';
+
+let contentObserver: any = null;
+
+function unitNumber(value: number | string | null | undefined) {
+    const number = Number.parseFloat(String(value ?? 0));
+    return Number.isFinite(number) ? number : 0;
+}
+function offsetTopPx(value: number | string | null | undefined) {
+    const number = unitNumber(value);
+    if (typeof value === 'string' && value.trim().endsWith('px')) return number;
+    return typeof uni !== 'undefined' && typeof uni.upx2px === 'function' ? uni.upx2px(number) : number;
+}
+// 正规化 disabled，避免宿主把 "false" 字符串传进来后被当成 true。
+const isDisabled = computed(() => {
+    // CMS 数据可能传入字符串布尔值，公共类型保持 boolean，此处按 unknown 归一化。
+    const value = props.disabled as unknown;
+    return value === true || value === 1 || value === '1' || value === 'true';
+});
+const stickyTop = computed(() => offsetTopPx(props.offsetTop) + unitNumber(props.customNavHeight));
+const placeholderStyle = computed(() => ({ height: fixed.value ? `${height.value}px` : 'auto' }));
+const contentStyle = computed(() => [
+    (fixed.value
+        ? { position: 'fixed', top: `${stickyTop.value}px`, left: `${left.value}px`, width: `${width.value}px` }
+        : { position: 'static' }) as CSSProperties,
+    { zIndex: props.zIndex, backgroundColor: props.bgColor },
+    props.customStyle
+]);
+
+async function setFixed(value: boolean) {
+    if (fixed.value === value) return;
+    // 吸顶瞬间补一次测量：内容（如 CMS 筛选数据）异步渲染时，挂载期重试可能仍测到 0。
+    // 此刻 fixed 尚未应用、占位层仍在文档流中，测得的就是真实高宽。
+    if (value) await measure();
+    fixed.value = value;
+    const detail = { isFixed: value, index: props.index };
+    if (value) emit('fixed', detail);
+    else emit('unfixed', detail);
+    emit('change', detail);
+}
+
+function disconnectObserver() {
+    if (contentObserver) {
+        contentObserver.disconnect();
+        contentObserver = null;
+    }
+}
+
+function observeContent() {
+    disconnectObserver();
+    contentObserver = uni.createIntersectionObserver(instance?.proxy as any, { thresholds: [0.95, 0.98, 1] });
+    contentObserver.relativeToViewport({ top: -stickyTop.value });
+    contentObserver.observe(`.${elClass}`, (res: any) => {
+        if (isDisabled.value) return;
+        setFixed(res.boundingClientRect.top < stickyTop.value);
+    });
+}
+
+// 降级方案：基于页面 scrollTop 手动计算是否吸顶。
+function updatePosition(scrollTop = currentScrollTop.value) {
+    currentScrollTop.value = scrollTop;
+    setFixed(!isDisabled.value && scrollTop + stickyTop.value >= originTop.value);
+}
+
+async function measure() {
+    const rect = await getRect(`.${elClass}`, instance);
+    if (!rect || !rect.height) return false;
+    height.value = Number(rect.height) || height.value;
+    width.value = Number(rect.width) || width.value;
+    left.value = Number(rect.left) || 0;
+    originTop.value = Number(rect.top) + currentScrollTop.value;
+    return true;
+}
+
+async function update() {
+    await nextTick();
+    if (isDisabled.value) return;
+    if (typeof uni === 'undefined' || typeof uni.createSelectorQuery !== 'function') return;
+    // 兼容 MP 首屏异步内容/布局未完成时测量为 0 的情况：最多重试 5 次，避免首次拿到 0 就直接放弃。
+    for (let attempt = 0; attempt < 5; attempt++) {
+        if (await measure()) break;
+        await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    nextTick(() => {
+        if (supportsObserver) observeContent();
+        else updatePosition();
+    });
+}
+
+watch(
+    () => props.offsetTop,
+    () => {
+        if (!isDisabled.value) void update();
+    }
+);
+watch(
+    () => isDisabled.value,
+    disabled => {
+        if (disabled) {
+            setFixed(false);
+            disconnectObserver();
+        } else {
+            void update();
+        }
+    }
+);
+watch(
+    () => props.scrollTop,
+    value => {
+        if (!supportsObserver) updatePosition(Number(value) || 0);
+    }
+);
+onPageScroll(event => {
+    if (!supportsObserver) updatePosition(Number(event.scrollTop) || 0);
+});
+onMounted(() => void update());
+onBeforeUnmount(disconnectObserver);
+defineExpose({ update });
+</script>

package/components/snake-sticky/types.ts

@@ -0,0 +1,48 @@
+import type { UnitValue } from '../../libs/function/unit';
+import type { StyleValue } from '../../types/global';
+
+/** Sticky 组件的公开属性。 */
+export interface StickyProps {
+    /** 吸顶或定位的顶部偏移量，数值按 rpx 处理，带 px 后缀时按 px 处理。 */
+    offsetTop?: UnitValue;
+    /** 自定义导航栏高度，单位 px。 */
+    customNavHeight?: UnitValue;
+    /** 组件层级。 */
+    zIndex?: number;
+    /** 是否禁用交互。 */
+    disabled?: boolean;
+    /** 背景颜色。 */
+    bgColor?: string;
+    /** 页面或容器当前滚动距离。 */
+    scrollTop?: number;
+    /** 当前数据项索引。 */
+    index?: number | string;
+    /** 根节点自定义类名。 */
+    customClass?: string;
+    /** 根节点自定义样式。 */
+    customStyle?: StyleValue;
+}
+
+/** StickyChange 事件详情。 */
+export interface StickyChangeDetail {
+    /** is fixed 配置。 */
+    isFixed: boolean;
+    /** 当前数据项索引。 */
+    index: number | string;
+}
+
+/** Sticky 组件的事件契约。 */
+export type StickyEmits = {
+    /** fixed 事件携带的参数。 */
+    fixed: [detail: StickyChangeDetail];
+    /** unfixed 事件携带的参数。 */
+    unfixed: [detail: StickyChangeDetail];
+    /** change 事件携带的参数。 */
+    change: [detail: StickyChangeDetail];
+};
+
+/** Sticky 组件实例公开的方法和状态。 */
+export interface StickyExpose {
+    /** update 方法。 */
+    update(): Promise<void>;
+}