Skip to content

feat: support nvue pages #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
skiyee merged 7 commits into from
Jul 25, 2026
Merged

feat: support nvue pages #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fc80c34
feat: support nvue pages
Jul 24, 2026
3db2f0f
refactor: 整理 nvue 页面路径与相对路径工具
skiyee Jul 25, 2026
439b000
fix(examples): 将示例组件标签改为 view
skiyee Jul 25, 2026
a50c6af
chore(examples): 补充 App 平台依赖与脚本
skiyee Jul 25, 2026
ba667fb
feat(examples): 增加 nvue 演示页面
skiyee Jul 25, 2026
e6a509c
test: 增加 examples nvue 转换校验
skiyee Jul 25, 2026
9916d41
docs: 精简 README 中的 nvue 说明
skiyee Jul 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
- 自定义虚拟根组件文件命名(App.ku.vue文件命名支持更换)
- 更高灵活度的获取虚拟根组件实例(获取KuRootView的Ref)
- 自动提取PageMeta到页面顶层(自动提升小程序PageMeta[用于阻止滚动穿透]组件)
- 支持 nvue 页面使用虚拟根组件

### 📦 安装

Expand Down Expand Up @@ -535,7 +536,7 @@ function showToast() {
- [x] 支持热更新
- [x] 支持VueSFC
- [x] 支持小程序PageMeta
- [ ] 支持 App.ku.vue 内直接编写控制逻辑
- [x] 支持 nvue 页面
- [ ] 补全单元测试

### 🤔 与uni-helper-layouts的区别
Expand Down
6 changes: 5 additions & 1 deletion examples/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,14 @@
"dev": "uni",
"build": "uni build",
"dev:mp-weixin": "uni -p mp-weixin",
"build:mp-weixin": "uni build -p mp-weixin"
"build:mp-weixin": "uni build -p mp-weixin",
"dev:app": "uni -p app",
"build:app": "uni build -p app"
},
"dependencies": {
"@dcloudio/uni-app": "3.0.0-4040520250104002",
"@dcloudio/uni-app-plus": "3.0.0-4040520250104002",
"@dcloudio/uni-app-vite": "3.0.0-4040520250104002",
"@dcloudio/uni-components": "3.0.0-4040520250104002",
"@dcloudio/uni-h5": "3.0.0-4040520250104002",
"@dcloudio/uni-mp-weixin": "3.0.0-4040520250104002",
Expand Down
38 changes: 19 additions & 19 deletions examples/src/KuRoot.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
<script setup lang="ts">
import { ref } from 'vue'
import GlobalToast from './components/GlobalToast.vue'

const HelloVueRef = ref('Hello app.Ku.vue')

const exposeRef = ref('this is form app.Ku.vue')

defineExpose({
exposeRef,
})
</script>

<template>
<div>Hello AppKuVue</div>
<KuRootView />
<div>{{ HelloVueRef }}</div>
<GlobalToast />
</template>
<script setup lang="ts">
import { ref } from 'vue'
import GlobalToast from './components/GlobalToast.vue'
const HelloVueRef = ref('Hello app.Ku.vue')
const exposeRef = ref('this is form app.Ku.vue')
defineExpose({
exposeRef,
})
</script>
<template>
<view>Hello AppKuVue</view>
<KuRootView />
<view>{{ HelloVueRef }}</view>
<GlobalToast />
</template>
64 changes: 32 additions & 32 deletions examples/src/components/GlobalToast.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,32 @@
<script setup lang="ts">
import { useToast } from '@/composables/useToast'

const { globalToastState, hideToast } = useToast()
</script>

<template>
<div v-if="globalToastState" class="toast-wrapper" @click="hideToast">
<div class="toast-box">
welcome to use @uni-ku/root
</div>
</div>
</template>

<style scoped>
.toast-wrapper{
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 100%;
background-color: rgba(0, 0, 0, 0.5);
display: flex;
align-items: center;
justify-content: center;
}

.toast-box{
background: white;
color: black;
}
</style>
<script setup lang="ts">
import { useToast } from '@/composables/useToast'
const { globalToastState, hideToast } = useToast()
</script>
<template>
<view v-if="globalToastState" class="toast-wrapper" @click="hideToast">
<view class="toast-box">
welcome to use @uni-ku/root
</view>
</view>
</template>
<style scoped>
.toast-wrapper{
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 100%;
Comment on lines +16 to +21

@coderabbitai coderabbitai Bot Jul 25, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Files of interest:\n'
git ls-files | rg '(^|/)GlobalTo(ast)?\.vue$|KuRoot\.vue$|nvue|package\.json$|manifest\.json$' || true

printf '\nGlobalToast.vue excerpt:\n'
if [ -f examples/src/components/GlobalToast.vue ]; then
  nl -ba examples/src/components/GlobalToast.vue | sed -n '1,120p'
fi

printf '\nKuRoot.vue excerpt around GlobalToast import/use:\n'
if [ -f examples/src/KuRoot.vue ]; then
  nl -ba examples/src/KuRoot.vue | sed -n '1,160p'
fi

printf '\nSearch for GlobalToast usage/import:\n'
rg -n "GlobalToast|toast" examples/src -S || true

printf '\nPackage/uniplatform hints:\n'
for f in package.json examples/package.json manifest.json examples/manifest.json; do
  if [ -f "$f" ]; then
    echo "--- $f"
    sed -n '1,220p' "$f"
  fi
done

Repository: uni-ku/root

Length of output: 458

🌐 Web query:

uniapp NVUE CSS width: 100% height: 100% unsupported percentage layout

💡 Result:

In uni-app, nvue pages render using native components rather than a webview, which imposes specific limitations on CSS [1][2][3]. Percentage-based layout, such as width: 100% or height: 100%, is not supported in nvue [4][5][6][1]. This is because the underlying native layout engine only supports Flexbox [4][6], and percentage values are not valid units in this native environment [5][7]. To achieve full-width or full-height layouts in nvue, you should use the following alternatives: For full width: Use width: 750rpx [5][7]. In uni-app, 750rpx is defined as the total width of the screen [5]. For full height: Use flex: 1 on the container [5][7]. This instructs the element to occupy the available remaining space within its parent, effectively filling the container's height when the parent is also set up correctly or occupies the screen [5]. Summary of constraints: 1. Percentage units (%, vh, vw, rem) are not supported [5][7][1]. 2. CSS layout must be based on Flexbox [4][6]. 3. Only px (absolute pixels) and rpx (relative pixels) are supported for length units [5][1]. If you need to set a container to be full-screen, ensure that all parent elements also have their height managed (e.g., using flex: 1) to ensure the layout propagates correctly to the bottom of the screen [5].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'GlobalToast.vue excerpt:\n'
awk '{printf "%4d: %s\n", NR, $0}' examples/src/components/GlobalToast.vue | sed -n '1,160p'

printf '\nKuRoot.vue excerpt around GlobalToast import/use:\n'
awk '{printf "%4d: %s\n", NR, $0}' examples/src/KuRoot.vue | sed -n '1,220p'

printf '\nSearch for GlobalToast usage/import:\n'
rg -n "GlobalToast|<GlobalToast|toast-wrapper|toast" examples/src -S || true

printf '\nnvue platform files summary:\n'
for f in examples/src/manifest.json examples/src/pages/nvue-demo.nvue examples/src/pages/nvue-options.nvue test/examples-nvue.test.ts; do
  if [ -f "$f" ]; then
    echo "--- $f"
    awk '{printf "%4d: %s\n", NR, $0}' "$f" | sed -n '1,220p'
  fi
done

Repository: uni-ku/root

Length of output: 9233

Avoid percentage dimensions in the NVUE toast overlay.

NVUE does not support percentage layout units, so width: 100% / height: 100% on the shared GlobalToast wrapper may not cover the page reliably. Use anchor offsets or NVUE-supported dimensions here.

Proposed fix 
 .toast-wrapper{
   position: fixed;
   top: 0;
   left: 0;
-  width: 100%;
-  height: 100%;
+  right: 0;
+  bottom: 0;
   background-color: rgba(0, 0, 0, 0.5);
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
.toast-wrapper{
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 100%;
.toast-wrapper{
position: fixed;
top: 0;
left: 0;
right: 0;
bottom: 0;
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/src/components/GlobalToast.vue` around lines 16 - 21, Update the
.toast-wrapper styles in GlobalToast so the NVUE overlay fills the page without
using percentage width or height; replace those percentage dimensions with
NVUE-supported anchor offsets or dimensions while preserving its fixed, top-left
positioning.

Source: MCP tools

background-color: rgba(0, 0, 0, 0.5);
display: flex;
align-items: center;
justify-content: center;
}
.toast-box{
background: white;
color: black;
}
</style>
12 changes: 6 additions & 6 deletions examples/src/layouts/default.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<template>
<div>
<slot />
Default Layout
</div>
</template>
<template>
<view>
<slot />
Default Layout
</view>
</template>
12 changes: 12 additions & 0 deletions examples/src/pages.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,18 @@
"style": {
"navigationBarTitleText": "uni-app"
}
},
{
"path": "pages/nvue-demo",
"style": {
"navigationBarTitleText": "nvue demo"
}
},
{
"path": "pages/nvue-options",
"style": {
"navigationBarTitleText": "nvue options"
}
}
],
"globalStyle": {
Expand Down
14 changes: 14 additions & 0 deletions examples/src/pages/index.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,14 @@ function handleClick() {
return globalToastState.value ? hideToast() : showToast()
}

function goNvueDemo() {
uni.navigateTo({ url: '/pages/nvue-demo' })
}

function goNvueOptions() {
uni.navigateTo({ url: '/pages/nvue-options' })
}

const uniKuRoot = ref()

onMounted(() => {
Expand All @@ -32,6 +40,12 @@ const color = 'red'
<button @click="handleClick">
展示Toast
</button>
<button @click="goNvueDemo">
打开 NVUE Demo
</button>
<button @click="goNvueOptions">
打开 NVUE Options
</button>
</LayoutDefault>
</template>

Expand Down
39 changes: 39 additions & 0 deletions examples/src/pages/nvue-demo.nvue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const pageLabel = ref('Hello NVUE + UniKuRoot')
const uniKuRoot = ref()

onMounted(() => {
// eslint-disable-next-line no-console
console.log('[nvue-demo] exposeRef from KuRoot:', uniKuRoot.value?.exposeRef)
})
</script>

<template root="uniKuRoot">
<view class="page">
<text class="title">{{ pageLabel }}</text>
<text class="hint">This page is .nvue and should be wrapped by local GlobalKuRoot.</text>
<text class="hint">Check console for KuRoot exposeRef after mount.</text>
</view>
</template>

<style>
.page {
flex: 1;
padding: 24px;
background-color: #f8f8f8;
}

.title {
font-size: 20px;
color: #111111;
margin-bottom: 12px;
}

.hint {
font-size: 14px;
color: #666666;
margin-bottom: 8px;
}
</style>
35 changes: 35 additions & 0 deletions examples/src/pages/nvue-options.nvue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
<template root="kuRoot">
<view class="page">
<text class="title">{{ title }}</text>
<text class="hint">Options API nvue page with local GlobalKuRoot registration.</text>
</view>
</template>

<script>
export default {
data() {
return {
title: 'Hello NVUE Options API',
}
},
}
</script>

<style>
.page {
flex: 1;
padding: 24px;
background-color: #ffffff;
}

.title {
font-size: 20px;
color: #111111;
margin-bottom: 12px;
}

.hint {
font-size: 14px;
color: #666666;
}
</style>
1 change: 1 addition & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
"example:build:h5": "pnpm build && pnpm -C examples run build",
"example:dev:mp-weixin": "pnpm build && pnpm -C examples run dev:mp-weixin",
"example:build:mp-weixin": "pnpm build && pnpm -C examples run build:mp-weixin",
"example:verify:nvue": "vitest run test/examples-nvue.test.ts",
"prepare": "simple-git-hooks",
"lint": "eslint . --fix",
"prepublishOnly": "pnpm build"
Expand Down
Loading