UniPage | uni-app-x

展示全部

# UniPage

uni-app x中，每个页面都对应一个UniPage对象。

如果是dialogPage，也可以通过UniPage的getDialogPage方法获取。

通过UniPage对象，可以获取/修改页面的pageStyle，让pages.json中的页面设置可以动态修改；可以继续获取原生页面对象，如原生view；可以继续获取页面的vue示例，通过vm属性。

UniPage在App和Web平台较完善，在小程序端受小程序未开放，很多功能无法实现。具体见兼容性表格。

# UniPage 的属性值

名称

类型

必备

默认值

兼容性

描述

route

string

是

页面的路由地址

options

UTSJSONObject

是

页面的路由参数信息

VueComponent

否

UniPage vue 实例对象

名称

类型

必备

默认值

兼容性

描述

$data

Map<string, any>

是

$props

Map<string, any>

是

$attrs

Map<string, any>

是

$slots

Map<string, any>

是

$refs

Map<string, any>

是

$parent

VueComponent

是

$root

VueComponent

是

$options

VueComponentOptions

是

$el

UniElement

是

$page

UniPage

是

pageBody

UniPageBody

是

UniPage 页面可使用区域信息，单位为px

名称

类型

必备

默认值

兼容性

描述

top

number

是

页面可使用区域左上角纵坐标，单位为px

bottom

number

是

页面可使用区域右下角纵坐标，单位为px

left

number

是

页面可使用区域左上角横坐标，单位为px

right

number

是

页面可使用区域右下角横坐标，单位为px

width

number

是

页面可使用区域的宽度，单位为px

height

number

是

页面可使用区域的高度，单位为px

safeAreaInsets

UniSafeAreaInsets

是

UniPage 安全区域插入位置（与屏幕边界的距离）信息

名称

类型

必备

默认值

兼容性

描述

left

number

是

安全区域左侧插入位置（距离左边边界距离）

right

number

是

安全区域右侧插入位置（距离右边边界距离）

top

number

是

安全区顶部插入位置（距离顶部边界距离）

bottom

number

是

安全区域底部插入位置（距离底部边界距离）

fullscreenElement

UniElement

否

已经进入全屏状态的元素

width

number

是

页面窗口宽度

height

number

是

页面窗口高度

statusBarHeight

number

是

页面状态栏高度

~~$vm~~

VueComponent

否

UniPage vue 实例对象

# UniPage 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
-	-	-	-	-

# UniPage 的方法

# getPageStyle(): UTSJSONObject

获取当前页面样式。详细属性配置请参考PageStyle

# getPageStyle 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.31	x	4.31	4.31	4.31	4.61

# 返回值

类型
UTSJSONObject

# setPageStyle(style: UTSJSONObject): void

设置当前页面样式。详细属性配置请参考PageStyle

# setPageStyle 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.31	x	4.31	4.31	4.31	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

style

UTSJSONObject

是

注意

HBuilderX 4.31+，$getPageStyle和$setPageStyle不再需要加前缀$。
使用选项式 API 时，不可创建 route、options 同名响应式变量，否则会覆盖当前 page 实例 的同名属性。
4.31 前仅 Web 与 iOS(非 uts 插件) 端支持通过 page.$vm 获取 vue 实例。
4.31+ 仅 iOS uts 插件 环境不支持通过 page.vm 获取 vue 实例。

PageStyle

支持当前页面 style 节点属性（注意并非所有 pages.json 的 pageStyle 都可以动态修改）

