浮层定位容器 AsamPopper

使用场景

为触发器、内容和箭头提供共享定位上下文。

触发器、内容与箭头组合

焦点/悬停控制公开 visible；四个子入口在同一个完整 SFC 中组合。

触发器、内容与箭头组合

vue

<template>
	<AsamPopper role="tooltip">
		<AsamPopperTrigger
			:on-mouseenter="show"
			:on-mouseleave="hide"
			:on-focus="show"
			:on-blur="hide"
		>
			<AsamButton type="default" native-type="button">基础定位触发器</AsamButton>
		</AsamPopperTrigger>
		<AsamPopperContent
			v-show="visible"
			:visible="visible"
			placement="bottom"
			:offset="12"
			:arrow-offset="6"
			:trapping="false"
		>
			<div class="panel">组合定位内容</div>
			<AsamPopperArrow />
		</AsamPopperContent>
	</AsamPopper>
</template>

<script lang="ts" setup>
defineOptions({ name: 'AsamPopperBasicDemo' });
import { ref } from 'vue';
import {
	AsamButton,
	AsamPopper,
	AsamPopperTrigger,
	AsamPopperContent,
	AsamPopperArrow
} from '@asam-ui/ui';
const visible = ref(false);
const show = () => {
	visible.value = true;
};
const hide = () => {
	visible.value = false;
};
</script>

<style scoped>
.actions {
	display: flex;
	flex-wrap: wrap;
	gap: var(--asam-space-md);
	align-items: center;
}

.panel {
	padding: var(--asam-space-lg);
	border: 1px solid var(--asam-color-border);
	border-radius: var(--asam-radius-control);
}
</style>

<!-- 兼容已发布 0.1.0-alpha.1 的深色浮层样式；仅修正 ASAM 颜色变量。 -->
<style>
:root .asam-tooltip.el-popper.is-dark, :root .asam-popper-content.el-popper.is-dark { --el-text-color-primary: var(--asam-color-text-primary); color: var(--asam-color-surface); }
</style>

vue

<template>
	<AsamPopper role="tooltip">
		<AsamPopperTrigger
			:on-mouseenter="show"
			:on-mouseleave="hide"
			:on-focus="show"
			:on-blur="hide"
		>
			<AsamButton type="default" native-type="button">基础定位触发器</AsamButton>
		</AsamPopperTrigger>
		<AsamPopperContent
			v-show="visible"
			:visible="visible"
			placement="bottom"
			:offset="12"
			:arrow-offset="6"
			:trapping="false"
		>
			<div class="panel">组合定位内容</div>
			<AsamPopperArrow />
		</AsamPopperContent>
	</AsamPopper>
</template>

<script setup>
defineOptions({ name: 'AsamPopperBasicDemo' });
import { ref } from 'vue';
import {
	AsamButton,
	AsamPopper,
	AsamPopperTrigger,
	AsamPopperContent,
	AsamPopperArrow
} from '@asam-ui/ui';
const visible = ref(false);
const show = () => {
	visible.value = true;
};
const hide = () => {
	visible.value = false;
};
</script>

<style scoped>
.actions {
	display: flex;
	flex-wrap: wrap;
	gap: var(--asam-space-md);
	align-items: center;
}

.panel {
	padding: var(--asam-space-lg);
	border: 1px solid var(--asam-color-border);
	border-radius: var(--asam-radius-control);
}
</style>

<!-- 兼容已发布 0.1.0-alpha.1 的深色浮层样式；仅修正 ASAM 颜色变量。 -->
<style>
:root .asam-tooltip.el-popper.is-dark, :root .asam-popper-content.el-popper.is-dark { --el-text-color-primary: var(--asam-color-text-primary); color: var(--asam-color-surface); }
</style>

使用约定

role 定义浮层语义。default 插槽同时放 Trigger 与 Content；公开 triggerRef、referenceRef、contentRef 和 popperInstanceRef 是定位句柄。高层业务提示优先使用 Tooltip/Popover，本入口没有独立显隐、控件 size 或用户事件。

组合职责与生命周期

底层定位上下文须将 AsamPopperTrigger、AsamPopperContent 与 AsamPopperArrow 组合在同一实例中。role 决定内容语义，default 承载组合结构；触发状态、过渡、挂载和业务动作由宿主管理。

API

属性 `AsamPopperProps`

属性名	说明	类型	默认值
`role`	角色决定 ARIA 属性的分配方式。	`enum"group" \| "dialog" \| "grid" \| "listbox" \| "menu" \| "navigation" \| "tooltip" \| "tree"`完整类型：`"group" \| "dialog" \| "grid" \| "listbox" \| "menu" \| "navigation" \| "tooltip" \| "tree" \| undefined`	`"tooltip"`

事件 `AsamPopperEmits`

插槽 `AsamPopperSlots`

属性名	说明	类型	默认值
`default`	—	`(() => unknown) \| undefined`	—

实例方法与状态 `AsamPopperExpose`

