Merge branch 'feature/composables' into optimize

src/components/Start.vue

@@ -1,36 +0,0 @@
-<script setup lang="ts">
-import { registerVisitorMethod } from '@/request/api';
-import { Notify } from '@/platform';
-import { useFlowStore, useVisitor } from '@/stores';
-
-const Visitor = useVisitor();
-const Flow = useFlowStore();
-const { flow } = storeToRefs(Flow);
-const handle = async () => {
-  Visitor.$reset();
-  if (flow.value.next === '/register' || (await register())) await Flow.router.push();
-};
-
-const registering = ref(false);
-const register = async () => {
-  registering.value = true;
-  try {
-    Visitor.patientId = await registerVisitorMethod().send(true);
-  } catch (error: any) {
-    Notify.error(error.message);
-  }
-  registering.value = false;
-  return Visitor.patientId;
-};
-</script>
-
-<template>
-  <div class="van-button decorate" @click="!registering && handle()">
-    <div class="van-button__content">
-      <van-loading v-if="registering" />
-      <span v-else class="van-button__text">开始检测</span>
-    </div>
-  </div>
-</template>
-
-<style scoped lang="scss"></style>

src/composables/FloatPanel/FloatPanel.vue

@@ -0,0 +1,327 @@
+<script setup lang="ts">
+/**
+ * 浮动面板展示层：组合 Vant Overlay + FloatingPanel，关闭动画与 CSS 变量。
+ * 锚点合并 / autoHeight 逻辑见 `floatPanelAnchors.ts`、`useFloatPanelAnchorsAutoHeight.ts`。
+ */
+import { computed, nextTick, onUpdated, ref, watch, watchPostEffect } from 'vue';
+import { useElementSize } from '@vueuse/core';
+import { computeAnchorsAndSnapHeight } from './floatPanelAnchors';
+import type { FloatPanelInstance, FloatPanelProps } from './types';
+import { useFloatPanelAnchorsAutoHeight } from './useFloatPanelAnchorsAutoHeight';
+
+// --- props（v-model：panel-height / panel-anchor）---
+const {
+  closeOnClickOverlay,
+  overlay = true,
+  overlayClass,
+  overlayStyle,
+
+  containerClass,
+  containerStyle,
+
+  title,
+  maxContainerHeight = innerHeight,
+  full = false,
+  closable = false,
+
+  contentDraggable = true,
+
+  autoHeight = false,
+
+  duration = 0.3,
+} = defineProps<FloatPanelProps>();
+
+// --- 动画：秒 -> 数值；与 Vant `duration`、关闭收尾定时器共用 ---
+const durationSec = computed(() => {
+  const n = Number(duration);
+  return Number.isFinite(n) && n >= 0 ? n : 0.3;
+});
+
+/** 关闭动画期间保持遮罩，避免 height 已为 0 时立刻隐藏打断过渡 */
+const isClosing = ref(false);
+const closeTimer = ref<ReturnType<typeof setTimeout> | null>(null);
+
+function clearCloseTimer() {
+  if (closeTimer.value != null) {
+    clearTimeout(closeTimer.value);
+    closeTimer.value = null;
+  }
+}
+
+onBeforeUnmount(() => {
+  clearCloseTimer();
+  isClosing.value = false;
+});
+
+// --- 样式 class ---
+const overlayClassList = computed(() => {
+  const value = Array.isArray(overlay) ? overlayClass : overlayClass ? [overlayClass] : [];
+  return ['float-panel-overlay', ...value, { hide: !overlay }];
+});
+const containerClassList = computed(() => {
+  const value = Array.isArray(containerClass) ? containerClass : containerClass ? [containerClass] : [];
+  return ['float-panel-container', ...value, { 'float-panel--auto-height': autoHeight }];
+});
+
+const height = defineModel<number>('panel-height', { default: 20 });
+const anchors = defineModel<number[]>('panel-anchor', { default: [] });
+
+const emit = defineEmits<{
+  /** 关闭动画与遮罩收尾结束（`duration` 为 0 时为同步收尾后） */
+  closed: [];
+}>();
+
+/** 立刻把 v-model height 置 0（Vant 做过渡）；遮罩用 isClosing 多留一程；结束后 `emit('closed')` */
+function applyCloseAnimation() {
+  clearCloseTimer();
+  isClosing.value = true;
+  height.value = 0;
+  const ms = durationSec.value * 1000;
+  if (ms <= 0) {
+    isClosing.value = false;
+    emit('closed');
+    return;
+  }
+  closeTimer.value = setTimeout(() => {
+    closeTimer.value = null;
+    isClosing.value = false;
+    emit('closed');
+  }, ms);
+}
+
+// --- 布局测量：头高参与 setHeight；内容外包层高度参与 autoHeight ---
+const panelHeaderRef = useTemplateRef('panel-header');
+const { height: panelHeaderHeight } = useElementSize(panelHeaderRef, { height: 30 }, { box: 'border-box' });
+
+const panelContentRootRef = useTemplateRef('panel-content-root');
+const { height: measuredContentHeight } = useElementSize(panelContentRootRef, { height: 0 }, { box: 'border-box' });
+const panelContentHeight = ref(0);
+
+/** autoHeight 下内容区被限制高度后，useElementSize 只有可视高；锚点需按 scrollHeight 取真实内容高 */
+const intrinsicAutoContentHeight = ref(0);
+function syncIntrinsicAutoContentHeight() {
+  if (!autoHeight) return;
+  nextTick(() => {
+    const el = panelContentRootRef.value;
+    const sh = el?.scrollHeight ?? 0;
+    if (intrinsicAutoContentHeight.value !== sh) intrinsicAutoContentHeight.value = sh;
+  });
+}
+watchPostEffect(() => {
+  if (!autoHeight) return;
+  height.value;
+  panelContentHeight.value;
+  measuredContentHeight.value;
+  syncIntrinsicAutoContentHeight();
+});
+onUpdated(() => {
+  if (autoHeight) syncIntrinsicAutoContentHeight();
+});
+
+const measuredContentHeightForAnchors = computed(() =>
+  autoHeight ? intrinsicAutoContentHeight.value : measuredContentHeight.value,
+);
+
+const style = computed(() => {
+  return {
+    '--van-floating-panel-header-height': `${panelHeaderHeight.value}px`,
+    '--van-floating-panel-content-height': `${panelContentHeight.value}px`,
+  };
+});
+
+// --- 对外 API（expose / useFloatPanel ref）---
+const instance: FloatPanelInstance = {
+  getAnchors() {
+    return toValue(anchors);
+  },
+  setAnchors(values: number | number[], reset = true) {
+    const result = computeAnchorsAndSnapHeight(
+      values,
+      reset,
+      height.value,
+      maxContainerHeight,
+      anchors.value,
+    );
+    if (!result) return;
+    anchors.value = result.anchors;
+    height.value = result.height;
+  },
+  setHeight(value: number, updateAnchor = true) {
+    const total = value + panelHeaderHeight.value;
+    if (updateAnchor) {
+      instance.setAnchors(total, false);
+      height.value = total;
+      return;
+    }
+    height.value = total;
+  },
+  closeAnimated: applyCloseAnimation,
+
+  snapMin() {
+    const target = toValue(anchors).find((a) => a > 0);
+    if (target === undefined) return false;
+    if (height.value === target) return false;
+    instance.setAnchors(target, false);
+    height.value = target;
+    return true;
+  },
+  snapMax() {
+    const list = toValue(anchors);
+    const target = list[list.length - 1];
+    if (target === undefined) return false;
+    if (height.value === target) return false;
+    instance.setAnchors(target, false);
+    height.value = target;
+    return true;
+  },
+  snapFull() {
+    const target = maxContainerHeight;
+    if (height.value === target) return false;
+    instance.setAnchors(target, false);
+    height.value = target;
+    return true;
+  },
+  snapToFirstAnchor() {
+    return instance.snapMin();
+  },
+  snapToLastAnchor() {
+    return instance.snapMax();
+  },
+  snapToMaxContainerHeight() {
+    return instance.snapFull();
+  },
+};
+
+const { resetAutoHeightSyncOnReopen } = useFloatPanelAnchorsAutoHeight({
+  height,
+  measuredContentHeight: measuredContentHeightForAnchors,
+  panelHeaderHeight,
+  closable: () => closable,
+  full: () => full,
+  maxContainerHeight: () => maxContainerHeight,
+  autoHeight: () => autoHeight,
+  setAnchors: (v, r) => instance.setAnchors(v, r),
+  setHeight: (v, u) => instance.setHeight(v, u),
+});
+
+const onClose = () => applyCloseAnimation();
+const onClickOverlay = () => {
+  if (closeOnClickOverlay) onClose();
+};
+
+/** 与 Vant `height-change` 一致：内容区高度 = 面板总高 − 头高。逻辑层改 `v-model:height` 时未必触发该事件，需自行同步 CSS 变量 */
+function syncPanelContentHeightFromTotal(total: number) {
+  panelContentHeight.value =
+    total <= 0 ? 0 : Math.max(0, total - panelHeaderHeight.value);
+}
+
+const onUpdateHeight = ({ height: h }: { height: number }) => {
+  syncPanelContentHeightFromTotal(h);
+};
+
+watch(
+  [height, panelHeaderHeight],
+  () => syncPanelContentHeightFromTotal(height.value),
+  { flush: 'post', immediate: true },
+);
+
+watch(height, (h, prev) => {
+  if (h !== 0) {
+    clearCloseTimer();
+    isClosing.value = false;
+  } else if (prev !== undefined && prev !== 0 && !isClosing.value) {
+    // 非 closeAnimated：等 v-model 同步到 Wrapper 后再通知（便于 `onUpdate:panelHeight` 先置 pending）
+    nextTick(() => emit('closed'));
+  }
+  resetAutoHeightSyncOnReopen(prev, h);
+});
+
+defineExpose(instance);
+</script>
+
+<template>
+  <!-- isClosing：height 已为 0 时仍短暂展示遮罩，与 Vant 收起动画同长 -->
+  <van-overlay
+    :class="overlayClassList"
+    :style="overlayStyle"
+    :show="height !== 0 || isClosing"
+    :duration="durationSec"
+    @click="onClickOverlay"
+  >
+    <van-floating-panel
+      :class="containerClassList"
+      :style="[containerStyle, style]"
+      v-model:height="height"
+      :duration="durationSec"
+      :anchors="anchors"
+      :content-draggable="contentDraggable"
+      @click.stop
+      @height-change="onUpdateHeight"
+    >
+      <template #header>
+        <div class="van-floating-panel__header">
+          <div ref="panel-header">
+            <van-icon v-if="closable" class="van-floating-panel__header_icon" name="cross" size="18" @click.stop="onClose()" />
+            <div class="van-floating-panel__header-bar"></div>
+            <slot name="header" :title="title">
+              <div>{{ title }}</div>
+            </slot>
+          </div>
+        </div>
+      </template>
+      <template #default>
+        <div ref="panel-content-root" class="float-panel-content-root">
+          <slot name="content"></slot>
+        </div>
+      </template>
+    </van-floating-panel>
+  </van-overlay>
+</template>
+
+<style scoped lang="scss">
+.float-panel-overlay {
+  --van-overlay-z-index: var(--van-floating-panel-z-index);
+  &.hide {
+    --van-overlay-background: transparent;
+  }
+}
+.float-panel-container {
+  $gap: calc((30px - var(--van-floating-panel-bar-height)) / 2);
+
+  :deep(.van-floating-panel__header) {
+    padding: 0;
+    position: relative;
+    > div {
+      padding-top: $gap;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      width: 100%;
+      min-height: 30px;
+    }
+    .van-floating-panel__header-bar {
+      & + * {
+        padding: calc($gap / 2) 0;
+      }
+    }
+    .van-floating-panel__header_icon {
+      position: absolute;
+      top: calc($gap / 2);
+      right:calc($gap / 2);
+      color: var(--van-floating-panel-bar-color);
+    }
+  }
+  :deep(.van-floating-panel__content) {
+    height: var(--van-floating-panel-content-height);
+    overflow: hidden !important;
+    flex: none;
+    min-height: 0;
+    > * {
+      height: 100%;
+      min-height: 0;
+      overflow-y: auto;
+      box-sizing: border-box;
+    }
+  }
+}
+</style>

