@puresnake/snake-ui 0.0.0-stage → 0.0.1

package/components/snake-index-anchor/snake-index-anchor.vue

@@ -0,0 +1,83 @@
+<template>
+    <view class="snake-index-anchor__wrapper" :style="wrapperStyle">
+        <view :id="anchorId" class="snake-index-anchor" :class="[customClass, { 'is-active': active }]" :style="style">
+            <slot v-if="useSlot" />
+            <text v-else>{{ text || index }}</text>
+        </view>
+    </view>
+</template>
+<script setup lang="ts">
+/**
+ * @component IndexAnchor
+ * @description 定义 `IndexList` 中的分组位置，并根据父组件配置提供吸顶效果。
+ * @see /components/index-anchor
+ */
+
+import { computed, getCurrentInstance, inject, onBeforeUnmount, onMounted, watch } from 'vue';
+import { indexListKey } from '../snake-index-list/types';
+import type { IndexAnchorProps } from './types';
+defineOptions({ name: 'IndexAnchor', options: { virtualHost: true, styleIsolation: 'shared' } });
+const props = withDefaults(defineProps<IndexAnchorProps>(), {
+    text: '',
+    useSlot: false,
+    customClass: '',
+    customStyle: ''
+});
+const instance = getCurrentInstance();
+const list = inject(indexListKey);
+const anchorId = computed(() => list?.anchorId(props.index) ?? `snake-index-anchor-${props.index}`);
+const active = computed(() => list?.isActive(props.index) ?? false);
+const wrapperStyle = computed(() => list?.wrapperStyle(props.index) ?? {});
+const style = computed(() => [list?.anchorStyle(props.index) ?? {}, props.customStyle]);
+
+// 微信端选择器查询不能跨自定义组件边界，锚点需在自身作用域内测量并回报父级。
+onMounted(() => {
+    list?.registerAnchor(props.index);
+    measure();
+});
+onBeforeUnmount(() => list?.unregisterAnchor(props.index));
+watch(
+    () => props.index,
+    (value, previous) => {
+        if (previous !== undefined && previous !== value) list?.unregisterAnchor(previous);
+        list?.registerAnchor(value);
+        measure();
+    }
+);
+watch(
+    () => list?.measureToken.value,
+    () => measure()
+);
+
+/** 测量自身节点位置并回报父级：查询限定在自身模板内，跨端可靠。 */
+function measure() {
+    if (typeof uni === 'undefined' || !instance) return;
+    uni.createSelectorQuery()
+        .in(instance?.proxy as any)
+        .select('.snake-index-anchor__wrapper')
+        .boundingClientRect()
+        .exec((results: any[]) => {
+            const rect = results?.[0];
+            if (rect) {
+                list?.reportAnchor(props.index, { top: Number(rect.top) || 0, height: Number(rect.height) || 0 });
+            }
+        });
+}
+</script>
+<style scoped>
+.snake-index-anchor__wrapper {
+    position: relative;
+}
+.snake-index-anchor {
+    display: flex;
+    box-sizing: border-box;
+    width: 100%;
+    min-height: 64rpx;
+    align-items: center;
+    padding: 0 20rpx;
+    color: var(--snake-color-text, #303133);
+    font-size: 24rpx;
+    font-weight: 600;
+    background: var(--snake-color-background, #f5f6f8);
+}
+</style>

package/components/snake-index-anchor/types.ts

@@ -0,0 +1,14 @@
+import type { StyleValue } from '../../types/global';
+/** IndexAnchor 组件的公开属性。 */
+export interface IndexAnchorProps {
+    /** 当前数据项索引。 */
+    index: string | number;
+    /** 展示文本。 */
+    text?: string;
+    /** 是否使用默认插槽替代文本。 */
+    useSlot?: boolean;
+    /** 根节点自定义类名。 */
+    customClass?: string;
+    /** 根节点自定义样式。 */
+    customStyle?: StyleValue;
+}

package/components/snake-index-list/anchor-registry.ts

@@ -0,0 +1,80 @@
+import { ref, type Ref } from 'vue';
+import type { IndexAnchorRect, IndexValue } from './types';
+
+/** 自测回报的兜底等待时长；超时后按已回报数据聚合，避免死等。 */
+const COLLECT_TIMEOUT = 200;
+
+/**
+ * 锚点登记与自测回报的共享实现。
+ *
+ * 微信小程序的选择器查询不能跨自定义组件边界：锚点节点位于
+ * `snake-index-anchor` 自身模板内、又经由插槽渲染，列表侧
+ * `createSelectorQuery().in(list)` 永远查不到。因此改为锚点在自身
+ * 作用域内测量并回报，列表 / 面板在 collect() 中聚合。
+ */
+export function createAnchorRegistry() {
+    /** 自测轮次号：锚点监听到变化后重新测量。 */
+    const measureToken = ref(0);
+    /** 各锚点最近一次回报的几何信息（非响应式，聚合时机由 collect 控制）。 */
+    const rects = new Map<IndexValue, IndexAnchorRect>();
+    /** 已挂载锚点集合，collect 按其数量等待回报。 */
+    const registered = new Set<IndexValue>();
+    let waiter: { expected: number; received: Set<IndexValue>; done: boolean; resolve: () => void } | null = null;
+    let waiterTimer: ReturnType<typeof setTimeout> | undefined;
+
+    function registerAnchor(value: IndexValue) {
+        registered.add(value);
+    }
+
+    function unregisterAnchor(value: IndexValue) {
+        registered.delete(value);
+        rects.delete(value);
+    }
+
+    function reportAnchor(value: IndexValue, rect: IndexAnchorRect) {
+        rects.set(value, rect);
+        if (waiter && !waiter.done && registered.has(value) && !waiter.received.has(value)) {
+            waiter.received.add(value);
+            if (waiter.received.size >= waiter.expected) settle();
+        }
+    }
+
+    function settle() {
+        if (!waiter || waiter.done) return;
+        waiter.done = true;
+        if (waiterTimer) clearTimeout(waiterTimer);
+        const resolve = waiter.resolve;
+        waiter = null;
+        resolve();
+    }
+
+    /**
+     * 触发一轮锚点自测并等待全部已登记锚点回报。
+     * 无锚点或超时（200ms）时立即返回，调用方按现有数据聚合。
+     */
+    function collect(): Promise<void> {
+        if (waiter) settle();
+        const expected = registered.size;
+        if (!expected) return Promise.resolve();
+        measureToken.value += 1;
+        return new Promise(resolve => {
+            waiter = { expected, received: new Set(), done: false, resolve };
+            waiterTimer = setTimeout(settle, COLLECT_TIMEOUT);
+        });
+    }
+
+    return {
+        measureToken,
+        rects,
+        registerAnchor,
+        unregisterAnchor,
+        reportAnchor,
+        collect
+    };
+}
+
+/** createAnchorRegistry 返回的锚点登记器。 */
+export interface AnchorRegistry extends ReturnType<typeof createAnchorRegistry> {
+    /** 自测轮次号（响应式，供锚点监听）。 */
+    measureToken: Ref<number>;
+}

package/components/snake-index-list/snake-index-list.vue

@@ -0,0 +1,259 @@
+<template>
+    <view class="snake-index-list" :class="customClass" :style="customStyle">
+        <slot />
+        <view
+            v-if="indexList.length"
+            class="snake-index-list__rail"
+            :style="[{ zIndex: props.zIndex }, railStyle]"
+            aria-label="索引导航"
+            @touchstart.stop.prevent="touchSelect"
+            @touchmove.stop.prevent="touchSelect"
+            @touchend.stop.prevent="touching = false"
+            @touchcancel.stop.prevent="touching = false"
+        >
+            <view
+                v-for="(item, index) in indexList"
+                :key="`${item}-${index}`"
+                class="snake-index-list__key"
+                :class="{ 'is-active': activeIndex === index }"
+                :style="{ color: activeIndex === index ? activeColor : inactiveColor }"
+                @click="scrollTo(index)"
+            >
+                {{ item }}
+            </view>
+        </view>
+        <view
+            v-if="indexList.length"
+            class="snake-index-list__bubble"
+            :class="{ 'is-visible': touching }"
+            :style="{ zIndex: props.zIndex + 1 }"
+        >
+            {{ activeIndex >= 0 ? indexList[activeIndex] : '' }}
+        </view>
+    </view>
+</template>
+
+<script setup lang="ts">
+/**
+ * @component IndexList
+ * @description 跟随页面滚动的索引列表，通过右侧索引快速定位分组内容，并与 IndexAnchor 配合实现吸顶。
+ * @see /components/index-list
+ */
+
+import { computed, getCurrentInstance, nextTick, onMounted, provide, ref, toRef, watch, type CSSProperties } from 'vue';
+import zIndex from '../../libs/config/zIndex';
+import { createAnchorRegistry } from './anchor-registry';
+import { indexFromTouch, offsetTopPx, resolveIndex, indexListKey } from './types';
+import type { IndexListEmits, IndexListProps, IndexValue } from './types';
+
+defineOptions({ name: 'IndexList', options: { virtualHost: true, styleIsolation: 'shared' } });
+
+const props = withDefaults(defineProps<IndexListProps>(), {
+    indexList: () => [],
+    scrollTop: 0,
+    zIndex: zIndex.indexListSticky,
+    sticky: true,
+    offsetTop: 0,
+    activeColor: 'var(--snake-color-primary, #06D290)',
+    inactiveColor: 'var(--snake-color-text-muted, #909399)',
+    railStyle: '',
+    customClass: '',
+    customStyle: ''
+});
+const emit = defineEmits<IndexListEmits>();
+const instance = getCurrentInstance();
+const activeIndex = ref(-1);
+const touching = ref(false);
+const railTop = ref(0);
+const railHeight = ref(0);
+const listLeft = ref(0);
+const listWidth = ref(0);
+// 锚点位置由锚点组件自测回报（微信端父级查询跨不过自定义组件边界）。
+const registry = createAnchorRegistry();
+const anchorTops = ref<number[]>([]);
+const anchorHeights = ref<number[]>([]);
+const currentScrollTop = computed(() => Number(props.scrollTop) || 0);
+const currentOffsetTop = computed(() => offsetTopPx(props.offsetTop));
+const anchorId = (value: IndexValue) => `snake-index-anchor-${String(value).replace(/[^a-zA-Z0-9_-]/g, '-')}`;
+
+function setActive(index: number, selected = false) {
+    if (!props.indexList.length || index < 0 || index >= props.indexList.length) return;
+    if (index !== activeIndex.value) {
+        activeIndex.value = index;
+        emit('change', { index, value: props.indexList[index] });
+    }
+    if (selected) emit('select', props.indexList[index]);
+}
+
+function updateActive() {
+    if (!anchorTops.value.length) {
+        activeIndex.value = -1;
+        return;
+    }
+    const target = currentScrollTop.value + currentOffsetTop.value;
+    let index = -1;
+    anchorTops.value.forEach((top, position) => {
+        if (top <= target + 1) index = position;
+    });
+    if (index >= 0) setActive(index);
+    else activeIndex.value = -1;
+}
+
+function scrollTo(indexOrValue: number | IndexValue) {
+    const index = resolveIndex(indexOrValue, props.indexList);
+    if (index < 0) return;
+    setActive(index, true);
+    const top = anchorTops.value[index];
+    if (Number.isFinite(top)) {
+        uni.pageScrollTo({ duration: 0, scrollTop: Math.max(0, top - currentOffsetTop.value) });
+        return;
+    }
+    // 兜底：锚点尚未回报时按锚点 id 定位（微信 2.23.1+ / H5 / App 支持 selector）。
+    uni.pageScrollTo({ duration: 0, selector: `#${anchorId(props.indexList[index])}` } as UniApp.PageScrollToOptions);
+}
+
+function touchSelect(event: any) {
+    touching.value = true;
+    const y = Number(event.touches?.[0]?.clientY ?? event.changedTouches?.[0]?.clientY);
+    const index = indexFromTouch(y, railTop.value, railHeight.value, props.indexList.length);
+    if (index >= 0) scrollTo(index);
+}
+
+async function update() {
+    if (typeof uni === 'undefined') return;
+    await nextTick();
+    await new Promise<void>(resolve => {
+        const query = uni.createSelectorQuery().in(instance?.proxy as any);
+        query.select('.snake-index-list').boundingClientRect();
+        query.select('.snake-index-list__rail').boundingClientRect();
+        query.exec((results: any[]) => {
+            const list = results?.[0];
+            const rail = results?.[1];
+            if (list) {
+                listLeft.value = Number(list.left) || 0;
+                listWidth.value = Number(list.width) || 0;
+            }
+            if (rail) {
+                railTop.value = Number(rail.top) || 0;
+                railHeight.value = Number(rail.height) || 0;
+            }
+            resolve();
+        });
+    });
+    await registry.collect();
+    const tops: number[] = [];
+    const heights: number[] = [];
+    props.indexList.forEach(value => {
+        const rect = registry.rects.get(value);
+        // 未回报的锚点以 Infinity 占位，避免被滚动激活逻辑命中。
+        tops.push(rect ? rect.top + currentScrollTop.value : Number.POSITIVE_INFINITY);
+        heights.push(rect?.height || 0);
+    });
+    anchorTops.value = tops;
+    anchorHeights.value = heights;
+    updateActive();
+}
+
+function indexOfAnchor(value: IndexValue) {
+    return props.indexList.indexOf(value);
+}
+
+function anchorStyle(value: IndexValue): CSSProperties {
+    const index = indexOfAnchor(value);
+    if (!props.sticky || index < 0 || index !== activeIndex.value) return {};
+    const height = anchorHeights.value[index] || 0;
+    const nextTop = anchorTops.value[index + 1];
+    const nextViewportTop = nextTop === undefined ? Number.POSITIVE_INFINITY : nextTop - currentScrollTop.value;
+    const translateY = Math.min(0, nextViewportTop - currentOffsetTop.value - height);
+    return {
+        position: 'fixed',
+        top: `${currentOffsetTop.value}px`,
+        left: `${listLeft.value}px`,
+        width: `${listWidth.value}px`,
+        zIndex: props.zIndex,
+        color: props.activeColor,
+        transform: `translate3d(0, ${translateY}px, 0)`
+    };
+}
+
+function wrapperStyle(value: IndexValue): CSSProperties {
+    const index = indexOfAnchor(value);
+    return props.sticky && index === activeIndex.value ? { height: `${anchorHeights.value[index] || 0}px` } : {};
+}
+
+provide(indexListKey, {
+    activeIndex,
+    sticky: toRef(props, 'sticky'),
+    offsetTop: toRef(props, 'offsetTop'),
+    zIndex: toRef(props, 'zIndex'),
+    anchorId,
+    anchorStyle,
+    wrapperStyle,
+    isActive: value => indexOfAnchor(value) === activeIndex.value,
+    measureToken: registry.measureToken,
+    registerAnchor: registry.registerAnchor,
+    unregisterAnchor: registry.unregisterAnchor,
+    reportAnchor: registry.reportAnchor
+});
+
+watch(() => props.scrollTop, updateActive);
+watch(() => props.offsetTop, updateActive);
+watch(
+    () => props.indexList,
+    () => void update(),
+    { deep: true }
+);
+onMounted(() => void update());
+defineExpose({ scrollTo, update });
+</script>
+
+<style scoped>
+.snake-index-list {
+    position: relative;
+    box-sizing: border-box;
+}
+.snake-index-list__rail {
+    position: fixed;
+    top: 50%;
+    right: 10rpx;
+    display: flex;
+    flex-direction: column;
+    padding: 8rpx 0;
+    border-radius: 999px;
+    background: rgba(255, 255, 255, 0.86);
+    transform: translateY(-50%);
+    user-select: none;
+}
+.snake-index-list__key {
+    display: flex;
+    min-width: 44rpx;
+    min-height: 34rpx;
+    align-items: center;
+    justify-content: center;
+    border-radius: 50%;
+    font-size: 20rpx;
+    line-height: 34rpx;
+}
+.snake-index-list__key.is-active {
+    font-weight: 700;
+    background: var(--snake-color-primary-light, rgba(6, 210, 144, 0.1));
+}
+.snake-index-list__bubble {
+    position: fixed;
+    top: 50%;
+    right: 90rpx;
+    display: none;
+    width: 96rpx;
+    height: 96rpx;
+    align-items: center;
+    justify-content: center;
+    border-radius: 16rpx;
+    color: #fff;
+    font-size: 42rpx;
+    background: rgba(0, 0, 0, 0.58);
+    transform: translateY(-50%);
+}
+.snake-index-list__bubble.is-visible {
+    display: flex;
+}
+</style>

package/components/snake-index-list/types.ts

@@ -0,0 +1,115 @@
+import type { CSSProperties, InjectionKey, Ref } from 'vue';
+import type { UnitValue } from '../../libs/function/unit';
+import type { StyleValue } from '../../types/global';
+/** IndexValue 类型定义。 */
+export type IndexValue = string | number;
+
+/** 锚点自测的几何信息（视口坐标系）。 */
+export interface IndexAnchorRect {
+    /** 视口顶部到锚点顶部的距离，单位 px。 */
+    top: number;
+    /** 锚点高度，单位 px。 */
+    height: number;
+}
+/** IndexList 组件的公开属性。 */
+export interface IndexListProps {
+    /** index list 配置。 */
+    indexList?: IndexValue[];
+    /** 页面当前滚动距离，由页面的 onPageScroll 事件传入。 */
+    scrollTop?: number | string;
+    /** 组件层级。 */
+    zIndex?: number;
+    /** sticky 配置。 */
+    sticky?: boolean;
+    /** 吸顶或定位的顶部偏移量。 */
+    offsetTop?: UnitValue;
+    /** 激活状态颜色。 */
+    activeColor?: string;
+    /** 未激活状态颜色。 */
+    inactiveColor?: string;
+    /** rail style 配置。 */
+    railStyle?: StyleValue;
+    /** 根节点自定义类名。 */
+    customClass?: string;
+    /** 根节点自定义样式。 */
+    customStyle?: StyleValue;
+}
+/** IndexListChange 事件详情。 */
+export interface IndexListChangeDetail {
+    /** 当前数据项索引。 */
+    index: number;
+    /** 当前值。 */
+    value: IndexValue;
+}
+/** IndexList 组件的事件契约。 */
+export type IndexListEmits = {
+    /** select 事件携带的参数。 */
+    select: [value: IndexValue];
+    /** change 事件携带的参数。 */
+    change: [detail: IndexListChangeDetail];
+};
+/** IndexList 组件实例公开的方法和状态。 */
+export interface IndexListExpose {
+    /** scrollTo 方法。 */
+    scrollTo(index: number | IndexValue): void;
+    /** update 方法。 */
+    update(): Promise<void>;
+}
+
+/** IndexList 向 Anchor / Panel 注入的配对上下文。 */
+export interface IndexListContext {
+    /** 当前激活项下标。 */
+    activeIndex: Ref<number>;
+    /** 锚点是否吸顶。 */
+    sticky: Ref<boolean>;
+    /** 吸顶或定位的顶部偏移量。 */
+    offsetTop: Ref<string | number | null | undefined>;
+    /** 组件层级。 */
+    zIndex: Ref<number>;
+    /** 生成锚点节点 id。 */
+    anchorId(index: IndexValue): string;
+    /** 生成锚点样式。 */
+    anchorStyle(index: IndexValue): CSSProperties;
+    /** 生成分组容器样式。 */
+    wrapperStyle(index: IndexValue): CSSProperties;
+    /** 判断指定项是否激活。 */
+    isActive(index: IndexValue): boolean;
+    /** 自测轮次号：变化时锚点需重新测量并回报。 */
+    measureToken: Ref<number>;
+    /** 登记已挂载的锚点。 */
+    registerAnchor(value: IndexValue): void;
+    /** 注销锚点。 */
+    unregisterAnchor(value: IndexValue): void;
+    /** 锚点回报自身几何信息。 */
+    reportAnchor(value: IndexValue, rect: IndexAnchorRect): void;
+}
+
+/** IndexList ↔ Anchor / Panel 配对注入键。 */
+export const indexListKey: InjectionKey<IndexListContext> = Symbol('snake-index-list');
+
+/** 索引或取值解析为下标：合法整数下标原样返回，否则按值查找。 */
+export function resolveIndex(indexOrValue: number | IndexValue, indexList: IndexValue[]): number {
+    if (
+        typeof indexOrValue === 'number' &&
+        Number.isInteger(indexOrValue) &&
+        indexOrValue >= 0 &&
+        indexOrValue < indexList.length
+    ) {
+        return indexOrValue;
+    }
+    return indexList.indexOf(indexOrValue);
+}
+
+/** 由触摸纵坐标换算最近的数据项下标，越界自动收敛。 */
+export function indexFromTouch(clientY: number, railTop: number, railHeight: number, length: number): number {
+    if (!Number.isFinite(clientY) || railHeight <= 0 || length <= 0) return -1;
+    return Math.max(0, Math.min(length - 1, Math.floor(((clientY - railTop) / railHeight) * length)));
+}
+
+/** offsetTop 值转 px 数值：rpx / 裸数字按 rpx 换算。 */
+export function offsetTopPx(value: string | number | null | undefined): number {
+    const number = Number.parseFloat(String(value ?? 0));
+    if (!Number.isFinite(number)) return 0;
+    if (typeof value === 'string' && value.trim().endsWith('px')) return number;
+    return typeof uni !== 'undefined' && typeof uni.upx2px === 'function' ? uni.upx2px(number) : number;
+}