属性	类型	Android	iOS	HarmonyOS	web	默认值
enablePullDownRefresh	Boolean	4.13	4.13	4.61	4.13	false
backgroundColorContent	String	4.15	4.15	4.61	4.18	#ffffff
navigationBarBackgroundColor	String	4.18	4.18	4.61	4.18	#007AFF
navigationBarTextStyle	String	4.18	4.18	4.61	4.18	white
navigationBarTitleText	String	4.18	4.18	4.61	4.18	""
navigationStyle	String	x	x	4.61	4.18	default
backgroundColor	String	4.18	4.18	4.61	x	#ffffff
backgroundTextStyle	String	4.31	4.31	x	x	dark
onReachBottomDistance	Number	x	x	4.61	4.18	50
pageOrientation	String	4.18	4.25	x	x	auto
disableSwipeBack	Boolean	x	4.18	x	x	false
hideStatusBar	Boolean	4.31	x	x	x	false
hideBottomNavigationIndicator	Boolean	4.31	x	x	x	false

注意事项

web端由于会自动摇树优化未使用的特性，如果整个项目中都没有使用到下拉刷新enablePullDownRefresh，那么下拉刷新功能会被摇掉，此时设置打开下拉刷新将无效。
app-android平台的页面是activity，不支持backgroundColorContent设为透明。
4.15版本前，app-ios平台在page.json 中设置页面 enablePullDownRefresh 为 false 时，无法通过 $setPageStyle 方法动态开启页面下拉刷新。新版已修复该问题。

# getParentPage(): UniPage | null

用于 dialogPage 获取所属父页面

# getParentPage 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.31	x	4.31	4.31	4.31	4.61

# 返回值

类型	必备
UniPage	否

# getDialogPages(): UniPage[]

获取当前页面的 dialog 子页面集合

# getDialogPages 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
4.31	x	4.31	4.31	4.31	4.61

# 返回值

类型
Array<UniPage>

# getElementById(id: string.IDString | string): UniElement | null

返回一个匹配特定 ID 的元素，如果不存在，返回 null。
如果需要获取指定的节点类型，需要使用 as 进行类型转换。
ID 区分大小写，且应该是唯一的。如果存在多个匹配的元素，则返回第一个匹配的元素。

# getElementById 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.31	x	4.31	4.31	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

string.IDString | string

是

# 返回值

类型	必备
UniElement	否

# getAndroidView(): View | null

返回 android 平台页面根 view

# getAndroidView 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
x	x	4.31	x	x

# 返回值

类型	必备
View	否

# getAndroidActivity(): Activity | null

返回 android 平台加载页面内容的Activity

# getAndroidActivity 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
x	x	4.61	x	x

# 返回值

类型	必备
Activity	否

# getIOSView(): UIView | null

返回 ios 平台页面根 view

# getIOSView 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	x	x	x	4.33	x

# 返回值

类型	必备
UIView	否

# getHTMLElement(): UniElement | null

返回页面 HTML Element 对象

# getHTMLElement 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.31	x	x	x	x

# 返回值

类型	必备
UniElement	否

# exitFullscreen(options: ExitFullscreenOptions|null) : void

将当前在全屏模式下显示的元素退出全屏模式，恢复全屏之前的状态

用于逆转先前调用 UniElement.requestFullscreen 的效果。

# exitFullscreen 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
x	x	4.61	x	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

options

ExitFullscreenOptions

否

名称

类型

必备

默认值

兼容性

描述

success

() => void

否

成功回调

fail

(error: IFullscreenError) => void

否

失败回调

complete

(result?: any) => void

否

完成回调

# IFullscreenError 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

number

是

错误码

合法值

兼容性

描述

106600

当前页面已经有element处于全屏状态

106601

当前element不支持全屏

106602

当前页面没有element处于全屏状态

106603

页面已销毁或者尚未就绪

106604

组件未就绪

errSubject

string

是

统一错误主题（模块）名称

data

any

否

错误信息中包含的数据

cause

Error

否

源错误信息，可以包含多个错误，详见SourceError

errMsg

string

是

# $setPageStyle(style: UTSJSONObject): void

设置当前页面样式。详细属性配置请参考PageStyle 已废弃，仅为了向下兼容保留

# $setPageStyle 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.13	x	4.13	4.13	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

style

UTSJSONObject

是