src/composables/FloatPanel/floatPanelAnchors.ts

@@ -0,0 +1,49 @@
+/**
+ * 浮动面板锚点：合并集合并按规则吸附到合法 height（无 Vue 依赖，便于测试与复用）。
+ */
+
+export type AnchorsSnapResult = { anchors: number[]; height: number };
+
+/**
+ * 根据新锚点候选合并列表，并计算吸附后的 `height`。
+ * @param values - 本次写入的锚点（或单个）
+ * @param reset - 为 `true` 时以 `values` 为基底；为 `false` 时与 `currentAnchors` 合并
+ * @param prevHeight - 吸附前的面板总高度
+ * @param maxContainerHeight - 允许的最大总高度（px）
+ * @param currentAnchors - 当前 v-model 锚点（`reset === false` 时参与合并）
+ */
+export function computeAnchorsAndSnapHeight(
+  values: number | number[],
+  reset: boolean,
+  prevHeight: number,
+  maxContainerHeight: number,
+  currentAnchors: readonly number[],
+): AnchorsSnapResult | null {
+  const list = !Array.isArray(values) ? [values] : values;
+  const set = new Set(list);
+  if (!reset) currentAnchors.forEach((a) => set.add(a));
+
+  const anchors = [...set].filter((v) => v <= maxContainerHeight).sort((a, b) => a - b);
+  if (!anchors.length) return null;
+
+  const hit = anchors.findIndex((v) => v === prevHeight);
+  if (hit >= 0) {
+    return { anchors, height: anchors[hit]! };
+  }
+
+  let nearest = anchors[0]!;
+  let minDist = Math.abs(prevHeight - nearest);
+  for (const a of anchors) {
+    const d = Math.abs(prevHeight - a);
+    if (d < minDist) {
+      minDist = d;
+      nearest = a;
+    }
+  }
+  const positives = anchors.filter((a) => a > 0);
+  if (nearest === 0 && prevHeight > 0 && positives.length) {
+    const height = positives.reduce((m, a) => (Math.abs(a - prevHeight) < Math.abs(m - prevHeight) ? a : m));
+    return { anchors, height };
+  }
+  return { anchors, height: nearest };
+}