属性名	说明	类型	默认值
`role`	—	`enum"group" \| "dialog" \| "grid" \| "listbox" \| "menu" \| "navigation" \| "tooltip" \| "tree"`完整类型：`"group" \| "dialog" \| "grid" \| "listbox" \| "menu" \| "navigation" \| "tooltip" \| "tree"`	—
`triggerRef`	—	`(AsamPopperExpose)["triggerRef"]`	—
`contentRef`	—	`HTMLElement \| undefined`	—
`popperInstanceRef`	—	`(AsamPopperExpose)["popperInstanceRef"]`	—
`referenceRef`	—	`(AsamPopperExpose)["referenceRef"]`	—

参数与事件补充说明

固定 2.14.7 公开参数；运行时默认值来自已安装组件。

参数与事件说明

`role`

必填：否；声明来源：上游声明。

role 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举："group" / "dialog" / "grid" / "listbox" / "menu" / "navigation" / "tooltip" / "tree"

默认值与来源

"tooltip"（已安装运行时；已安装组件）

固定上游源码默认表达式：'tooltip'（2.14.7；源码事实，未作为 ASAM 运行实测）

AsamPopperProps 公开类型视图

import type { AsamPopperProps } from '@asam-ui/ui';

// AsamPopperProps
type PublicContract = {
	"role"?: "group" | "dialog" | "grid" | "listbox" | "menu" | "navigation" | "tooltip" | "tree" | undefined;
};

AsamPopperEmits 公开类型视图

import type { AsamPopperEmits } from '@asam-ui/ui';

// AsamPopperEmits
type PublicContract = {
	[key: string]: never;
};

参数与事件说明

`default`

必填：否；声明来源：ASAM 声明。

default 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

事件参数：(): unknown

AsamPopperSlots 公开类型视图

import type { AsamPopperSlots } from '@asam-ui/ui';

// AsamPopperSlots
type PublicContract = {
	"default"?: (() => unknown) | undefined;
};

参数与事件说明

`role`

必填：是；声明来源：上游声明。

role 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

枚举："group" / "dialog" / "grid" / "listbox" / "menu" / "navigation" / "tooltip" / "tree"

`triggerRef`

必填：是；声明来源：上游声明。

triggerRef 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

triggerRef.getBoundingClientRect: () => DOMRect — 上游声明
事件参数：(): DOMRect

`contentRef`

必填：是；声明来源：上游声明。

contentRef 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

嵌套展开边界：大型实例类型；完整类型见公开类型视图。

`popperInstanceRef`

必填：是；声明来源：上游声明。

popperInstanceRef 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

popperInstanceRef.state: PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state"> — 依赖声明
- popperInstanceRef.state.elements: (NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["elements"] — 依赖声明
  - popperInstanceRef.state.elements.reference: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["elements"]>)["reference"] — 依赖声明
    嵌套展开边界：深度上限；完整类型见公开类型视图。
  - popperInstanceRef.state.elements.popper: HTMLElement — 依赖声明
    嵌套展开边界：框架 / 平台类型；完整类型见公开类型视图。
  - popperInstanceRef.state.elements.arrow: HTMLElement | undefined — 依赖声明
    嵌套展开边界：深度上限；完整类型见公开类型视图。
- popperInstanceRef.state.options: (NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["options"] — 依赖声明
  - popperInstanceRef.state.options.placement: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["options"]>)["placement"] — 依赖声明
    枚举："auto" / "auto-start" / "auto-end" / "top" / "bottom" / "right" / "left" / "top-start" / "top-end" / "bottom-start" / "bottom-end" / "right-start" / "right-end" / "left-start" / "left-end"
    嵌套展开边界：深度上限；完整类型见公开类型视图。
  - popperInstanceRef.state.options.modifiers: any[] — 依赖声明
    嵌套展开边界：框架 / 平台类型；完整类型见公开类型视图。
  - popperInstanceRef.state.options.strategy: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["options"]>)["strategy"] — 依赖声明
    枚举："fixed" / "absolute"
    嵌套展开边界：深度上限；完整类型见公开类型视图。
  - popperInstanceRef.state.options.onFirstUpdate: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["options"]>)["onFirstUpdate"] — 依赖声明
    事件参数：(arg0: Parameters<Extract<NonNullable<(NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["options"]>)["onFirstUpdate"]>, (...args: never[]) => unknown>>[0]): void
    嵌套展开边界：深度上限；完整类型见公开类型视图。
