or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

components.mdcontext.mddevice.mdframework.mdindex.mdlocation.mdmedia.mdnavigation.mdnetwork.mdstorage.mdui-controls.md
tile.json

ui-controls.mddocs/

UI Controls

User interface control APIs including modals, toasts, action sheets, navigation bars, tab bars, page scrolling functionality, and other interactive UI elements for enhanced user experience.

Capabilities

Modal Dialogs

Display modal dialogs for user confirmations, alerts, and input collection.

/**
 * Show modal dialog
 * @param options - Modal configuration
 * @returns Promise resolving to user interaction result
 */
function showModal(options: ShowModalOptions): Promise<ShowModalResult>;

interface ShowModalOptions {
  /** Modal title */
  title?: string;
  /** Modal content message */
  content?: string;
  /** Whether to show cancel button */
  showCancel?: boolean;
  /** Cancel button text */
  cancelText?: string;
  /** Cancel button color */
  cancelColor?: string;
  /** Confirm button text */
  confirmText?: string;
  /** Confirm button color */
  confirmColor?: string;
  /** Whether content is editable */
  editable?: boolean;
  /** Placeholder for editable content */
  placeholderText?: string;
  /** Success callback */
  success?: (result: ShowModalResult) => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: (result: any) => void;
}

interface ShowModalResult {
  /** Whether user confirmed */
  confirm: boolean;
  /** Whether user cancelled */
  cancel: boolean;
  /** Input content if editable */
  content?: string;
}

Usage Examples:

import { showModal } from "@dcloudio/uni-h5";

// Simple confirmation dialog
const result = await showModal({
  title: 'Confirm Action',
  content: 'Are you sure you want to delete this item?',
  showCancel: true
});

if (result.confirm) {
  // User confirmed, proceed with deletion
  deleteItem();
}

// Editable modal for user input
showModal({
  title: 'Enter Name',
  content: 'Please enter your name:',
  editable: true,
  placeholderText: 'Your name here',
  success(result) {
    if (result.confirm && result.content) {
      console.log('User entered:', result.content);
      saveUserName(result.content);
    }
  }
});

// Custom styled modal
showModal({
  title: 'Warning',
  content: 'This action cannot be undone.',
  confirmText: 'Delete',
  confirmColor: '#ff4444',
  cancelText: 'Keep',
  cancelColor: '#007aff'
});

Toast Messages

Display temporary notification messages to users.

/**
 * Show toast message
 * @param options - Toast configuration
 */
function showToast(options: ShowToastOptions): void;

/**
 * Hide current toast message
 */
function hideToast(): void;