src/composables/FloatPanel/index.ts

@@ -0,0 +1,7 @@
+/**
+ * 底部浮动面板：封装 Vant `FloatingPanel` + `Overlay`，并提供 `useFloatPanel` 命令式封装。
+ */
+export { default as FloatPanel } from './FloatPanel.vue';
+export { injectFloatPanelContext, useFloatPanel } from './useFloatPanel';
+
+export * from './types';

src/composables/FloatPanel/types.ts

@@ -0,0 +1,141 @@
+import type { InjectionKey, Ref } from 'vue';
+
+/**
+ * 底部浮动面板（基于 Vant `FloatingPanel`）的 props。
+ * 对外 v-model：`panel-height`、`panel-anchor`。
+ *
+ * 事件：`closed` — 关闭动画与遮罩收尾结束（见组件 `defineEmits`）。
+ */
+export interface FloatPanelProps {
+  /** 是否显示遮罩层；为 `false` 时仍占位但背景可透明（配合 `overlayClass`） */
+  overlay?: boolean;
+  /** 遮罩层额外 class */
+  overlayClass?: Array<string | object> | string | object;
+  /** 遮罩层内联样式 */
+  overlayStyle?: CSSStyleValue;
+  /** 点击遮罩是否触发关闭（将 height 置 0） */
+  closeOnClickOverlay?: boolean;
+
+  /** 面板容器额外 class */
+  containerClass?: Array<string | object> | string | object;
+  /** 面板容器内联样式 */
+  containerStyle?: CSSStyleValue;
+
+  /** 标题文案（默认 header 插槽） */
+  title?: string;
+  /**
+   * 为 `true` 时在锚点中加入 `maxContainerHeight`，可拖到全屏高度。
+   */
+  full?: boolean;
+  /**
+   * 为 `true` 时在锚点中加入 `0`，展示关闭图标，并允许收起到高度 0。
+   */
+  closable?: boolean;
+  /** 是否允许拖拽内容区改变高度（仅头部可拖时为 `false`） */
+  contentDraggable?: boolean;
+  /**
+   * 为 `true` 时按内容高度同步面板总高（测量见 `FloatPanel` 实现）。
+   * 不使用 100 / 60% 视口等默认锚点；打开后锚点收敛为 `0`（若 `closable`）、`maxContainerHeight`（若 `full`）与当前内容总高。
+   */
+  autoHeight?: boolean;
+  /**
+   * 动画时长（秒）。`0` 表示无过渡。
+   * 用于 Vant Overlay / FloatingPanel，并与关闭时 `isClosing` 时长一致。
+   */
+  duration?: number | string;
+  /** 面板允许的最大高度（px），锚点与 autoHeight 裁剪均受此限制 */
+  maxContainerHeight?: number;
+}
+
+/**
+ * 通过 `defineExpose` 暴露给父组件或 `ref` 的实例能力。
+ * `setHeight` 的入参为**内容区**高度（不含头部）；默认将总高合并进锚点，见 `setHeight` 的 `updateAnchor`。
+ */
+export interface FloatPanelInstance {
+  /** 当前锚点数组（只读快照） */
+  getAnchors(): number[];
+
+  /**
+   * 更新锚点集合。
+   * @param value - 一个或多个锚点（px）
+   * @param reset - `true` 时用 `value` 替换；`false` 时与现有锚点合并
+   */
+  setAnchors(value: number | number[], reset?: boolean): void;
+
+  /**
+   * 按**内容区**高度（不含头）换算为总高度后更新 `panel-height`。
+   * @param value - 内容区高度（px）
+   * @param updateAnchor - 默认 `true`：将总高合并进锚点（`setAnchors(total, false)`）再设 `height`；
+   *   `false` 时仅写入 `height`，不修改锚点列表（可能影响磁力吸附，按需使用）
+   */
+  setHeight(value: number, updateAnchor?: boolean): void;
+
+  /**
+   * 触发关闭动画：立即将 `panel-height` 置 `0`，由 Vant 在 `duration` 内过渡；
+   * 同时维持遮罩至动画结束，避免提前卸载打断过渡。
+   */
+  closeAnimated(): void;
+
+  /**
+   * 将总高设为当前**已排序锚点列表里第一个大于 `0` 的项**（跳过关闭态 `0`）。
+   * @returns 若无任何 `> 0` 的锚点、或已在目标高度，则为 `false`
+   */
+  snapMin(): boolean;
+
+  /**
+   * 将总高设为当前**已排序锚点列表的最后一个**（通常最大）。
+   * @returns 若 `height` 发生变化则为 `true`；无锚点或已在目标高度则为 `false`
+   */
+  snapMax(): boolean;
+
+  /**
+   * 将总高设为 **`maxContainerHeight` 上限**（会合并进锚点，与 `full` 锚点边界一致）。
+   * @returns 若 `height` 发生变化则为 `true`；已在该高度则为 `false`
+   */
+  snapFull(): boolean;
+
+  /** 同 {@link FloatPanelInstance.snapMin}（第一个 `> 0` 的锚点） */
+  snapToFirstAnchor(): boolean;
+
+  /** 同 {@link FloatPanelInstance.snapMax} */
+  snapToLastAnchor(): boolean;
+
+  /** 同 {@link FloatPanelInstance.snapFull} */
+  snapToMaxContainerHeight(): boolean;
+}
+
+/**
+ * `useFloatPanel` 注入到内容子树的 key，值为指向 `FloatPanelInstance` 的 ref（面板挂载后才有值）。
+ */
+export const floatPanelContextKey: InjectionKey<Ref<FloatPanelInstance | undefined>> =
+  Symbol('floatPanelContext');
+
+/**
+ * `useFloatPanel` 返回的操作对象：在 `open` 返回的 Promise 上接收 `complete` / `cancel` 或 `close(result)` 的结果。
+ */
+export interface FloatPanelApi<P extends Record<string, any>, R = any> extends FloatPanelInstance {
+  /**
+   * 打开面板并传入内容区 props；返回的 Promise 在关闭时 resolve。
+   * @param props - 传给 `Content` 或默认插槽作用域的对象
+   */
+  open(props: P | void | null): Promise<R | void>;
+
+  /**
+   * 关闭面板并 resolve `open` 的 Promise。
+   * @param result - 可选结果，会作为 `open` Promise 的 resolve 值
+   */
+  close(result?: R): void;
+}
+
+/**
+ * 合并 `open(props)` 与面板注入的关闭回调后，传给内容组件或默认插槽的最终 props。
+ *
+ * - 内容组件可 `emit('complete', result?)` / `emit('cancel')`
+ * - 与直接使用 `onComplete` / `onCancel` 等价（由 `mergeProps` 合并）
+ */
+export type FloatPanelContentBindings<P extends Record<string, any>, R = unknown> = P & {
+  /** 确认关闭，可选传入 `open` Promise 的结果 */
+  onComplete: (result?: R) => void;
+  /** 取消关闭，`open` Promise resolve 为 `undefined` */
+  onCancel: () => void;
+};