# $getPageStyle(): UTSJSONObject

获取当前页面样式。详细属性配置请参考PageStyle 已废弃，仅为了向下兼容保留

# $getPageStyle 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.13	x	4.13	4.13	4.61

# 返回值

类型
UTSJSONObject

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

示例

<template>
  <!-- #ifdef APP -->
  <scroll-view class="page-scroll-view">
  <!-- #endif -->
    <view>
      <page-head title="getCurrentPages"></page-head>
      <view class="uni-padding-wrap">
        <button @click="_getCurrentPages">getCurrentPages</button>
        <view v-if="pages.length" style="padding: 15px 0px">
          <text>当前页面栈中 {{ pages.length }} 个页面，列表如下：</text>
          <template v-for="(page, index) in pages" :key="page.route">
            <text style="margin-top: 5px">index: {{ index }}, route: {{ page.route }}</text>
          </template>
        </view>
        <!-- #ifndef MP -->
        <button class="uni-common-mt" @click="check$page">check $page</button>
        <button class="uni-common-mt" @click="checkGetParentPage">
          check getParentPage
        </button>
        <button class="uni-common-mt" @click="checkGetDialogPages">
          check getDialogPages
        </button>
        <button id="check-get-element-by-id-btn" class="uni-common-mt" @click="checkGetElementById">
          check getElementById
        </button>
        <button class="uni-common-mt" @click="checkGetAndroidView">
          check getAndroidView
        </button>
        <button class="uni-common-mt" @click="checkGetIOSView">
          check getIOSView
        </button>
        <button class="uni-common-mt" @click="checkGetHTMLElement">
          check getHTMLElement
        </button>
        <!-- #endif -->
        <!-- #ifdef APP-ANDROID -->
        <button class="uni-common-mt" @click="checkGetAndroidActivity">
          check getAndroidActivity
        </button>
        <!-- #endif -->
      </view>
      <!-- #ifndef MP -->
      <page-head title="currentPageStyle"></page-head>
      <template v-for="(item, index) in PageStyleArray">
        <view class="page-style-item" v-if="currentPageStyle[item.key] != null" :key="index">
          <view class="item-text">
            <text class="item-text-key">{{ item.key }}:</text>
            <text class="item-text-value">{{
              currentPageStyle[item.key]
            }}</text>
          </view>
          <view class="set-value" v-if="item.type == 'boolean'">
            <switch :checked="currentPageStyle.getBoolean(item.key)"
              @change="switchChange(item.key, $event as UniSwitchChangeEvent)">
            </switch>
          </view>
          <view class="set-value" v-else-if="item.type == 'number'">
            <slider :value="currentPageStyle.getNumber(item.key)" :show-value="true"
              @change="sliderChange(item.key, $event as UniSliderChangeEvent)" />
          </view>
          <view class="set-value" v-else-if="item.type == 'string'">
            <radio-group class="radio-set-value" @change="radioChange(item.key, $event as RadioGroupChangeEvent)">
              <radio class="radio-value" v-for="(item2, index2) in item.value" :key="index2" :value="item2">{{ item2 }}
              </radio>
            </radio-group>
          </view>
        </view>
      </template>
      <!-- #ifndef APP-HARMONY -->
      <button style="margin: 10px" @click="goSetDisablePullDownRefresh">
        go set disable pullDownRefresh
      </button>
      <!-- #endif -->
      <!-- #endif -->
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

