TopTips 顶部提示

17:06

说明

页面顶部滑入的轻提示，通过组件实例的 show({ title, type, duration }) 弹出，到时自动收起。默认自动避让状态栏与自绘导航栏，也可用 navbarHeight 显式指定；支持 primary / success / warning / error / info 五种主题。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

通过 ref 调用 show() 弹出提示，默认 primary 主题，2 秒后自动收起。

查看源码

<template>
    <ux-button type="primary" shape="round" text="弹出提示" @click="showBasic" />
    <ux-top-tips ref="tipsRef" />
</template>

<script setup lang="uts">
const tipsRef = ref<any>();

const showBasic = () => {
    tipsRef.value?.show?.({
        title: '这是一条顶部提示'
    });
};
</script>

主题 type

show({ type }) 支持 primary / success / warning / error / info 五种主题。

查看源码

<template>
    <view class="top-tips-row">
        <ux-button custom-class="top-tips-item" type="primary" size="small" shape="round" text="primary 主题" @click="showType('primary')" />
        <ux-button custom-class="top-tips-item" type="success" size="small" shape="round" text="success 主题" @click="showType('success')" />
        <ux-button custom-class="top-tips-item" type="warning" size="small" shape="round" text="warning 主题" @click="showType('warning')" />
        <ux-button custom-class="top-tips-item" type="error" size="small" shape="round" text="error 主题" @click="showType('error')" />
        <ux-button custom-class="top-tips-item" type="info" size="small" shape="round" text="info 主题" @click="showType('info')" />
    </view>
    <ux-top-tips ref="tipsRef" />
</template>

<script setup lang="uts">
const tipsRef = ref<any>();

const showType = (type: string) => {
    tipsRef.value?.show?.({
        title: '这是一条顶部提示',
        type
    });
};
</script>

<style scoped>
.top-tips-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.top-tips-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

显示时长 duration

show({ duration }) 控制提示停留时长（毫秒）。

查看源码

<template>
    <view class="top-tips-row">
        <ux-button custom-class="top-tips-item" type="primary" size="small" shape="round" text="停留 1 秒" @click="showDuration(1000)" />
        <ux-button custom-class="top-tips-item" type="primary" size="small" shape="round" text="停留 3 秒" @click="showDuration(3000)" />
    </view>
    <ux-top-tips ref="tipsRef" />
</template>

<script setup lang="uts">
const tipsRef = ref<any>();

const showDuration = (duration: number) => {
    tipsRef.value?.show?.({
        title: '这是一条顶部提示',
        duration
    });
};
</script>

<style scoped>
.top-tips-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
}
.top-tips-item {
    margin-right: 8px;
    margin-bottom: 8px;
}
</style>

导航栏高度与层级

navbar-height 适配页面导航栏高度（px），z-index 控制提示条层级。

查看源码

<template>
    <ux-button type="warning" shape="round" text="从导航栏下方弹出" @click="showNav" />
    <ux-top-tips ref="tipsRef" :navbar-height="navBarHeight" :z-index="9999" />
</template>

<script setup lang="uts">
import { useWindowInfo, useDeviceInfo } from '@/uni_modules/uview-pro-x';

const { statusBarHeight } = useWindowInfo();
const { platform } = useDeviceInfo();

const tipsRef = ref<any>();

// 顶部避让总高度 = 状态栏 + 自绘导航栏本体（取法与页面 ux-navbar 默认高度一致）
const navBarHeight = computed((): number => {
    let body = 44;
    // #ifdef MP
    body = platform.value == 'ios' ? 44 : 48;
    // #endif
    return statusBarHeight.value + body;
});

const showNav = () => {
    tipsRef.value?.show?.({
        title: '已适配导航栏高度',
        duration: 3000
    });
};
</script>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	String	''	-
customClass	自定义根节点样式类	String	''	-
navbarHeight	顶部避让总高度（包含状态栏高度在内），单位 px；传 0（默认）时自动取「状态栏 + 平台默认导航栏高度」（App/H5 为 44，小程序 iOS 44 / 安卓 48；H5 无状态栏即 44），自定义导航栏页面直接弹出在导航栏下沿	Number|String	0	-
zIndex	提示条 z-index，默认取 $u.zIndex.topTips	Number|String	-	-

Events

ux-top-tips 无事件。

Slots

ux-top-tips 无插槽。

注意事项

1. 只能通过实例 show() 触发，没有 show 属性或 v-model；重复调用会清掉上一个定时器并重新计时。
2. 调用时未传 type / duration 会沿用上一次的值（首次为 primary / 2000ms），不是每次都重置为默认值。
3. navbarHeight=0（默认）时自动取「状态栏 + 导航栏」：App 与 H5 为 44，小程序 iOS 44 / 安卓 48；H5 无系统状态栏，实际结果为 44。自定义导航栏页面可显式传入完整避让高度。
4. 隐藏时 z-index 置为 -1，显示时才使用 zIndex（默认 $u.zIndex.topTips），避免遮挡页面其他元素。
5. 微信小程序端禁用了常驻 transition，入场改用一次性 keyframes，动画细节与其他端略有差异。