Primeros pasos

Instalar

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego usa el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-photo-library` plugin in my project.

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

bun add @capgo/capacitor-photo-library
bunx cap sync

Importar

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

Inicio rápido

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.checkAuthorization();
console.log(result);

Ejemplo: requestAuthorization

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.requestAuthorization();
console.log(result);

Ejemplo: getAlbums

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.getAlbums();
console.log(result);

Errores comunes

• Sync nativo: ejecuta bunx cap sync tras actualizar los plugins.
• Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

Resumen de API

checkAuthorization

Devuelve el estado de autorización actual sin pedir permiso al usuario.

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.checkAuthorization();
console.log(result);

requestAuthorization

Solicita acceso a la biblioteca de fotos si es necesario.

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.requestAuthorization();
console.log(result);

getAlbums

Recupera los álbumes disponibles.

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.getAlbums();
console.log(result);

getLibrary

Obtiene los recursos de la librería junto con las URLs para mostrarlos en la web view.

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.getLibrary();
console.log(result);

getPhotoUrl

Obtiene una URL que se puede mostrar de la versión a resolución completa del asset. Si ya llamaste a getLibrary con includeFullResolutionData, normalmente no necesitas este método.

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.getPhotoUrl({ id: 'id-123' });
console.log(result);

getThumbnailUrl

Obtiene una URL para mostrar una miniatura redimensionada del recurso.

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.getThumbnailUrl({ id: 'id-123' });
console.log(result);

pickMedia

Abre el selector nativo del sistema para que el usuario seleccione contenido multimedia sin conceder acceso completo a la biblioteca de fotos. Los archivos seleccionados se copian en la caché de la aplicación y se devuelven con URLs portables.

import { PhotoLibrary } from '@capgo/capacitor-photo-library';

const result = await PhotoLibrary.pickMedia();
console.log(result);

Referencia de tipos

PhotoLibraryAuthorizationState

export type PhotoLibraryAuthorizationState = 'authorized' | 'limited' | 'denied' | 'notDetermined';

PhotoLibraryAlbum

export interface PhotoLibraryAlbum {
  id: string;
  title: string;
  assetCount: number;
}

GetLibraryOptions

export interface GetLibraryOptions {
  /**
   * Number of assets to skip from the beginning of the query.
   */
  offset?: number;
  /**
   * Maximum number of assets to return. Omit to return everything that matches.
   */
  limit?: number;
  /**
   * Include images in the result. Defaults to `true`.
   */
  includeImages?: boolean;
  /**
   * Include videos in the result. Defaults to `false`.
   */
  includeVideos?: boolean;
  /**
   * Include information about the albums each asset belongs to. Defaults to `false`.
   */
  includeAlbumData?: boolean;
  /**
   * Include assets stored in the cloud (iCloud / Google Photos). Defaults to `true`.
   */
  includeCloudData?: boolean;
  /**
   * If `true`, use the original filenames reported by the OS when available.
   */
  useOriginalFileNames?: boolean;
  /**
   * Width of the generated thumbnails. Defaults to `512`.
   */
  thumbnailWidth?: number;
  /**
   * Height of the generated thumbnails. Defaults to `384`.
   */
  thumbnailHeight?: number;
  /**
   * JPEG quality for generated thumbnails (0-1). Defaults to `0.5`.
   */
  thumbnailQuality?: number;
  /**
   * When `true`, copies the full sized asset into the app cache and returns its URL.
   * Defaults to `false`.
   */
  includeFullResolutionData?: boolean;
}

GetLibraryResult

export interface GetLibraryResult {
  assets: PhotoLibraryAsset[];
  /**
   * Total number of assets matching the query in the library. `assets.length` can be less
   * than this value when pagination is used.
   */
  totalCount: number;
  /** Whether more assets are available when using pagination. */
  hasMore: boolean;
}

PhotoLibraryFile

export interface PhotoLibraryFile {
  /** Absolute path on the native file system. */
  path: string;
  /**
   * URL that can be used inside a web view. Usually produced by `Capacitor.convertFileSrc(path)`.
   */
  webPath: string;
  mimeType: string;
  /** Size in bytes if known, otherwise `-1`. */
  size: number;
}

PickMediaOptions

export interface PickMediaOptions {
  /**
   * Maximum number of items the user can select. Use `0` to allow unlimited selection.
   * Defaults to `1`.
   */
  selectionLimit?: number;
  /** Allow the user to select images. Defaults to `true`. */
  includeImages?: boolean;
  /** Allow the user to select videos. Defaults to `false`. */
  includeVideos?: boolean;
  /** Width of the generated thumbnails for picked items. Defaults to `256`. */
  thumbnailWidth?: number;
  /** Height of the generated thumbnails for picked items. Defaults to `256`. */
  thumbnailHeight?: number;
  /** JPEG quality for generated thumbnails (0-1). Defaults to `0.7`. */
  thumbnailQuality?: number;
}

PickMediaResult

export interface PickMediaResult {
  assets: PhotoLibraryAsset[];
}

PhotoLibraryAsset

export interface PhotoLibraryAsset {
  id: string;
  fileName: string;
  type: PhotoAssetType;
  width: number;
  height: number;
  duration?: number;
  creationDate?: string;
  modificationDate?: string;
  latitude?: number;
  longitude?: number;
  mimeType: string;
  /** Size in bytes reported by the OS for the underlying asset, if available. */
  size?: number;
  albumIds?: string[];
  thumbnail?: PhotoLibraryFile;
  file?: PhotoLibraryFile;
}

PhotoAssetType

export type PhotoAssetType = 'image' | 'video';

Fuente de verdad

Esta página se genera a partir del plugin src/definitions.ts. Vuelve a ejecutar el sync cuando el API público cambie en upstream.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar las operaciones del dashboard y de API, conéctalo con Usando @capgo/capacitor-photo-library para la capacidad nativa al usar @capgo/capacitor-photo-library, Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para los detalles de implementación en las claves de API, y Dispositivos para el detalle de implementación en Devices.