Interface for interacting with individual pages/screens in the uni-app application, including element selection, page data manipulation, and page-level operations.
Core functionality for finding and selecting elements within the page DOM structure.
/**
* Select a single element using CSS selector
* @param selector - CSS selector string
* @returns Promise resolving to Element instance or null if not found
*/
$(selector: string): Promise<Element | null>;
/**
* Select multiple elements using CSS selector
* @param selector - CSS selector string
* @returns Promise resolving to array of Element instances
*/
$$(selector: string): Promise<Element[]>;Usage Examples:
// Select single element
const button = await page.$(".submit-button");
if (button) {
await button.tap();
}
// Select multiple elements
const listItems = await page.$$(".list-item");
console.log(`Found ${listItems.length} list items`);
// Chain selections for complex queries
const form = await page.$("form");
const inputs = await form.$$("input");Interface for accessing and modifying page-level data in uni-app's data binding system.
/**
* Get page data
* @param path - Optional path to specific data property (e.g., "user.name")
* @returns Promise resolving to page data object or specific property
*/
data(path?: string): Promise<any>;
/**
* Set page data
* @param data - Data object to merge with existing page data
* @returns Promise resolving when data is set
*/
setData(data: object): Promise<void>;
/**
* Call a method defined in the page instance
* @param method - Method name to call
* @param args - Arguments to pass to the method
* @returns Promise resolving to the method's return value
*/
callMethod(method: string, ...args: any[]): Promise<any>;Usage Examples:
// Get all page data
const allData = await page.data();
console.log("Page data:", allData);
// Get specific data property
const userName = await page.data("user.name");
console.log("User name:", userName);
// Set page data
await page.setData({
title: "Updated Title",
user: { name: "John", age: 30 }
});
// Call page method
const result = await page.callMethod("handleSubmit", formData);Methods for getting page dimensions, scroll position, and window properties.
/**
* Get page dimensions
* @returns Promise resolving to page size object
*/
size(): Promise<PageSize>;
/**
* Get current vertical scroll position
* @returns Promise resolving to scroll top value in pixels
*/
scrollTop(): Promise<number>;
/**
* Get window or document properties
* @param property - Property path (e.g., "document.title")
* @returns Promise resolving to property value
*/
windowProperty(property: string | string[]): Promise<any>;Usage Examples:
// Get page dimensions
const { width, height } = await page.size();
console.log(`Page size: ${width}x${height}`);
// Check scroll position
const scrollPos = await page.scrollTop();
if (scrollPos > 100) {
console.log("Page is scrolled");
}
// Get window properties
const title = await page.windowProperty("document.title");
const dimensions = await page.windowProperty([
"document.documentElement.scrollWidth",
"document.documentElement.scrollHeight"
]);Access to page metadata and routing information.
/**
* Page properties available as instance variables
*/
interface Page {
/** Unique page identifier */
readonly id: string;
/** Page route path */
readonly path: string;
/** URL query parameters object */
readonly query: object;
}Usage Examples:
// Access page properties
console.log(`Page ID: ${page.id}`);
console.log(`Current path: ${page.path}`);
console.log(`Query params:`, page.query);
// Check if on specific page
if (page.path === "pages/detail/detail") {
const productId = page.query.id;
console.log(`Viewing product: ${productId}`);
}Utilities for waiting for conditions, timeouts, and page state changes.
/**
* Wait for a condition to be met
* @param condition - Condition to wait for
* @returns Promise resolving when condition is met
*/
waitFor(condition: number | string | Function): Promise<void>;Usage Examples:
// Wait for specific time (milliseconds)
await page.waitFor(1000);
// Wait for element to appear
await page.waitFor(".loading-complete");
// Wait for custom condition
await page.waitFor(async () => {
const items = await page.$$(".list-item");
return items.length > 0;
});
// Wait for page data to change
await page.waitFor(async () => {
const loading = await page.data("loading");
return !loading;
});WeChat mini-programs have specific constraints for element selection and component interaction:
// ❌ Cross-component selection doesn't work
const element = await page.$(".child-component .inner-element");
// ✅ Select parent first, then child
const parentComponent = await page.$("custom-component");
const childElement = await parentComponent.$(".inner-element");Pages in subpackages may require longer wait times after navigation:
// Navigate to subpackage page
const subPage = await program.reLaunch("/subpackage/pages/detail/detail");
// Allow extra time for subpackage loading
await subPage.waitFor(7000);
// Refresh page reference for proper interaction
const currentPage = await program.currentPage();Different platforms may have varying behavior for certain operations:
// H5 platform: Full DOM access
const htmlContent = await page.windowProperty("document.documentElement.outerHTML");
// Mini-program platforms: Limited to uni-app APIs
const pageData = await page.data();Common page interaction errors and their handling:
// Element not found
const button = await page.$(".missing-button");
if (!button) {
console.log("Button not found, skipping interaction");
return;
}
// Wait for element with timeout
try {
await page.waitFor(".dynamic-content");
} catch (error) {
console.log("Content didn't load within timeout");
}
// Data access errors
try {
const data = await page.data("nested.property.path");
} catch (error) {
console.log("Property path doesn't exist");
}interface PageSize {
width: number;
height: number;
}
interface PageQuery {
[key: string]: string | undefined;
}