- popperInstanceRef.state.placement: (NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["placement"] — 依赖声明
  枚举："auto" / "auto-start" / "auto-end" / "top" / "bottom" / "right" / "left" / "top-start" / "top-end" / "bottom-start" / "bottom-end" / "right-start" / "right-end" / "left-start" / "left-end"
- popperInstanceRef.state.strategy: (NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["strategy"] — 依赖声明
  枚举："fixed" / "absolute"
- popperInstanceRef.state.orderedModifiers: (NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["orderedModifiers"] — 依赖声明
  嵌套展开边界：框架 / 平台类型；完整类型见公开类型视图。
- popperInstanceRef.state.rects: (NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["rects"] — 依赖声明
  - popperInstanceRef.state.rects.reference: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["rects"]>)["reference"] — 依赖声明
    嵌套展开边界：深度上限；完整类型见公开类型视图。
  - popperInstanceRef.state.rects.popper: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["rects"]>)["popper"] — 依赖声明
    嵌套展开边界：深度上限；完整类型见公开类型视图。
- popperInstanceRef.state.scrollParents: (NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["scrollParents"] — 依赖声明
  - popperInstanceRef.state.scrollParents.reference: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["scrollParents"]>)["reference"] — 依赖声明
    嵌套展开边界：框架 / 平台类型；完整类型见公开类型视图。
  - popperInstanceRef.state.scrollParents.popper: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["scrollParents"]>)["popper"] — 依赖声明
    嵌套展开边界：框架 / 平台类型；完整类型见公开类型视图。
- popperInstanceRef.state.styles: { [key: string]: Partial<CSSStyleDeclaration>; } — 依赖声明
- popperInstanceRef.state.attributes: { [key: string]: { [key: string]: string | boolean; }; } — 依赖声明
- popperInstanceRef.state.modifiersData: (NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["modifiersData"] — 依赖声明
  - popperInstanceRef.state.modifiersData.arrow: { x?: number; y?: number; centerOffset: number; } | undefined — 依赖声明
    嵌套展开边界：深度上限；完整类型见公开类型视图。
  - popperInstanceRef.state.modifiersData.hide: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["modifiersData"]>)["hide"] — 依赖声明
    嵌套展开边界：深度上限；完整类型见公开类型视图。
  - popperInstanceRef.state.modifiersData.offset: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["modifiersData"]>)["offset"] — 依赖声明
    嵌套展开边界：深度上限；完整类型见公开类型视图。
  - popperInstanceRef.state.modifiersData.preventOverflow: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["modifiersData"]>)["preventOverflow"] — 依赖声明
    嵌套展开边界：深度上限；完整类型见公开类型视图。
  - popperInstanceRef.state.modifiersData.popperOffsets: (NonNullable<(NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "state">>)["modifiersData"]>)["popperOffsets"] — 依赖声明
    嵌套展开边界：深度上限；完整类型见公开类型视图。
- popperInstanceRef.state.reset: boolean — 依赖声明
  枚举：false / true
popperInstanceRef.destroy: () => void — 依赖声明
事件参数：(): void
popperInstanceRef.forceUpdate: () => void — 依赖声明
事件参数：(): void
popperInstanceRef.update: PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "update"> — 依赖声明
事件参数：(): ReturnType<Extract<NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "update">>, (...args: never[]) => unknown>>
popperInstanceRef.setOptions: PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "setOptions"> — 依赖声明
事件参数：(setOptionsAction: Parameters<Extract<NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "setOptions">>, (...args: never[]) => unknown>>[0]): ReturnType<Extract<NonNullable<PublicMember<NonNullable<(AsamPopperExpose)["popperInstanceRef"]>, "setOptions">>, (...args: never[]) => unknown>>

`referenceRef`

必填：是；声明来源：上游声明。

referenceRef 参数与事件数据

下列为声明可读视图；可导入类型以公开类型视图为准。分支条件与父属性一致。

referenceRef.getBoundingClientRect: () => DOMRect — 上游声明
事件参数：(): DOMRect

AsamPopperExpose 公开类型视图

import type { AsamPopperExpose } from '@asam-ui/ui';

type PublicMember<T, K extends PropertyKey> = T extends unknown ? K extends keyof T ? T[K] : never : never;

// AsamPopperExpose
type PublicContract = {
	"role": "group" | "dialog" | "grid" | "listbox" | "menu" | "navigation" | "tooltip" | "tree";
	"triggerRef": (AsamPopperExpose)["triggerRef"];
	"contentRef": HTMLElement | undefined;
	"popperInstanceRef": (AsamPopperExpose)["popperInstanceRef"];
	"referenceRef": (AsamPopperExpose)["referenceRef"];
};

浮层定位容器 AsamPopper

使用场景 ​

触发器、内容与箭头组合 ​

触发器、内容与箭头组合

使用约定 ​

组合职责与生命周期 ​

API

属性 AsamPopperProps

事件 AsamPopperEmits

插槽 AsamPopperSlots

实例方法与状态 AsamPopperExpose

关联组件

参数与事件说明

role

默认值与来源

参数与事件说明

default

参数与事件说明

role

triggerRef

contentRef

popperInstanceRef

referenceRef

使用场景

触发器、内容与箭头组合

使用约定

组合职责与生命周期

属性 `AsamPopperProps`

事件 `AsamPopperEmits`

插槽 `AsamPopperSlots`

实例方法与状态 `AsamPopperExpose`

`role`

`default`

`role`

`triggerRef`

`contentRef`

`popperInstanceRef`

`referenceRef`