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

media.mddocs/

Media Handling

Media selection and processing APIs for images, videos, and files with support for camera capture, gallery selection, media information retrieval, and preview functionality.

Capabilities

Image Selection

Choose images from camera or gallery with configurable options for source, quality, and count.

/**
 * Choose images from camera or gallery
 * @param options - Image selection options
 * @returns Promise resolving to selected images
 */
function chooseImage(options?: ChooseImageOptions): Promise<ChooseImageResult>;

interface ChooseImageOptions {
  /** Maximum number of images to select */
  count?: number;
  /** Image size options */
  sizeType?: ('original' | 'compressed')[];
  /** Image source options */
  sourceType?: ('album' | 'camera')[];
  /** File extensions to filter */
  extension?: string[];
  /** Success callback */
  success?: (result: ChooseImageResult) => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface ChooseImageResult {
  /** Selected image file paths */
  tempFilePaths: string[];
  /** Selected image files */
  tempFiles: ChooseImageFile[];
}

interface ChooseImageFile {
  /** File path */
  path: string;
  /** File size in bytes */
  size: number;
  /** File name */
  name: string;
  /** File type */
  type: string;
}

Usage Examples:

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

// Choose single image from any source
const result = await chooseImage({
  count: 1,
  sizeType: ['compressed'],
  sourceType: ['album', 'camera']
});

console.log('Selected images:', result.tempFilePaths);

// Choose multiple images from album only
chooseImage({
  count: 9,
  sourceType: ['album'],
  success(result) {
    result.tempFiles.forEach((file, index) => {
      console.log(`Image ${index + 1}: ${file.name} (${file.size} bytes)`);
    });
  }
});

// Choose with specific file extensions
chooseImage({
  count: 5,
  extension: ['jpg', 'png', 'gif'],
  success(result) {
    // Process selected images
    uploadImages(result.tempFilePaths);
  }
});

Image Information

Retrieve detailed information about image files including dimensions, format, and metadata.

/**
 * Get image information
 * @param options - Image info options
 * @returns Promise resolving to image information
 */
function getImageInfo(options: GetImageInfoOptions): Promise<GetImageInfoResult>;

interface GetImageInfoOptions {
  /** Image file path */
  src: string;
  /** Success callback */
  success?: (result: GetImageInfoResult) => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface GetImageInfoResult {
  /** Image width in pixels */
  width: number;
  /** Image height in pixels */
  height: number;
  /** Image file path */
  path: string;
  /** Image orientation */
  orientation?: 'up' | 'down' | 'left' | 'right';
  /** Image type */
  type?: string;
}

Usage Examples:

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

// Get image dimensions
const imageInfo = await getImageInfo({
  src: '/tmp/selected-image.jpg'
});

console.log(`Image size: ${imageInfo.width}x${imageInfo.height}`);

// Check image orientation for proper display
getImageInfo({
  src: imagePath,
  success(info) {
    if (info.orientation === 'left' || info.orientation === 'right') {
      // Handle rotated images
      rotateImageDisplay(info.orientation);
    }
  }
});

Video Selection

Choose videos from camera or gallery with duration and quality controls.

/**
 * Choose video from camera or gallery
 * @param options - Video selection options
 * @returns Promise resolving to selected video
 */
function chooseVideo(options?: ChooseVideoOptions): Promise<ChooseVideoResult>;

interface ChooseVideoOptions {
  /** Video source options */
  sourceType?: ('album' | 'camera')[];
  /** Whether to compress video */
  compressed?: boolean;
  /** Maximum recording duration in seconds */
  maxDuration?: number;
  /** Camera to use */
  camera?: 'back' | 'front';
  /** Success callback */
  success?: (result: ChooseVideoResult) => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface ChooseVideoResult {
  /** Video file path */
  tempFilePath: string;
  /** Video duration in seconds */
  duration: number;
  /** Video file size in bytes */
  size: number;
  /** Video width in pixels */
  width: number;
  /** Video height in pixels */
  height: number;
  /** Video thumbnail path */
  thumbTempFilePath?: string;
}

Usage Examples:

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

// Record short video
const video = await chooseVideo({
  sourceType: ['camera'],
  maxDuration: 60,
  compressed: true,
  camera: 'back'
});

console.log(`Video: ${video.duration}s, ${video.size} bytes`);

// Choose from gallery
chooseVideo({
  sourceType: ['album'],
  success(result) {
    console.log('Video dimensions:', result.width, 'x', result.height);
    if (result.thumbTempFilePath) {
      displayVideoThumbnail(result.thumbTempFilePath);
    }
  }
});

Video Information

Retrieve metadata and properties of video files.

/**
 * Get video information
 * @param options - Video info options
 * @returns Promise resolving to video information
 */
function getVideoInfo(options: GetVideoInfoOptions): Promise<GetVideoInfoResult>;

interface GetVideoInfoOptions {
  /** Video file path */
  src: string;
  /** Success callback */
  success?: (result: GetVideoInfoResult) => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface GetVideoInfoResult {
  /** Video orientation */
  orientation: 'up' | 'down' | 'left' | 'right';
  /** Video type/format */
  type: string;
  /** Video duration in seconds */
  duration: number;
  /** Video file size in bytes */
  size: number;
  /** Video width in pixels */
  width: number;
  /** Video height in pixels */
  height: number;
  /** Video frame rate */
  fps?: number;
  /** Video bitrate */
  bitrate?: number;
}

File Selection

Choose various file types with filtering and validation capabilities.

/**
 * Choose files from device storage
 * @param options - File selection options
 * @returns Promise resolving to selected files
 */
function chooseFile(options?: ChooseFileOptions): Promise<ChooseFileResult>;

interface ChooseFileOptions {
  /** Maximum number of files to select */
  count?: number;
  /** File type filters */
  type?: 'all' | 'video' | 'image';
  /** File extensions to filter */
  extension?: string[];
  /** Success callback */
  success?: (result: ChooseFileResult) => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface ChooseFileResult {
  /** Selected file paths */
  tempFilePaths: string[];
  /** Selected files */
  tempFiles: ChooseFile[];
}

interface ChooseFile {
  /** File path */
  path: string;
  /** File size in bytes */
  size: number;
  /** File name */
  name: string;
  /** File type */
  type: string;
}

Usage Examples:

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

// Choose document files
const files = await chooseFile({
  count: 5,
  type: 'all',
  extension: ['pdf', 'doc', 'docx', 'txt']
});

files.tempFiles.forEach(file => {
  console.log(`Selected: ${file.name} (${file.size} bytes)`);
});

// Choose media files only
chooseFile({
  count: 10,
  type: 'image',
  success(result) {
    processMediaFiles(result.tempFiles);
  }
});

Image Preview

Display images in a full-screen preview with navigation and zoom capabilities.

/**
 * Preview images in full screen
 * @param options - Preview options
 */
function previewImage(options: PreviewImageOptions): void;

interface PreviewImageOptions {
  /** Current image index */
  current?: string | number;
  /** Array of image URLs to preview */
  urls: string[];
  /** Indicator display */
  indicator?: 'default' | 'number' | 'none';
  /** Whether to loop through images */
  loop?: boolean;
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

Usage Examples:

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

// Preview image gallery
previewImage({
  current: 0,
  urls: [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg',
    'https://example.com/image3.jpg'
  ],
  indicator: 'number',
  loop: true
});

// Preview with specific starting image
previewImage({
  current: 'https://example.com/featured.jpg',
  urls: imageUrls,
  success() {
    console.log('Image preview opened');
  }
});

File Information

Get detailed information about files including size, type, and metadata.

/**
 * Get file information
 * @param options - File info options
 * @returns Promise with file information
 */
function getFileInfo(options: GetFileInfoOptions): Promise<GetFileInfoResult>;

interface GetFileInfoOptions {
  /** File path to get info for */
  filePath: string;
  /** Digest algorithm for checksum */
  digestAlgorithm?: 'md5' | 'sha1';
  /** Success callback */
  success?: (result: GetFileInfoResult) => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface GetFileInfoResult {
  /** File size in bytes */
  size: number;
  /** File digest/checksum */
  digest?: string;
}

Usage Example:

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

// Get file size and checksum
const fileInfo = await getFileInfo({
  filePath: '/path/to/document.pdf',
  digestAlgorithm: 'md5'
});

console.log(`File size: ${fileInfo.size} bytes`);
console.log(`MD5 checksum: ${fileInfo.digest}`);

Document Opening

Open documents using the system's default application or document viewer.

/**
 * Open document with system default application
 * @param options - Document open options
 */
function openDocument(options: OpenDocumentOptions): Promise<void>;

interface OpenDocumentOptions {
  /** Document file path */
  filePath: string;
  /** File type hint */
  fileType?: string;
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

Usage Example:

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

// Open PDF document
await openDocument({
  filePath: '/temp/report.pdf',
  fileType: 'pdf'
});

// Open with error handling
try {
  await openDocument({
    filePath: downloadedFilePath,
    fileType: 'docx'
  });
  console.log('Document opened successfully');
} catch (error) {
  console.error('Failed to open document:', error);
}

Media Utilities

Helper functions for media processing and format conversion.

/**
 * Save image to album
 * @param options - Save image options
 */
function saveImageToPhotosAlbum(options: SaveImageOptions): void;

/**
 * Save video to album
 * @param options - Save video options
 */
function saveVideoToPhotosAlbum(options: SaveVideoOptions): void;

interface SaveImageOptions {
  /** Image file path */
  filePath: string;
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

interface SaveVideoOptions {
  /** Video file path */
  filePath: string;
  /** Success callback */
  success?: () => void;
  /** Failure callback */
  fail?: (error: any) => void;
  /** Completion callback */
  complete?: () => void;
}

Usage Examples:

import { saveImageToPhotosAlbum, saveVideoToPhotosAlbum } from "@dcloudio/uni-h5";

// Save processed image
saveImageToPhotosAlbum({
  filePath: processedImagePath,
  success() {
    uni.showToast({
      title: 'Image saved to album',
      icon: 'success'
    });
  },
  fail() {
    uni.showToast({
      title: 'Failed to save image',
      icon: 'error'
    });
  }
});

// Save recorded video
saveVideoToPhotosAlbum({
  filePath: videoPath,
  success() {
    console.log('Video saved successfully');
  }
});

Media Types

// Media file information
interface MediaFile {
  path: string;
  size: number;
  name: string;
  type: string;
  lastModified?: number;
}

// Image specific types
interface ImageDimensions {
  width: number;
  height: number;
}

// Video specific types
interface VideoProperties {
  duration: number;
  fps?: number;
  bitrate?: number;
  codec?: string;
}

// Media source types
type MediaSource = 'camera' | 'album';

// Size type options
type SizeType = 'original' | 'compressed';

// File type filters
type FileTypeFilter = 'all' | 'image' | 'video' | 'audio';