wevu 6.10.2 → 6.11.1

package/README.md

@@ -144,7 +144,7 @@ const onActiveChange = bindModel.model<boolean>('isActive').onChange
 
 - 更新被批量加入微任务队列，`nextTick` 与 Vue 3 行为一致。
 - 对状态做快照 diff，只把变更路径传给 `setData`，避免大对象全量下发。
-- 提供 `batch`/`startBatch`/`endBatch` 用于同步更新合并触发；以及 `effectScope`/`onScopeDispose` 统一管理 effect/watch 的销毁，便于避免泄漏。
+- 提供 `batch`/`startBatch`/`endBatch` 用于同步更新合并触发；以及 `effectScope`/`getCurrentScope`/`onScopeDispose` 统一管理 effect/watch 的销毁，`setup()` 同步阶段内创建的副作用会自动归属到实例级 scope，便于避免泄漏。
 
 ## 本地开发
 

package/dist/index.d.mts

@@ -143,6 +143,14 @@ declare function isRaw(value: unknown): boolean;
  */
 declare function readonly<T extends object>(target: T): T;
 declare function readonly<T>(target: Ref<T>): Readonly<Ref<T>>;
+/**
+ * 与 Vue 3 的 `shallowReadonly()` 对齐。
+ *
+ * 当前 wevu 的只读语义本身就是浅层只读，因此这里直接复用同一套实现，
+ * 让依赖 Vue 兼容 API 的代码可以无缝迁移。
+ */
+declare function shallowReadonly<T extends object>(target: T): Readonly<T>;
+declare function shallowReadonly<T>(target: Ref<T>): Readonly<Ref<T>>;
 //#endregion
 //#region src/reactivity/shallowRef.d.ts
 declare function shallowRef<T>(value: T): Ref<T>;