src/composables/FloatPanel/useFloatPanel.ts

@@ -0,0 +1,159 @@
+import type { Component, Ref } from 'vue';
+import { defineComponent, h, inject, mergeProps, provide, ref, shallowRef } from 'vue';
+import __FloatPanel_vue from './FloatPanel.vue';
+import type { FloatPanelApi, FloatPanelContentBindings, FloatPanelInstance } from './types';
+import { floatPanelContextKey } from './types';
+
+/**
+ * 在 `useFloatPanel` 提供的内容子树内调用，获取指向 `FloatPanelInstance` 的 ref。
+ * @throws 若在 provide 范围外调用
+ */
+export function injectFloatPanelContext(): Ref<FloatPanelInstance | undefined> {
+  const injected = inject(floatPanelContextKey, undefined);
+  if (injected === undefined) {
+    throw new Error('injectFloatPanelContext() 须在 useFloatPanel 的 Wrapper 内容树内使用');
+  }
+  return injected;
+}
+
+/**
+ * 声明式挂载浮动面板：返回 `[Wrapper, api]`。
+ *
+ * - **Wrapper**：放入模板根或任意位置；`open()` 后才会渲染内部 `FloatPanel`。
+ * - **api**：`open` / `close` 及与 `FloatPanelInstance` 一致的面板操作。
+ *
+ * 关闭卸载由 `FloatPanel` 在动画结束后 **`emit('closed')`** 触发，不在此重复定时逻辑。
+ *
+ * @param Content - 可选内容组件；不传则用 Wrapper 的默认插槽（作用域参数含 `onComplete` / `onCancel`）
+ */
+export function useFloatPanel<P extends Record<string, any> = Record<string, unknown>, R = P>(
+  Content?: Component,
+) {
+  let pending: PromiseWithResolvers<R | void> | undefined;
+  /** `closeAnimated` 结束时交给 `onClosed` 再 `settle` */
+  let dismissResult: R | void | undefined;
+
+  const show = ref(false);
+  /** 为 true 表示正在等待 FloatPanel `closed`，用于忽略重开后的陈旧 `closed` */
+  const pendingCloseUnmount = ref(false);
+  const panelOpenKey = ref(0);
+  const innerProps = shallowRef<P>();
+  const floatPanelRef = ref<FloatPanelInstance>();
+
+  function settle(result?: R | void) {
+    pending?.resolve(result);
+    pending = undefined;
+  }
+
+  function closePanel(result?: R) {
+    const inst = floatPanelRef.value;
+    if (inst?.closeAnimated) {
+      pendingCloseUnmount.value = true;
+      dismissResult = result;
+      inst.closeAnimated();
+    } else {
+      pendingCloseUnmount.value = false;
+      dismissResult = undefined;
+      settle(result);
+      show.value = false;
+    }
+  }
+
+  const api: FloatPanelApi<P, R> = {
+    open(props: P): Promise<R | void> {
+      pending?.resolve(void 0);
+      pending = Promise.withResolvers<R | void>();
+      dismissResult = undefined;
+      pendingCloseUnmount.value = false;
+      innerProps.value = props;
+      panelOpenKey.value += 1;
+      show.value = true;
+      return pending.promise;
+    },
+    close(result?: R) {
+      closePanel(result);
+    },
+    getAnchors() {
+      return floatPanelRef.value?.getAnchors() ?? [];
+    },
+    setAnchors(value, reset) {
+      floatPanelRef.value?.setAnchors(value, reset);
+    },
+    setHeight(value, updateAnchor) {
+      floatPanelRef.value?.setHeight(value, updateAnchor);
+    },
+    closeAnimated() {
+      floatPanelRef.value?.closeAnimated();
+    },
+    snapMin() {
+      return floatPanelRef.value?.snapMin() ?? false;
+    },
+    snapMax() {
+      return floatPanelRef.value?.snapMax() ?? false;
+    },
+    snapFull() {
+      return floatPanelRef.value?.snapFull() ?? false;
+    },
+    snapToFirstAnchor() {
+      return floatPanelRef.value?.snapToFirstAnchor() ?? false;
+    },
+    snapToLastAnchor() {
+      return floatPanelRef.value?.snapToLastAnchor() ?? false;
+    },
+    snapToMaxContainerHeight() {
+      return floatPanelRef.value?.snapToMaxContainerHeight() ?? false;
+    },
+  };
+
+  const Wrapper = defineComponent({
+    name: 'FloatPanelWrapper',
+    inheritAttrs: false,
+    setup(_, { attrs, slots }) {
+      provide(floatPanelContextKey, floatPanelRef);
+
+      return () => {
+        if (!show.value) return null;
+
+        const attrObj = attrs as Record<string, unknown>;
+        const panelBindings = mergeProps(attrObj, {
+          'onUpdate:panelHeight': (value: number) => {
+            if (value !== 0) {
+              show.value = true;
+              return;
+            }
+            if (!pendingCloseUnmount.value) {
+              pendingCloseUnmount.value = true;
+            }
+          },
+          onClosed: () => {
+            if (!pendingCloseUnmount.value) return;
+            pendingCloseUnmount.value = false;
+            const r = dismissResult;
+            dismissResult = undefined;
+            settle(r);
+            show.value = false;
+          },
+        });
+
+        return h(
+          __FloatPanel_vue,
+          { ref: floatPanelRef, key: panelOpenKey.value, closable: true, ...panelBindings },
+          {
+            header: slots.header,
+            content: () => {
+              const slotProps = innerProps.value ?? ({} as P);
+              const contentBindings = mergeProps(slotProps as Record<string, unknown>, {
+                onComplete: (result?: R) => closePanel(result),
+                onCancel: () => closePanel(),
+              });
+              if (Content) return h(Content, contentBindings);
+              return slots.default?.(contentBindings as FloatPanelContentBindings<P, R>) ?? null;
+            },
+          },
+        );
+      };
+    },
+  });
+
+  return [Wrapper, api] as const;
+}