<script>
  import { PageStyleItem, PageStyleArray } from './page-style.uts';

  class Page {
    constructor(public route : string) {
    }
  }

  export default {
    data() {
      return {
        checked: false,
        pages: [] as Page[],
        PageStyleArray: PageStyleArray as PageStyleItem[],
        currentPageStyle: {} as UTSJSONObject,
        testing: false
      }
    },
    computed: {
      pageStyleText() : string {
        return JSON.stringify(this.currentPageStyle)
      }
    },
    // #ifndef MP
    onLoad() {
      this.getPageStyle();
    },
    // #endif
    onReady() {
      // #ifdef APP-ANDROID
      this.setPageStyle({
        'androidThreeButtonNavigationBackgroundColor': 'transparent',
        'androidThreeButtonNavigationStyle': 'black'
      });
      this.getPageStyle();
      // #endif
    },
    onPullDownRefresh() {
      setTimeout(() => {
        uni.stopPullDownRefresh()
      }, 2000)
    },
    methods: {
      startPullDownRefresh() {
        uni.startPullDownRefresh()
      },
      _getCurrentPages: function () {
        this.pages.length = 0
        const pages = getCurrentPages()
        this.pages.push(new Page(pages[0].route))
        if (this.pages[0].route.includes('/tabBar/') || this.pages[0].route == '/') {
          this.checked = true
        }
        for (let i = 1; i < pages.length; i++) {
          this.pages.push(new Page(pages[i].route))
          if (pages[i].route.includes('/tabBar/')) {
            this.checked = false
          }
        }
      },
      /// get-set-page-style
      radioChange(key : string, e : RadioGroupChangeEvent) {
        this.setStyleValue(key, e.detail.value);
      },
      sliderChange(key : string, e : UniSliderChangeEvent) {
        this.setStyleValue(key, e.detail.value);
      },
      switchChange(key : string, e : UniSwitchChangeEvent) {
        this.setStyleValue(key, e.detail.value);
      },
      setStyleValue(key : string, value : any) {
        const style = {}
        style[key] = value
        this.setPageStyle(style)
        this.getPageStyle()
      },
      getPageStyle() : UTSJSONObject {
        const pages = getCurrentPages();
        const currentPage = pages[pages.length - 1];
        this.currentPageStyle = currentPage.getPageStyle()
        console.log(this.currentPageStyle)
        return this.currentPageStyle;
      },
      setPageStyle(style : UTSJSONObject) {
        console.log('setPageStyle:', style);
        const pages = getCurrentPages();
        const currentPage = pages[pages.length - 1];
        currentPage.setPageStyle(style);
      },
      goSetDisablePullDownRefresh() {
        uni.navigateTo({
          url: '/pages/API/get-current-pages/set-page-style-disable-pull-down-refresh'
        });
      },
      getCurrentPage() : UniPage {
        const pages = getCurrentPages()
        return pages[pages.length - 1]
      },
      check$page() : boolean {
        const page = this.getCurrentPage()
        let res = this.$page === page
        if (this.testing && res) {
          res = page.options['test'] == '123'
          if (res) {
            res = page.route == 'pages/API/get-current-pages/get-current-pages'
          }
        }
        console.log('check $page', res)
        uni.showToast(res ? { title: 'check success' } : { title: 'check fail', icon: 'error' })
        return res
      },
      checkGetParentPage() : boolean {
        const page = this.getCurrentPage()
        const parentPage = page.getParentPage()
        const res = parentPage == null
        console.log('check getParentPage', res)
        uni.showToast(res ? { title: 'check success' } : { title: 'check fail', icon: 'error' })
        return res
      },
      checkGetDialogPages() : boolean {
        const page = this.getCurrentPage()
        const dialogPages = page.getDialogPages()
        const res = Array.isArray(dialogPages) && dialogPages.length == 0
        uni.showToast(res ? { title: 'check success' } : { title: 'check fail', icon: 'error' })
        console.log('check getDialogPages', res)
        return res
      },
      checkGetElementById() : boolean {
        const page = this.getCurrentPage()
        const element = page.getElementById('check-get-element-by-id-btn')
        let res = element != null
        // #ifndef APP-ANDROID
        if (res) {
          const elPage = element!.getPage()
          console.log('elPage', elPage)
          res = elPage === page
        }
        // #endif
        console.log('check getElementById', res)
        uni.showToast(res ? { title: 'check success' } : { title: 'check fail', icon: 'error' })
        return res
      },
      checkGetAndroidView() : boolean {
        const page = this.getCurrentPage()
        const androidView = page.getAndroidView()
        const res = androidView != null
        console.log('check getAndroidView', res)
        uni.showToast(res ? { title: 'check success' } : { title: 'check fail', icon: 'error' })
        return res
      },
      checkGetIOSView() : boolean {
        const page = this.getCurrentPage()
        const IOSView = page.getIOSView()
        const res = IOSView != null
        console.log('check getIOSView', res)
        uni.showToast(res ? { title: 'check success' } : { title: '仅 IOS uts 插件环境支持', icon: 'error' })
        return res
      },
      checkGetHTMLElement() : boolean {
        const page = this.getCurrentPage()
        const HTMLView = page.getHTMLElement()
        const res = HTMLView != null
        console.log('check getHTMLElement', res)
        uni.showToast(res ? { title: 'check success' } : { title: 'check fail', icon: 'error' })
        return res
      },
      checkGetAndroidActivity() : boolean {
        const page = this.getCurrentPage()
        const activity = page.getAndroidActivity()
        const res = activity != null
        console.log('check getAndroidActivity', res)
        uni.showToast(res ? { title: 'check success' } : { title: 'check getAndroidActivity', icon: 'error' })
        return res
      }
    },
  }