@@ -387,11 +395,13 @@ interface RuntimeInstance<D extends object, C extends ComputedDefinitions, M ext
 }
 interface InternalRuntimeStateFields {
   __wevu?: RuntimeInstance<any, any, any>;
+  __wevuSetPageLayout?: (layout: string | false, props?: Record<string, any>) => void;
   __wevuWatchStops?: WatchStopHandle[];
   $wevu?: RuntimeInstance<any, any, any>;
   __wevuHooks?: Record<string, any>;
   __wevuExposed?: Record<string, any>;
   __wevuAttrs?: Record<string, any>;
+  __wevuEffectScope?: EffectScope;
   __wevuPropKeys?: string[];
   __wevuTemplateRefs?: unknown[];
   __wevuTemplateRefMap?: Map<string, Ref<any>>;
@@ -662,6 +672,7 @@ interface SetDataDebugInfo {
 }
 //#endregion
 //#region src/runtime/types/options.d.ts
+type DataOption<D extends object> = D | (() => D);
 interface DefineComponentOptions<P extends ComponentPropsOptions = ComponentPropsOptions, D extends object = Record<string, any>, C extends ComputedDefinitions = ComputedDefinitions, M extends MethodDefinitions = MethodDefinitions, S extends Record<string, any> | void = Record<string, any> | void> extends MiniProgramComponentOptions, MiniProgramPageLifetimes {
   /**
    * 页面特性开关（用于按需注入 Page 事件处理函数）。
@@ -691,7 +702,7 @@ interface DefineComponentOptions<P extends ComponentPropsOptions = ComponentProp
   /**
    * 组件 data（建议使用函数返回初始值）。
    */
-  data?: () => D;
+  data?: DataOption<D>;
   /**
    * 组件 computed（会参与快照 diff）。
    */
@@ -717,7 +728,7 @@ interface DefineAppOptions<D extends object = Record<string, any>, C extends Com
   [key: string]: any;
 }
 interface CreateAppOptions<D extends object = Record<string, any>, C extends ComputedDefinitions = ComputedDefinitions, M extends MethodDefinitions = MethodDefinitions> extends MiniProgramAppOptions {
-  data?: () => D;
+  data?: DataOption<D>;
   computed?: C;
   methods?: M;
   setData?: SetDataSnapshotOptions;
@@ -1064,6 +1075,31 @@ declare function useIntersectionObserver(options?: UseIntersectionObserverOption
 declare function markNoSetData<T extends object>(value: T): T;
 declare function isNoSetData(value: unknown): boolean;
 //#endregion
+//#region src/runtime/pageLayout.d.ts
+interface WevuPageLayoutMap {}
+type ResolveTypedPageLayoutName = keyof WevuPageLayoutMap extends never ? string : Extract<keyof WevuPageLayoutMap, string>;
+type ResolveTypedPageLayoutProps<Name extends string> = Name extends keyof WevuPageLayoutMap ? WevuPageLayoutMap[Name] : Record<string, any>;
+type PageLayoutNamedState = { [Name in ResolveTypedPageLayoutName]: {
+  name: Name;
+  props: ResolveTypedPageLayoutProps<Name>;
+} }[ResolveTypedPageLayoutName];
+type PageLayoutState = PageLayoutNamedState | {
+  name: false;
+  props: Record<string, any>;
+} | {
+  name: undefined;
+  props: Record<string, any>;
+};
+/**
+ * 获取当前页面 layout 状态。
+ */
+declare function usePageLayout(): Readonly<PageLayoutState>;
+declare function syncRuntimePageLayoutState(target: Record<string, any>, layout: string | false, props: Record<string, any>): void;
+declare function syncRuntimePageLayoutStateFromRuntime(target: Record<string, any>): void;
+declare function setPageLayout(layout: false): void;
+declare function setPageLayout<Name extends ResolveTypedPageLayoutName>(layout: Name, props?: ResolveTypedPageLayoutProps<Name>): void;
+declare function resolveRuntimePageLayoutName(layout: string | false): string;
+//#endregion
 //#region src/runtime/pageScroll.d.ts
 interface UsePageScrollThrottleOptions {
   /**
@@ -1091,6 +1127,13 @@ type UsePageScrollThrottleStopHandle = () => void;
 declare function usePageScrollThrottle(handler: (opt: WechatMiniprogram.Page.IPageScrollOption) => void, options?: UsePageScrollThrottleOptions): UsePageScrollThrottleStopHandle;
 //#endregion
 //#region src/runtime/provide.d.ts
+/**
+ * 判断当前是否存在可用的注入上下文。
+ *
+ * wevu 目前的依赖注入上下文来自同步 `setup()` 阶段的当前实例；
+ * 若未来补充 app 级 provider，这里可继续扩展判断来源。
+ */
+declare function hasInjectionContext(): boolean;
 /**
  * 在组件上下文中向后代注入值（与 Vue 3 行为兼容），若没有当前实例则回落到全局存储。
  *
@@ -1341,6 +1384,18 @@ declare function defineOptions<D extends object = Record<string, any>, C extends
  * defineSlots 声明 slots 类型（仅类型层）。
  */
 declare function defineSlots<T extends Record<string, any> = Record<string, any>>(): T;
+type PageLayoutMeta = string | false | {
+  name: string;
+  props?: Record<string, unknown>;
+};
+interface PageMeta {
+  layout?: PageLayoutMeta;
+  [key: string]: unknown;
+}
+/**
+ * definePageMeta 声明页面级元信息（仅类型层）。
+ */
+declare function definePageMeta(meta: PageMeta): void;
 /**
  * defineModel 声明 v-model 绑定（类型层宏）。
  */
@@ -1361,4 +1416,4 @@ declare function defineModel<T = any, M extends PropertyKey = string, G = T, S =
 declare function defineModel<T = any, M extends PropertyKey = string, G = T, S = T>(options?: DefineModelBaseOptions<T | undefined, M, G | undefined, S | undefined>): ModelRef<T | undefined, M, G | undefined, S | undefined>;
 declare function defineModel<T = any, M extends PropertyKey = string, G = T, S = T>(name?: string, options?: DefineModelBaseOptions<T | undefined, M, G | undefined, S | undefined>): ModelRef<T | undefined, M, G | undefined, S | undefined>;
 //#endregion
-export { ActionContext, ActionSubscriber, type AllowedComponentProps, type AppConfig, type ComponentCustomProps, ComponentDefinition, type ComponentOptionsMixin, type ComponentPropsOptions, type ComponentPublicInstance, type ComponentTypeEmits, type ComputedDefinitions, ComputedGetter, ComputedRef, ComputedSetter, type CreateAppOptions, CustomRefFactory, CustomRefOptions, CustomRefSource, type DefineAppOptions, type DefineComponent, type DefineComponentOptions, DefineModelModifiers, DefineModelTransformOptions, DefineStoreOptions, DisposableBag, DisposableLike, DisposableMethodName, DisposableObject, EffectScope, type EmitFn, type EmitsOptions, type ExtractComputed, type ExtractDefaultPropTypes, type ExtractMethods, type ExtractPropTypes, type ExtractPublicPropTypes, GlobalComponents, GlobalDirectives, type InferNativePropType, type InferNativeProps, type InferPropType, type InferProps, type InternalRuntimeState, type InternalRuntimeStateFields, type MapSources, MaybeRef, MaybeRefOrGetter, type MaybeUndefined, type MethodDefinitions, type MiniProgramAdapter, type MiniProgramAppOptions, type MiniProgramBehaviorIdentifier, type MiniProgramComponentBehaviorOptions, type MiniProgramComponentOptions, type MiniProgramComponentRawOptions, type MiniProgramInstance, type MiniProgramPageLifetimes, type ModelBinding, type ModelBindingOptions, type ModelBindingPayload, ModelModifiers, ModelRef, type MultiWatchSources, type MutationKind, type MutationOp, type MutationRecord, MutationType, type NativeComponent, type NativePropType, type NativePropsOptions, type NativeTypeHint, type NativeTypedProperty, type ObjectDirective, type OnCleanup, type PageFeatures, type PrelinkReactiveTreeOptions, type PropConstructor, type PropOptions, type PropType, type PublicProps, Ref, type RuntimeApp, type RuntimeInstance, type SetDataDebugInfo, type SetDataSnapshotOptions, type SetupContext, type SetupContextNativeInstance, type SetupContextRouter, type SetupFunction, ShallowRef, type ShallowUnwrapRef, StoreManager, StoreSubscribeOptions, StoreToRefsResult, SubscriptionCallback, TemplateRef, TemplateRefValue, TemplateRefs, ToRefs, type TriggerEventOptions, UpdatePerformanceListener, UpdatePerformanceListenerResult, UseIntersectionObserverOptions, UseIntersectionObserverResult, UseModelOptions, UsePageScrollThrottleOptions, UsePageScrollThrottleStopHandle, UseUpdatePerformanceListenerStopHandle, type VNode, type VNodeProps, type WatchCallback, type WatchEffect, type WatchEffectOptions, type WatchMultiSources, type WatchOptions, type WatchScheduler, type WatchSource, type WatchSourceValue, type WatchSources, type WatchStopHandle, WevuComponentConstructor, WevuDefaults, WevuGlobalComponents, WevuGlobalDirectives, type WevuPlugin, type WevuTypedRouterRouteMap, WritableComputedOptions, WritableComputedRef, addMutationRecorder, batch, callHookList, callHookReturn, callUpdateHooks, computed, createApp, createStore, createWevuComponent, createWevuScopedSlotComponent, customRef, defineComponent, defineEmits, defineExpose, defineModel, defineOptions, defineProps, defineSlots, defineStore, effect, effectScope, endBatch, getCurrentInstance, getCurrentScope, getCurrentSetupContext, getDeepWatchStrategy, getReactiveVersion, inject, injectGlobal, isNoSetData, isRaw, isReactive, isRef, isShallowReactive, isShallowRef, markNoSetData, markRaw, mergeModels, mountRuntimeInstance, nextTick, normalizeClass, normalizeStyle, onActivated, onAddToFavorites, onAttached, onBeforeMount, onBeforeUnmount, onBeforeUpdate, onDeactivated, onDetached, onError, onErrorCaptured, onHide, onLaunch, onLoad, onMemoryWarning, onMounted, onMoved, onPageNotFound, onPageScroll, onPullDownRefresh, onReachBottom, onReady, onResize, onRouteDone, onSaveExitState, onScopeDispose, onServerPrefetch, onShareAppMessage, onShareTimeline, onShow, onTabItemTap, onThemeChange, onUnhandledRejection, onUnload, onUnmounted, onUpdated, prelinkReactiveTree, provide, provideGlobal, reactive, readonly, ref, registerApp, registerComponent, removeMutationRecorder, resetWevuDefaults, runSetupFunction, setCurrentInstance, setCurrentSetupContext, setDeepWatchStrategy, setRuntimeSetDataVisibility, setWevuDefaults, shallowReactive, shallowRef, startBatch, stop, storeToRefs, teardownRuntimeInstance, toRaw, toRef, toRefs, toValue, touchReactive, traverse, triggerRef, unref, useAttrs, useBindModel, useDisposables, useIntersectionObserver, useModel, useNativeInstance, useNativePageRouter, useNativeRouter, usePageScrollThrottle, useSlots, useTemplateRef, useUpdatePerformanceListener, watch, watchEffect, withDefaults };
+export { ActionContext, ActionSubscriber, type AllowedComponentProps, type AppConfig, type ComponentCustomProps, ComponentDefinition, type ComponentOptionsMixin, type ComponentPropsOptions, type ComponentPublicInstance, type ComponentTypeEmits, type ComputedDefinitions, ComputedGetter, ComputedRef, ComputedSetter, type CreateAppOptions, CustomRefFactory, CustomRefOptions, CustomRefSource, type DataOption, type DefineAppOptions, type DefineComponent, type DefineComponentOptions, DefineComponentTypePropsOptions, DefineComponentWithTypeProps, DefineModelModifiers, DefineModelTransformOptions, DefineStoreOptions, DisposableBag, DisposableLike, DisposableMethodName, DisposableObject, EffectScope, type EmitFn, type EmitsOptions, type ExtractComputed, type ExtractDefaultPropTypes, type ExtractMethods, type ExtractPropTypes, type ExtractPublicPropTypes, GlobalComponents, GlobalDirectives, type InferNativePropType, type InferNativeProps, type InferPropType, type InferProps, type InternalRuntimeState, type InternalRuntimeStateFields, type MapSources, MaybeRef, MaybeRefOrGetter, type MaybeUndefined, type MethodDefinitions, type MiniProgramAdapter, type MiniProgramAppOptions, type MiniProgramBehaviorIdentifier, type MiniProgramComponentBehaviorOptions, type MiniProgramComponentOptions, type MiniProgramComponentRawOptions, type MiniProgramInstance, type MiniProgramPageLifetimes, type ModelBinding, type ModelBindingOptions, type ModelBindingPayload, ModelModifiers, ModelRef, type MultiWatchSources, type MutationKind, type MutationOp, type MutationRecord, MutationType, type NativeComponent, type NativePropType, type NativePropsOptions, type NativeTypeHint, type NativeTypedProperty, type ObjectDirective, type OnCleanup, type PageFeatures, PageLayoutMeta, PageLayoutState, PageMeta, type PrelinkReactiveTreeOptions, type PropConstructor, type PropOptions, type PropType, type PublicProps, Ref, type RuntimeApp, type RuntimeInstance, type SetDataDebugInfo, type SetDataSnapshotOptions, type SetupContext, type SetupContextNativeInstance, type SetupContextRouter, SetupContextWithTypeProps, type SetupFunction, SetupFunctionWithTypeProps, ShallowRef, type ShallowUnwrapRef, StoreManager, StoreSubscribeOptions, StoreToRefsResult, SubscriptionCallback, TemplateRef, TemplateRefValue, TemplateRefs, ToRefs, type TriggerEventOptions, UpdatePerformanceListener, UpdatePerformanceListenerResult, UseIntersectionObserverOptions, UseIntersectionObserverResult, UseModelOptions, UsePageScrollThrottleOptions, UsePageScrollThrottleStopHandle, UseUpdatePerformanceListenerStopHandle, type VNode, type VNodeProps, type WatchCallback, type WatchEffect, type WatchEffectOptions, type WatchMultiSources, type WatchOptions, type WatchScheduler, type WatchSource, type WatchSourceValue, type WatchSources, type WatchStopHandle, WevuComponentConstructor, WevuDefaults, WevuGlobalComponents, WevuGlobalDirectives, WevuPageLayoutMap, type WevuPlugin, type WevuTypedRouterRouteMap, WritableComputedOptions, WritableComputedRef, addMutationRecorder, batch, callHookList, callHookReturn, callUpdateHooks, computed, createApp, createStore, createWevuComponent, createWevuScopedSlotComponent, customRef, defineComponent, defineEmits, defineExpose, defineModel, defineOptions, definePageMeta, defineProps, defineSlots, defineStore, effect, effectScope, endBatch, getCurrentInstance, getCurrentScope, getCurrentSetupContext, getDeepWatchStrategy, getReactiveVersion, hasInjectionContext, inject, injectGlobal, isNoSetData, isRaw, isReactive, isRef, isShallowReactive, isShallowRef, markNoSetData, markRaw, mergeModels, mountRuntimeInstance, nextTick, normalizeClass, normalizeStyle, onActivated, onAddToFavorites, onAttached, onBeforeMount, onBeforeUnmount, onBeforeUpdate, onDeactivated, onDetached, onError, onErrorCaptured, onHide, onLaunch, onLoad, onMemoryWarning, onMounted, onMoved, onPageNotFound, onPageScroll, onPullDownRefresh, onReachBottom, onReady, onResize, onRouteDone, onSaveExitState, onScopeDispose, onServerPrefetch, onShareAppMessage, onShareTimeline, onShow, onTabItemTap, onThemeChange, onUnhandledRejection, onUnload, onUnmounted, onUpdated, prelinkReactiveTree, provide, provideGlobal, reactive, readonly, ref, registerApp, registerComponent, removeMutationRecorder, resetWevuDefaults, resolveRuntimePageLayoutName, runSetupFunction, setCurrentInstance, setCurrentSetupContext, setDeepWatchStrategy, setPageLayout, setRuntimeSetDataVisibility, setWevuDefaults, shallowReactive, shallowReadonly, shallowRef, startBatch, stop, storeToRefs, syncRuntimePageLayoutState, syncRuntimePageLayoutStateFromRuntime, teardownRuntimeInstance, toRaw, toRef, toRefs, toValue, touchReactive, traverse, triggerRef, unref, useAttrs, useBindModel, useDisposables, useIntersectionObserver, useModel, useNativeInstance, useNativePageRouter, useNativeRouter, usePageLayout, usePageScrollThrottle, useSlots, useTemplateRef, useUpdatePerformanceListener, watch, watchEffect, withDefaults };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { A as track, C as effect, D as onScopeDispose, E as getCurrentScope, M as triggerEffects, N as nextTick, O as startBatch, P as queueJob, S as batch, T as endBatch, _ as ReactiveFlags, a as toValue, b as addMutationRecorder, c as isRaw, d as reactive, f as isShallowReactive, g as touchReactive, h as prelinkReactiveTree, i as ref, j as trigger, k as stop, l as isReactive, m as clearPatchIndices, n as isRef, o as unref, p as shallowReactive, r as markAsRef, s as getReactiveVersion, t as customRef, u as markRaw, v as isObject$1, w as effectScope, x as removeMutationRecorder, y as toRaw } from "./ref-BjmD-qct.mjs";
 import { i as computed, n as defineStore, r as createStore, t as storeToRefs } from "./store-Ct-o7qtH.mjs";
-import { A as onUnload, B as getScopedSlotHostGlobalObject, C as onSaveExitState, D as onTabItemTap, E as onShow, F as getCurrentSetupContext, I as pushHook, L as setCurrentInstance, M as callHookList, N as callHookReturn, O as onThemeChange, P as getCurrentInstance, R as setCurrentSetupContext, S as onRouteDone, T as onShareTimeline, V as readonly, _ as onPageScroll, a as provide, b as onReady, c as onAttached, d as onHide, f as onLaunch, g as onPageNotFound, h as onMoved, i as injectGlobal, j as assertInSetup, k as onUnhandledRejection, l as onDetached, m as onMemoryWarning, n as useNativeRouter, o as provideGlobal, p as onLoad, r as inject, s as onAddToFavorites, t as useNativePageRouter, u as onError, v as onPullDownRefresh, w as onShareAppMessage, x as onResize, y as onReachBottom, z as getMiniProgramGlobalObject } from "./router-BoEmd9rt.mjs";
+import { A as onUnhandledRejection, B as getMiniProgramGlobalObject, C as onRouteDone, D as onShow, E as onShareTimeline, F as getCurrentInstance, H as readonly, I as getCurrentSetupContext, L as pushHook, M as assertInSetup, N as callHookList, O as onTabItemTap, P as callHookReturn, R as setCurrentInstance, S as onResize, T as onShareAppMessage, U as shallowReadonly, V as getScopedSlotHostGlobalObject, _ as onPageNotFound, a as injectGlobal, b as onReachBottom, c as onAddToFavorites, d as onError, f as onHide, g as onMoved, h as onMemoryWarning, i as inject, j as onUnload, k as onThemeChange, l as onAttached, m as onLoad, n as useNativeRouter, o as provide, p as onLaunch, r as hasInjectionContext, s as provideGlobal, t as useNativePageRouter, u as onDetached, v as onPageScroll, w as onSaveExitState, x as onReady, y as onPullDownRefresh, z as setCurrentSetupContext } from "./router-PqZEeqhd.mjs";
 //#region src/reactivity/shallowRef.ts
 /**
 * 创建一个“浅层” ref：它只在 .value 被整体替换时触发依赖，不会对内部对象做深层响应式处理。
@@ -1459,10 +1459,14 @@ function createWatchStopHandle(cleanup, baseHandle) {
 	};
 	return stopHandle;
 }
+function resolveDataOption(data) {
+	if (typeof data === "function") return data();
+	return data !== null && data !== void 0 ? data : {};
+}
 function createRuntimeMount(options) {
 	const { data, resolvedComputed, resolvedMethods, appConfig, setDataOptions } = options;
 	return (adapter) => {
-		const rawState = (data !== null && data !== void 0 ? data : (() => ({})))();
+		const rawState = resolveDataOption(data);
 		if (rawState && typeof rawState === "object" && !Object.hasOwn(rawState, "__wevuProps")) try {
 			Object.defineProperty(rawState, "__wevuProps", {
 				value: shallowReactive(Object.create(null)),
@@ -2558,10 +2562,12 @@ function runRuntimeSetupPhase(options) {
 		attrs,
 		slots: createSetupSlotsFallback()
 	});
+	const instanceScope = effectScope(true);
+	target.__wevuEffectScope = instanceScope;
 	setCurrentInstance(target);
 	setCurrentSetupContext(context);
 	try {
-		const result = runSetupFunction(setup, props, context);
+		const result = instanceScope.run(() => runSetupFunction(setup, props, context));
 		let methodsChanged = false;
 		if (result && typeof result === "object") {
 			const runtimeRawState = isReactive(runtime.state) ? toRaw(runtime.state) : runtime.state;
@@ -2604,6 +2610,10 @@ function runRuntimeSetupPhase(options) {
 			var _wevu_touchSetupMetho;
 			(_wevu_touchSetupMetho = runtime.__wevu_touchSetupMethodsVersion) === null || _wevu_touchSetupMetho === void 0 || _wevu_touchSetupMetho.call(runtime);
 		}
+	} catch (error) {
+		instanceScope.stop();
+		target.__wevuEffectScope = void 0;
+		throw error;
 	} finally {
 		setCurrentSetupContext(void 0);
 		setCurrentInstance(void 0);
@@ -2999,6 +3009,7 @@ function setRuntimeSetDataVisibility(target, visible) {
 * @internal
 */
 function teardownRuntimeInstance(target) {
+	var _target$__wevuEffectS;
 	const runtime = target.__wevu;
 	const ownerId = target.__wvOwnerId;
 	if (ownerId) removeOwner(ownerId);
@@ -3010,6 +3021,8 @@ function teardownRuntimeInstance(target) {
 		stop();
 	} catch (_unused2) {}
 	target.__wevuWatchStops = void 0;
+	(_target$__wevuEffectS = target.__wevuEffectScope) === null || _target$__wevuEffectS === void 0 || _target$__wevuEffectS.stop();
+	target.__wevuEffectScope = void 0;
 	if (runtime) runtime.unmount();
 	delete target.__wevu;
 	if ("$wevu" in target) delete target.$wevu;
@@ -3729,10 +3742,84 @@ function createPropsSync(options) {
 	};
 }
 //#endregion
+//#region src/runtime/pageLayout.ts
+const PAGE_LAYOUT_SETTER_KEY = "__wevuSetPageLayout";
+const NO_LAYOUT_RUNTIME_KEY = "__wv_no_layout";
+function resolveCurrentPageInstance() {
+	const getCurrentPagesFn = globalThis.getCurrentPages;
+	if (typeof getCurrentPagesFn !== "function") return;
+	return getCurrentPagesFn().at(-1);
+}
+function normalizeRuntimePageLayoutName(layout) {
+	return layout === NO_LAYOUT_RUNTIME_KEY ? false : layout;
+}
+/**
+* 获取当前页面 layout 状态。
+*/
+function usePageLayout() {
+	var _currentInstance$__we, _runtimeState$__wv_pa;
+	if (!getCurrentSetupContext()) throw new Error("usePageLayout() 必须在 setup() 的同步阶段调用");
+	const currentInstance = getCurrentInstance();
+	const runtimeState = currentInstance === null || currentInstance === void 0 || (_currentInstance$__we = currentInstance.__wevu) === null || _currentInstance$__we === void 0 ? void 0 : _currentInstance$__we.state;
+	const pageLayoutState = reactive({
+		name: normalizeRuntimePageLayoutName(runtimeState === null || runtimeState === void 0 ? void 0 : runtimeState.__wv_page_layout_name),
+		props: { ...(_runtimeState$__wv_pa = runtimeState === null || runtimeState === void 0 ? void 0 : runtimeState.__wv_page_layout_props) !== null && _runtimeState$__wv_pa !== void 0 ? _runtimeState$__wv_pa : {} }
+	});
+	if (currentInstance) currentInstance.__wevuPageLayoutState = pageLayoutState;
+	return readonly(pageLayoutState);
+}
+function syncRuntimePageLayoutState(target, layout, props) {
+	const state = target.__wevuPageLayoutState;
+	if (!state) return;
+	state.name = layout;
+	state.props = { ...props };
+}
+function syncRuntimePageLayoutStateFromRuntime(target) {
+	var _target$__wevu, _runtimeState$__wv_pa2;
+	const state = target.__wevuPageLayoutState;
+	const runtimeState = (_target$__wevu = target.__wevu) === null || _target$__wevu === void 0 ? void 0 : _target$__wevu.state;
+	if (!state || !runtimeState) return;
+	state.name = normalizeRuntimePageLayoutName(runtimeState.__wv_page_layout_name);
+	state.props = { ...(_runtimeState$__wv_pa2 = runtimeState.__wv_page_layout_props) !== null && _runtimeState$__wv_pa2 !== void 0 ? _runtimeState$__wv_pa2 : {} };
+}
+/**
+* 显式切换当前页面使用的 layout。
+*/
+function setPageLayout(layout, props) {
+	const currentInstance = getCurrentInstance();
+	const directSetter = currentInstance === null || currentInstance === void 0 ? void 0 : currentInstance[PAGE_LAYOUT_SETTER_KEY];
+	if (typeof directSetter === "function") {
+		directSetter(layout, props);
+		return;
+	}
+	const currentPage = resolveCurrentPageInstance();
+	const pageSetter = currentPage === null || currentPage === void 0 ? void 0 : currentPage[PAGE_LAYOUT_SETTER_KEY];
+	if (typeof pageSetter === "function") {
+		pageSetter(layout, props);
+		return;
+	}
+	throw new Error("setPageLayout() 未找到当前页面实例。请在页面 setup()、事件回调或当前页面上下文中调用。");
+}
+function resolveRuntimePageLayoutName(layout) {
+	return layout === false ? NO_LAYOUT_RUNTIME_KEY : layout;
+}
+//#endregion
 //#region src/runtime/register/component/registerDefinition.ts
 function registerComponentDefinition(options) {
 	const { runtimeApp, watch, setup, restOptions, pageLifecycleHooks, finalObservers, userLifetimes, userPageLifetimes, finalMethods, finalOptions, applyExtraInstanceFields, templateRefs, attachWevuPropKeys, setupLifecycle, syncWevuPropsFromInstance, isPage, legacyCreated, getRuntimeOwnerLabel } = options;
 	const pageShareMethodBridges = {};
+	const attachPageLayoutSetter = (instance) => {
+		if (!isPage) return;
+		instance.__wevuSetPageLayout = (layout, props) => {
+			var _instance$__wevu;
+			const runtimeState = (_instance$__wevu = instance.__wevu) === null || _instance$__wevu === void 0 ? void 0 : _instance$__wevu.state;
+			if (!runtimeState || typeof runtimeState !== "object") return;
+			runtimeState.__wv_page_layout_name = resolveRuntimePageLayoutName(layout);
+			const nextProps = layout === false ? {} : props !== null && props !== void 0 ? props : {};
+			runtimeState.__wv_page_layout_props = nextProps;
+			syncRuntimePageLayoutState(instance, layout, nextProps);
+		};
+	};
 	if (isPage) for (const hookName of [
 		"onShareAppMessage",
 		"onShareTimeline",
@@ -3768,6 +3855,7 @@ function registerComponentDefinition(options) {
 						throw new Error(`[wevu] mount runtime failed in created (${label}): ${error instanceof Error ? error.message : String(error)}`);
 					}
 					syncWevuPropsFromInstance(this);
+					attachPageLayoutSetter(this);
 				}
 				if (typeof legacyCreated === "function") legacyCreated.apply(this, args);
 				if (typeof userLifetimes.created === "function") userLifetimes.created.apply(this, args);
@@ -3792,6 +3880,7 @@ function registerComponentDefinition(options) {
 					throw new Error(`[wevu] mount runtime failed in attached (${label}): ${error instanceof Error ? error.message : String(error)}`);
 				}
 				syncWevuPropsFromInstance(this);
+				attachPageLayoutSetter(this);
 				if (setupLifecycle === "created") enableDeferredSetData(this);
 				callHookList(this, "onAttached", args);
 				if (typeof userLifetimes.attached === "function") userLifetimes.attached.apply(this, args);
@@ -4901,4 +4990,4 @@ function useTemplateRef(name) {
 	return target;
 }
 //#endregion
-export { addMutationRecorder, batch, callHookList, callHookReturn, callUpdateHooks, computed, createApp, createStore, createWevuComponent, createWevuScopedSlotComponent, customRef, defineComponent, defineStore, effect, effectScope, endBatch, getCurrentInstance, getCurrentScope, getCurrentSetupContext, getDeepWatchStrategy, getReactiveVersion, inject, injectGlobal, isNoSetData, isRaw, isReactive, isRef, isShallowReactive, isShallowRef, markNoSetData, markRaw, mergeModels, mountRuntimeInstance, nextTick, normalizeClass, normalizeStyle, onActivated, onAddToFavorites, onAttached, onBeforeMount, onBeforeUnmount, onBeforeUpdate, onDeactivated, onDetached, onError, onErrorCaptured, onHide, onLaunch, onLoad, onMemoryWarning, onMounted, onMoved, onPageNotFound, onPageScroll, onPullDownRefresh, onReachBottom, onReady, onResize, onRouteDone, onSaveExitState, onScopeDispose, onServerPrefetch, onShareAppMessage, onShareTimeline, onShow, onTabItemTap, onThemeChange, onUnhandledRejection, onUnload, onUnmounted, onUpdated, prelinkReactiveTree, provide, provideGlobal, reactive, readonly, ref, registerApp, registerComponent, removeMutationRecorder, resetWevuDefaults, runSetupFunction, setCurrentInstance, setCurrentSetupContext, setDeepWatchStrategy, setRuntimeSetDataVisibility, setWevuDefaults, shallowReactive, shallowRef, startBatch, stop, storeToRefs, teardownRuntimeInstance, toRaw, toRef, toRefs, toValue, touchReactive, traverse, triggerRef, unref, useAttrs, useBindModel, useDisposables, useIntersectionObserver, useModel, useNativeInstance, useNativePageRouter, useNativeRouter, usePageScrollThrottle, useSlots, useTemplateRef, useUpdatePerformanceListener, watch, watchEffect };
+export { addMutationRecorder, batch, callHookList, callHookReturn, callUpdateHooks, computed, createApp, createStore, createWevuComponent, createWevuScopedSlotComponent, customRef, defineComponent, defineStore, effect, effectScope, endBatch, getCurrentInstance, getCurrentScope, getCurrentSetupContext, getDeepWatchStrategy, getReactiveVersion, hasInjectionContext, inject, injectGlobal, isNoSetData, isRaw, isReactive, isRef, isShallowReactive, isShallowRef, markNoSetData, markRaw, mergeModels, mountRuntimeInstance, nextTick, normalizeClass, normalizeStyle, onActivated, onAddToFavorites, onAttached, onBeforeMount, onBeforeUnmount, onBeforeUpdate, onDeactivated, onDetached, onError, onErrorCaptured, onHide, onLaunch, onLoad, onMemoryWarning, onMounted, onMoved, onPageNotFound, onPageScroll, onPullDownRefresh, onReachBottom, onReady, onResize, onRouteDone, onSaveExitState, onScopeDispose, onServerPrefetch, onShareAppMessage, onShareTimeline, onShow, onTabItemTap, onThemeChange, onUnhandledRejection, onUnload, onUnmounted, onUpdated, prelinkReactiveTree, provide, provideGlobal, reactive, readonly, ref, registerApp, registerComponent, removeMutationRecorder, resetWevuDefaults, resolveRuntimePageLayoutName, runSetupFunction, setCurrentInstance, setCurrentSetupContext, setDeepWatchStrategy, setPageLayout, setRuntimeSetDataVisibility, setWevuDefaults, shallowReactive, shallowReadonly, shallowRef, startBatch, stop, storeToRefs, syncRuntimePageLayoutState, syncRuntimePageLayoutStateFromRuntime, teardownRuntimeInstance, toRaw, toRef, toRefs, toValue, touchReactive, traverse, triggerRef, unref, useAttrs, useBindModel, useDisposables, useIntersectionObserver, useModel, useNativeInstance, useNativePageRouter, useNativeRouter, usePageLayout, usePageScrollThrottle, useSlots, useTemplateRef, useUpdatePerformanceListener, watch, watchEffect };

package/dist/{router-BoEmd9rt.mjs → router-PqZEeqhd.mjs}

@@ -1,6 +1,6 @@
 import { n as isRef, r as markAsRef, v as isObject } from "./ref-BjmD-qct.mjs";
 //#region src/reactivity/readonly.ts
-function readonly(target) {
+function createReadonlyWrapper(target) {
 	if (isRef(target)) {
 		const source = target;
 		return markAsRef({
@@ -28,6 +28,12 @@ function readonly(target) {
 		}
 	});
 }
+function readonly(target) {
+	return createReadonlyWrapper(target);
+}
+function shallowReadonly(target) {
+	return createReadonlyWrapper(target);
+}
 //#endregion
 //#region src/runtime/platform.ts
 function getGlobalRuntime() {
@@ -266,6 +272,15 @@ function onAddToFavorites(handler) {
 const PROVIDE_SCOPE_KEY = Symbol("wevu.provideScope");
 const __wevuGlobalProvideStore = /* @__PURE__ */ new Map();
 /**
+* 判断当前是否存在可用的注入上下文。
+*
+* wevu 目前的依赖注入上下文来自同步 `setup()` 阶段的当前实例；
+* 若未来补充 app 级 provider，这里可继续扩展判断来源。
+*/
+function hasInjectionContext() {
+	return Boolean(getCurrentInstance());
+}
+/**
 * 在组件上下文中向后代注入值（与 Vue 3 行为兼容），若没有当前实例则回落到全局存储。
 *
 * @param key 注入键，可为字符串、Symbol 或对象
@@ -407,4 +422,4 @@ function useNativePageRouter() {
 	return useRuntimeRouterByAccessor("pageRouter", "router", "useNativePageRouter");
 }
 //#endregion
-export { onUnload as A, getScopedSlotHostGlobalObject as B, onSaveExitState as C, onTabItemTap as D, onShow as E, getCurrentSetupContext as F, pushHook as I, setCurrentInstance as L, callHookList as M, callHookReturn as N, onThemeChange as O, getCurrentInstance as P, setCurrentSetupContext as R, onRouteDone as S, onShareTimeline as T, readonly as V, onPageScroll as _, provide as a, onReady as b, onAttached as c, onHide as d, onLaunch as f, onPageNotFound as g, onMoved as h, injectGlobal as i, assertInSetup as j, onUnhandledRejection as k, onDetached as l, onMemoryWarning as m, useNativeRouter as n, provideGlobal as o, onLoad as p, inject as r, onAddToFavorites as s, useNativePageRouter as t, onError as u, onPullDownRefresh as v, onShareAppMessage as w, onResize as x, onReachBottom as y, getMiniProgramGlobalObject as z };
+export { onUnhandledRejection as A, getMiniProgramGlobalObject as B, onRouteDone as C, onShow as D, onShareTimeline as E, getCurrentInstance as F, readonly as H, getCurrentSetupContext as I, pushHook as L, assertInSetup as M, callHookList as N, onTabItemTap as O, callHookReturn as P, setCurrentInstance as R, onResize as S, onShareAppMessage as T, shallowReadonly as U, getScopedSlotHostGlobalObject as V, onPageNotFound as _, injectGlobal as a, onReachBottom as b, onAddToFavorites as c, onError as d, onHide as f, onMoved as g, onMemoryWarning as h, inject as i, onUnload as j, onThemeChange as k, onAttached as l, onLoad as m, useNativeRouter as n, provide as o, onLaunch as p, hasInjectionContext as r, provideGlobal as s, useNativePageRouter as t, onDetached as u, onPageScroll as v, onSaveExitState as w, onReady as x, onPullDownRefresh as y, setCurrentSetupContext as z };

package/dist/router.mjs

@@ -1,5 +1,5 @@
 import { d as reactive } from "./ref-BjmD-qct.mjs";
-import { E as onShow, F as getCurrentSetupContext, S as onRouteDone, V as readonly, i as injectGlobal, n as useNativeRouter$1, o as provideGlobal, p as onLoad, t as useNativePageRouter$1 } from "./router-BoEmd9rt.mjs";
+import { C as onRouteDone, D as onShow, H as readonly, I as getCurrentSetupContext, a as injectGlobal, m as onLoad, n as useNativeRouter$1, s as provideGlobal, t as useNativePageRouter$1 } from "./router-PqZEeqhd.mjs";
 //#region src/routerInternal/path.ts
 function normalizePathSegments(path) {
 	const segments = [];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wevu",
   "type": "module",
-  "version": "6.10.2",
+  "version": "6.11.1",
   "description": "Vue 3 风格的小程序运行时，包含响应式、diff+setData 与轻量状态管理",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -96,7 +96,7 @@
   "dependencies": {
     "vue": "^3.5.30",
     "@wevu/api": "0.2.2",
-    "@wevu/compiler": "6.10.2"
+    "@wevu/compiler": "6.11.1"
   },
   "scripts": {
     "dev": "tsdown -w",