src/composables/FloatPanel/useFloatPanelAnchorsAutoHeight.ts

@@ -0,0 +1,117 @@
+import type { Ref } from 'vue';
+import { ref, watch } from 'vue';
+
+export interface FloatPanelAnchorsAutoHeightOptions {
+  height: Ref<number>;
+  measuredContentHeight: Ref<number>;
+  panelHeaderHeight: Ref<number>;
+  closable: () => boolean;
+  full: () => boolean;
+  maxContainerHeight: () => number;
+  autoHeight: () => boolean;
+  setAnchors: (values: number | number[], reset?: boolean) => void;
+  setHeight: (contentHeight: number, updateAnchor?: boolean) => void;
+}
+
+/**
+ * 边界锚点 + 默认锚点合并，以及 autoHeight 与测量联动。
+ * 与关闭动画、`isClosing` 无关。
+ */
+export function useFloatPanelAnchorsAutoHeight(options: FloatPanelAnchorsAutoHeightOptions) {
+  const {
+    height,
+    measuredContentHeight,
+    panelHeaderHeight,
+    closable,
+    full,
+    maxContainerHeight,
+    autoHeight,
+    setAnchors,
+    setHeight,
+  } = options;
+
+  /** 区分「首次从 0 按内容撑起」与「用户已关到 0 勿再被测量顶开」 */
+  const autoHeightSyncedOnce = ref(false);
+
+  /** 在 setHeight 之后收敛锚点：仅保留 0 / max / 当前总高，去掉默认 100 等残留 */
+  function replaceAnchorsAfterContentHeight(total: number) {
+    const list = new Set<number>([total]);
+    if (closable()) list.add(0);
+    if (full()) list.add(maxContainerHeight());
+    setAnchors(
+      [...list].filter((v) => v <= maxContainerHeight()).sort((a, b) => a - b),
+      true,
+    );
+  }
+
+  /** 未改 height 时仅补充边界锚点（合并，不整表替换） */
+  function mergeBoundaryAnchors() {
+    const b: number[] = [];
+    if (closable()) b.push(0);
+    if (full()) b.push(maxContainerHeight());
+    if (!b.length) return;
+    setAnchors(b.length === 1 ? b[0]! : b, false);
+  }
+
+  watch(
+    [
+      () => closable(),
+      () => full(),
+      () => maxContainerHeight(),
+      measuredContentHeight,
+      panelHeaderHeight,
+      () => autoHeight(),
+    ],
+    () => {
+      const boundary = new Set<number>();
+      if (closable()) boundary.add(0);
+      if (full()) boundary.add(maxContainerHeight());
+
+      if (!autoHeight()) {
+        const defaultAnchors = [100, innerHeight * 0.6];
+        setAnchors([...new Set([...boundary, ...defaultAnchors])], false);
+        autoHeightSyncedOnce.value = false;
+        return;
+      }
+
+      // autoHeight：不使用 100 / 60% 视口等默认锚点，避免打开时被吸附到最小非零锚点
+      const ch = measuredContentHeight.value;
+      if (ch <= 0) return;
+
+      const header = panelHeaderHeight.value;
+      const maxContent = Math.max(0, maxContainerHeight() - header);
+      const contentClamped = Math.min(ch, maxContent);
+      const targetPanel = contentClamped + header;
+
+      if (height.value === 0) {
+        if (!autoHeightSyncedOnce.value) {
+          setHeight(contentClamped, true);
+          replaceAnchorsAfterContentHeight(targetPanel);
+          autoHeightSyncedOnce.value = true;
+        }
+        return;
+      }
+
+      autoHeightSyncedOnce.value = true;
+      if (Math.abs(height.value - targetPanel) > 0.5) {
+        setHeight(contentClamped, true);
+        replaceAnchorsAfterContentHeight(targetPanel);
+      } else {
+        mergeBoundaryAnchors();
+      }
+    },
+    { flush: 'post', immediate: true },
+  );
+
+  /** 供外层对 `height` 的 watch 调用：从关闭态再次打开时允许 autoHeight 重新同步 */
+  function resetAutoHeightSyncOnReopen(prev: number | undefined, h: number) {
+    if (prev === 0 && h !== 0) {
+      autoHeightSyncedOnce.value = false;
+    }
+  }
+
+  return {
+    autoHeightSyncedOnce,
+    resetAutoHeightSyncOnReopen,
+  };
+}