</script>

<style>
  .page {
    flex: 1;
    padding: 10px;
  }

  .page-style {
    margin-top: 15px;
  }

  .page-style-item {
    padding: 10px;
    margin-top: 10px;
    background-color: #ffffff;
    border-radius: 5px;
  }

  .item-text {
    flex-direction: row;
  }

  .item-text-key {
    font-weight: bold;
  }

  .item-text-value {
    margin-left: 5px;
  }

  .set-value {
    margin-top: 10px;
  }

  .radio-set-value {
    flex-direction: row;
  }

  .radio-value {
    margin-left: 10px;
  }
</style>

运营产品

uni-ad uni统计 uni发行 uni安全专题

开发者服务

问答社区开发者后台

技术文档

uni-app文档 uniCloud文档原生开发者支持文档 HBuilder文档

生态服务

插件市场 OAuth用户开放平台

关于我们： DCloud官网案例需求墙许可协议加入我们赞助我们

联系我们：商务合作：bd@dcloud.io 广告合作：uniad@dcloud.io

DCloud.io 数字天堂（北京）网络技术有限公司是

HTML5中国产业联盟发起单位

京公网安备：11010802035340号

国家信息安全等级保护三级，证书编号：11010813802-20001

# UniPage

# UniPage 的属性值

# UniPage 兼容性

# UniPage 的方法

# getPageStyle(): UTSJSONObject

# getPageStyle 兼容性

# 返回值

# setPageStyle(style: UTSJSONObject): void

# setPageStyle 兼容性

# 参数

# getParentPage(): UniPage | null

# getParentPage 兼容性

# 返回值

# getDialogPages(): UniPage[]

# getDialogPages 兼容性

# 返回值

# getElementById(id: string.IDString | string): UniElement | null

# getElementById 兼容性

# 参数

# 返回值

# getAndroidView(): View | null

# getAndroidView 兼容性

# 返回值

# getAndroidActivity(): Activity | null

# getAndroidActivity 兼容性

# 返回值

# getIOSView(): UIView | null

# getIOSView 兼容性

# 返回值

# getHTMLElement(): UniElement | null

# getHTMLElement 兼容性

# 返回值

# exitFullscreen(options: ExitFullscreenOptions|null) : void

# exitFullscreen 兼容性

# 参数

# IFullscreenError 的属性值

# $setPageStyle(style: UTSJSONObject): void

# $setPageStyle 兼容性

# 参数

# $getPageStyle(): UTSJSONObject

# $getPageStyle 兼容性

# 返回值

# 示例

本页导读