interface ShowToastOptions {
  /** Toast message text */
  title: string;
  /** Toast icon */
  icon?: 'success' | 'error' | 'loading' | 'none';
  /** Custom image path for icon */
  image?: string;
  /** Display duration in milliseconds */
  duration?: number;
  /** Whether to show mask to prevent touch */
  mask?: boolean;
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

Usage Examples:

import { showToast, hideToast } from "@dcloudio/uni-h5";

// Success toast
showToast({
  title: 'Operation successful!',
  icon: 'success',
  duration: 2000
});

// Error toast
showToast({
  title: 'Network error',
  icon: 'error'
});

// Loading toast with mask
showToast({
  title: 'Loading...',
  icon: 'loading',
  mask: true
});

// Custom icon toast
showToast({
  title: 'Custom message',
  image: '/static/custom-icon.png',
  duration: 3000
});

// Hide toast programmatically
setTimeout(() => {
  hideToast();
}, 1000);

Action Sheets

Display action sheets for user selection from multiple options.

/**
 * Show action sheet
 * @param options - Action sheet configuration
 * @returns Promise resolving to user selection
 */
function showActionSheet(options: ShowActionSheetOptions): Promise<ShowActionSheetResult>;

interface ShowActionSheetOptions {
  /** Array of action item text */
  itemList: string[];
  /** Item text color */
  itemColor?: string;
  /** Success callback */
  success?: (result: ShowActionSheetResult) => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: (result: any) => void;
}

interface ShowActionSheetResult {
  /** Selected item index */
  tapIndex: number;
}

Usage Examples:

import { showActionSheet } from "@dcloudio/uni-h5";

// Basic action sheet
const result = await showActionSheet({
  itemList: ['Camera', 'Photo Library', 'Cancel']
});

switch (result.tapIndex) {
  case 0:
    openCamera();
    break;
  case 1:
    openPhotoLibrary();
    break;
  case 2:
    // Cancel - do nothing
    break;
}

// Action sheet with custom colors
showActionSheet({
  itemList: ['Edit', 'Share', 'Delete'],
  itemColor: '#007aff',
  success(result) {
    const actions = ['edit', 'share', 'delete'];
    const selectedAction = actions[result.tapIndex];
    handleAction(selectedAction);
  }
});

Navigation Bar

Control navigation bar appearance and behavior.

/**
 * Set navigation bar title
 * @param options - Title configuration
 */
function setNavigationBarTitle(options: SetNavigationBarTitleOptions): void;

/**
 * Set navigation bar color
 * @param options - Color configuration
 */
function setNavigationBarColor(options: SetNavigationBarColorOptions): void;

/**
 * Show navigation bar loading indicator
 */
function showNavigationBarLoading(): void;

/**
 * Hide navigation bar loading indicator
 */
function hideNavigationBarLoading(): void;

interface SetNavigationBarTitleOptions {
  /** Navigation bar title */
  title: string;
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface SetNavigationBarColorOptions {
  /** Foreground color (text/icons) */
  frontColor: '#000000' | '#ffffff';
  /** Background color */
  backgroundColor: string;
  /** Animation configuration */
  animation?: {
    /** Animation duration in ms */
    duration?: number;
    /** Animation timing function */
    timingFunc?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
  };
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

Usage Examples:

import { 
  setNavigationBarTitle, 
  setNavigationBarColor, 
  showNavigationBarLoading, 
  hideNavigationBarLoading 
} from "@dcloudio/uni-h5";

// Set page title
setNavigationBarTitle({
  title: 'Profile Settings'
});

// Set navigation bar colors
setNavigationBarColor({
  frontColor: '#ffffff',
  backgroundColor: '#007aff',
  animation: {
    duration: 400,
    timingFunc: 'easeInOut'
  }
});

// Show loading in navigation bar
showNavigationBarLoading();

// Hide loading after operation
setTimeout(() => {
  hideNavigationBarLoading();
}, 2000);

// Dynamic title based on data
function updatePageTitle(user) {
  setNavigationBarTitle({
    title: `${user.name}'s Profile`,
    success() {
      console.log('Title updated successfully');
    }
  });
}

Tab Bar

Control tab bar appearance, visibility, and badges.

/**
 * Set tab bar item properties
 * @param options - Tab bar item configuration
 */
function setTabBarItem(options: SetTabBarItemOptions): void;

/**
 * Set tab bar style
 * @param options - Tab bar style configuration
 */
function setTabBarStyle(options: SetTabBarStyleOptions): void;

/**
 * Hide tab bar
 * @param options - Hide configuration
 */
function hideTabBar(options?: HideTabBarOptions): void;

/**
 * Show tab bar  
 * @param options - Show configuration
 */
function showTabBar(options?: ShowTabBarOptions): void;

/**
 * Set tab bar badge
 * @param options - Badge configuration
 */
function setTabBarBadge(options: SetTabBarBadgeOptions): void;

/**
 * Remove tab bar badge
 * @param options - Remove badge configuration
 */
function removeTabBarBadge(options: RemoveTabBarBadgeOptions): void;

/**
 * Show tab bar red dot
 * @param options - Red dot configuration
 */
function showTabBarRedDot(options: ShowTabBarRedDotOptions): void;

/**
 * Hide tab bar red dot
 * @param options - Hide red dot configuration
 */
function hideTabBarRedDot(options: HideTabBarRedDotOptions): void;

interface SetTabBarItemOptions {
  /** Tab index */
  index: number;
  /** Tab text */
  text?: string;
  /** Tab icon path */
  iconPath?: string;
  /** Selected tab icon path */
  selectedIconPath?: string;
  /** Page path */
  pagePath?: string;
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface SetTabBarStyleOptions {
  /** Tab bar text color */
  color?: string;
  /** Selected tab text color */
  selectedColor?: string;
  /** Tab bar background color */
  backgroundColor?: string;
  /** Tab bar border color */
  borderStyle?: 'black' | 'white';
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface SetTabBarBadgeOptions {
  /** Tab index */
  index: number;
  /** Badge text */
  text: string;
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

Usage Examples:

import { 
  setTabBarItem, 
  setTabBarStyle, 
  setTabBarBadge, 
  removeTabBarBadge,
  showTabBarRedDot,
  hideTabBarRedDot 
} from "@dcloudio/uni-h5";

// Update tab bar item
setTabBarItem({
  index: 0,
  text: 'Home',
  iconPath: '/static/home.png',
  selectedIconPath: '/static/home-active.png'
});

// Set tab bar theme
setTabBarStyle({
  color: '#666666',
  selectedColor: '#007aff',
  backgroundColor: '#ffffff',
  borderStyle: 'black'
});

// Add badge to tab
setTabBarBadge({
  index: 1,
  text: '5'
});

// Show red dot notification
showTabBarRedDot({
  index: 2
});

// Remove badge
removeTabBarBadge({
  index: 1
});

// Handle notification updates
function updateNotificationBadge(count) {
  if (count > 0) {
    setTabBarBadge({
      index: 3,
      text: count > 99 ? '99+' : count.toString()
    });
  } else {
    removeTabBarBadge({
      index: 3
    });
  }
}

Page Scrolling

Control page scrolling behavior and position.

/**
 * Scroll page to specific position
 * @param options - Scroll configuration
 */
function pageScrollTo(options: PageScrollToOptions): void;

/**
 * Start pull down refresh
 */
function startPullDownRefresh(): void;

/**
 * Stop pull down refresh
 */
function stopPullDownRefresh(): void;

interface PageScrollToOptions {
  /** Scroll position in px */
  scrollTop?: number;
  /** Element selector to scroll to */
  selector?: string;
  /** Scroll duration in ms */
  duration?: number;
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

Usage Examples:

import { pageScrollTo, startPullDownRefresh, stopPullDownRefresh } from "@dcloudio/uni-h5";

// Scroll to top
pageScrollTo({
  scrollTop: 0,
  duration: 300
});

// Scroll to specific element
pageScrollTo({
  selector: '#section-2',
  duration: 500,
  success() {
    console.log('Scrolled to section 2');
  }
});

// Programmatically trigger refresh
startPullDownRefresh();

// Stop refresh after data loading
async function refreshData() {
  try {
    const data = await fetchLatestData();
    updatePageData(data);
  } finally {
    stopPullDownRefresh();
  }
}

// Smooth scroll to bottom
function scrollToBottom() {
  const systemInfo = uni.getSystemInfoSync();
  pageScrollTo({
    scrollTop: systemInfo.windowHeight * 2, // Approximate content height
    duration: 800
  });
}

Element Selection

Query and manipulate page elements.

/**
 * Get element by ID
 * @param options - Element query options
 */
function getElementById(options: GetElementByIdOptions): void;

interface GetElementByIdOptions {
  /** Element ID */
  id: string;
  /** Success callback */
  success?: (result: ElementResult) => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface ElementResult {
  /** Element information */
  element: ElementInfo;
}

interface ElementInfo {
  /** Element ID */
  id: string;
  /** Element bounds */
  left: number;
  top: number;
  width: number;
  height: number;
  /** Scroll position */
  scrollLeft: number;
  scrollTop: number;
}

Font Loading

Load custom fonts for enhanced typography.

/**
 * Load custom font
 * @param options - Font loading configuration
 */
function loadFontFace(options: LoadFontFaceOptions): void;

interface LoadFontFaceOptions {
  /** Font family name */
  family: string;
  /** Font source URL or path */
  source: string;
  /** Font descriptors */
  desc?: {
    /** Font style */
    style?: 'normal' | 'italic' | 'oblique';
    /** Font weight */
    weight?: 'normal' | 'bold' | number;
    /** Font variant */
    variant?: 'normal' | 'small-caps';
  };
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

Usage Examples:

import { loadFontFace } from "@dcloudio/uni-h5";

// Load custom font
loadFontFace({
  family: 'CustomFont',
  source: 'url("/static/fonts/custom.woff2")',
  desc: {
    weight: 'normal',
    style: 'normal'
  },
  success() {
    console.log('Font loaded successfully');
    // Apply font to elements
    document.body.style.fontFamily = 'CustomFont, sans-serif';
  },
  fail(error) {
    console.error('Failed to load font:', error);
  }
});

// Load multiple font weights
const weights = [300, 400, 600, 700];
weights.forEach(weight => {
  loadFontFace({
    family: 'Roboto',
    source: `url("/static/fonts/roboto-${weight}.woff2")`,
    desc: { weight }
  });
});

UI Control Types

// Common UI callback types
interface UISuccessCallback<T = void> {
  success?: (result: T) => void;
  fail?: (error: any) => void;
  complete?: () => void;
}

// Animation configuration
interface AnimationConfig {
  duration?: number;
  timingFunc?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
}

// Color values
type ColorValue = string; // Hex, RGB, RGBA, or named color

// UI state types
interface UIState {
  visible: boolean;
  loading: boolean;
  disabled: boolean;
}