src/composables/start/Start.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import { useStart, startDirective } from '@/composables/start';
+
+const vStart = startDirective;
+const { loading, handle, extra } = useStart();
+</script>
+
+<template>
+  <div
+    class="van-button decorate"
+    data-start="true"
+    v-start="extra"
+    @click="!loading && handle()"
+  >
+    <div class="van-button__content">
+      <van-loading v-if="loading" />
+      <span v-else class="van-button__text">开始检测</span>
+    </div>
+  </div>
+</template>
+
+<style scoped lang="scss"></style>

src/composables/start/index.ts

@@ -0,0 +1,3 @@
+export { default as Start } from './Start.vue';
+export { startDirective } from './start.directive';
+export { useStart } from './useStart';

src/composables/start/start.directive.ts

@@ -0,0 +1,110 @@
+import type { DirectiveBinding, ObjectDirective } from 'vue';
+
+export const START_HOLD_EVENT = 'start-hold';
+
+export interface StartDirectiveValue {
+  threshold: number;
+  fn?: () => void;
+  /** 默认派发 `start-hold`；`false` 时不派发 */
+  emit?: boolean;
+}
+
+type StartBinding = DirectiveBinding<StartDirectiveValue>;
+
+type Entry = {
+  binding: StartBinding;
+};
+
+const entries = new WeakMap<HTMLElement, Entry>();
+
+const listenOpts: AddEventListenerOptions = { capture: true };
+
+function resolveMode(modifiers: StartBinding['modifiers']): 'duration' | 'distance' {
+  if (modifiers.distance && modifiers.duration) {
+    console.warn('[v-start] Both .duration and .distance are set; using .distance.');
+    return 'distance';
+  }
+  if (modifiers.distance) return 'distance';
+  return 'duration';
+}
+
+function readValue(binding: StartBinding): StartDirectiveValue | null {
+  const v = binding.value;
+  if (v == null || typeof v !== 'object') return null;
+  if (typeof v.threshold !== 'number' || Number.isNaN(v.threshold)) return null;
+  return v;
+}
+
+function mount(el: HTMLElement, binding: StartBinding) {
+  let down: { timeStamp: number; clientX: number; clientY: number; pointerId: number } | null =
+    null;
+
+  const onPointerDown = (e: PointerEvent) => {
+    down = {
+      timeStamp: e.timeStamp,
+      clientX: e.clientX,
+      clientY: e.clientY,
+      pointerId: e.pointerId,
+    };
+  };
+
+  const onPointerUp = (e: PointerEvent) => {
+    if (!down || e.pointerId !== down.pointerId) return;
+
+    const entry = entries.get(el);
+    if (!entry) return;
+
+    const value = readValue(entry.binding);
+    const mode = resolveMode(entry.binding.modifiers);
+
+    const start = down;
+    down = null;
+
+    if (!value) return;
+
+    const delta =
+      mode === 'duration'
+        ? e.timeStamp - start.timeStamp
+        : Math.hypot(e.clientX - start.clientX, e.clientY - start.clientY);
+
+    if (delta <= value.threshold) return;
+
+    value.fn?.();
+
+    if (value.emit !== false) {
+      const detail =
+        mode === 'duration' ? { durationMs: delta } : { distancePx: delta };
+      el.dispatchEvent(
+        new CustomEvent(START_HOLD_EVENT, {
+          detail,
+          bubbles: true,
+        }),
+      );
+    }
+  };
+
+  el.addEventListener('pointerdown', onPointerDown, listenOpts);
+  el.addEventListener('pointerup', onPointerUp, listenOpts);
+
+  entries.set(el, { binding });
+
+  return () => {
+    el.removeEventListener('pointerdown', onPointerDown, listenOpts);
+    el.removeEventListener('pointerup', onPointerUp, listenOpts);
+    entries.delete(el);
+  };
+}
+
+export const startDirective: ObjectDirective<HTMLElement, StartDirectiveValue> = {
+  mounted(el, binding) {
+    (el as HTMLElement & { __startCleanup?: () => void }).__startCleanup = mount(el, binding);
+  },
+  updated(el, binding) {
+    const e = entries.get(el);
+    if (e) e.binding = binding;
+  },
+  unmounted(el) {
+    (el as HTMLElement & { __startCleanup?: () => void }).__startCleanup?.();
+    (el as HTMLElement & { __startCleanup?: () => void }).__startCleanup = undefined;
+  },
+};

src/composables/start/useStart.ts

@@ -0,0 +1,49 @@
+import type { StartDirectiveValue } from '@/composables/start/start.directive';
+
+import { showLoadingToast } from 'vant';
+import { Notify } from '@/platform';
+import { registerVisitorMethod } from '@/request/api';
+import { useFlowStore, useVisitor } from '@/stores';
+
+const showLoading = () => {
+  const instance = showLoadingToast({
+    message: '加载中...',
+    forbidClick: true,
+    duration: 0,
+  });
+  return () => instance.close();
+}
+
+export function useStart(ui?: boolean) {
+  const Visitor = useVisitor();
+  const Flow = useFlowStore();
+  const { flow } = storeToRefs(Flow);
+
+  const extra: StartDirectiveValue = {
+    threshold: 1000 * 5,
+    fn() {},
+  };
+
+  const register = async () => {
+    loading.value = true;
+    const close = ui ? showLoading() : void 0;
+    try {
+      Visitor.patientId = await registerVisitorMethod().send(true);
+      return Visitor.patientId;
+    } catch (error: any) {
+      Notify.error(error.message);
+    } finally {
+      loading.value = false;
+      close?.()
+    }
+  };
+
+  const loading = ref(false);
+  async function handle() {
+    if (loading.value) return;
+    Visitor.$reset();
+    if (flow.value.next === '/register' || (await register())) await Flow.router.push();
+  }
+
+  return { extra, loading, handle };
+}

src/pages/scan.page.vue

@@ -2,7 +2,7 @@
 import { useRequest } from 'alova/client';
 import { getApplicationMethod } from '@/request/api';
 
-import Start from '@/components/Start.vue';
+import { Start } from '@/composables/start';
 
 const { data } = useRequest(getApplicationMethod, { initialData: { image: { el: '', copyright: '' } } });
 const title = computed(() => data.value.image.title || import.meta.env.SIX_APP_TITLE);

src/pages/screen.page.vue

@@ -6,7 +6,7 @@ import { useElementSize } from '@vueuse/core';
 import { useRequest }     from 'alova/client';
 import p5                 from 'p5';
 
-import Start from '@/components/Start.vue';
+import { Start } from '@/composables/start';
 
 const { data } = useRequest(getApplicationMethod, { initialData: { image: { el: '', copyright: '' } } });
 const title = computed(() => data.value.image.title || import.meta.env.SIX_APP_TITLE);