@sakitam-gis/sprite-cli 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,303 @@
+/**
+ * 图片缓冲区（支持 SVG 和 PNG）
+ */
+interface ImageBuffer {
+    svg?: Buffer;
+    png?: Buffer;
+    id: string;
+    type?: 'svg' | 'png';
+    width?: number;
+    height?: number;
+}
+/**
+ * 生成配置选项
+ */
+interface LayoutOptions {
+    imgs: ImageBuffer[];
+    pixelRatio: number;
+    format: boolean;
+    extractMetadata?: boolean;
+}
+/**
+ * 生成配置选项（兼容旧名称）
+ */
+type GenerateOptions = LayoutOptions;
+/**
+ * Mapbox 样式元数据
+ * 支持9-patch拉伸和文本占位符
+ *
+ * @see https://docs.mapbox.com/mapbox-gl-js/style-spec/sprite/#stretch-metadata
+ */
+interface SpriteMetadata {
+    /** 内容区域边界 [left, top, right, bottom] */
+    content?: [number, number, number, number];
+    /** 文本占位符区域 [left, top, right, bottom] */
+    placeholder?: [number, number, number, number];
+    /** 水平拉伸区域数组 [[start, end], ...] */
+    stretchX?: Array<[number, number]>;
+    /** 垂直拉伸区域数组 [[start, end], ...] */
+    stretchY?: Array<[number, number]>;
+}
+/**
+ * 雪碧图布局项
+ */
+interface LayoutItem {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    pixelRatio: number;
+    content?: [number, number, number, number];
+    placeholder?: [number, number, number, number];
+    stretchX?: Array<[number, number]>;
+    stretchY?: Array<[number, number]>;
+    data?: any;
+    svg?: Buffer;
+    png?: Buffer;
+}
+/**
+ * 雪碧图布局对象
+ */
+type Layout = Record<string, LayoutItem>;
+
+/**
+ * 雪碧图生成选项
+ */
+interface SpriteOptions {
+    /** 输出文件路径（不包含扩展名） */
+    output: string;
+    /** 输入目录路径 */
+    input: string;
+    /** 像素比率 (默认: 1) */
+    ratio?: number;
+    /** 是否使用 unique 模式 (默认: false) */
+    unique?: boolean;
+    /** 是否格式化 JSON 输出 (默认: true) */
+    format?: boolean;
+}
+/**
+ * 雪碧图生成结果
+ */
+interface SpriteResult {
+    /** JSON 文件路径 */
+    jsonPath: string;
+    /** PNG 文件路径 */
+    pngPath: string;
+    /** 布局对象 */
+    layout: Layout;
+    /** 生成的图片数量 */
+    imageCount: number;
+}
+/**
+ * 生成雪碧图
+ *
+ * @param options 生成选项
+ * @returns Promise<SpriteResult> 生成结果
+ *
+ * @example
+ * ```typescript
+ * import { generateSprite } from '@sakitam-gis/sprite-cli';
+ *
+ * // 生成 1x 雪碧图
+ * const result = await generateSprite({
+ *   output: 'output/sprite',
+ *   input: 'icons/',
+ * });
+ *
+ * // 生成 2x 雪碧图
+ * const result2x = await generateSprite({
+ *   output: 'output/sprite@2x',
+ *   input: 'icons/',
+ *   ratio: 2,
+ * });
+ *
+ * // 使用 unique 模式
+ * const resultUnique = await generateSprite({
+ *   output: 'output/sprite-unique',
+ *   input: 'icons/',
+ *   unique: true,
+ * });
+ * ```
+ */
+declare function generateSprite(options: SpriteOptions): Promise<SpriteResult>;
+/**
+ * 批量生成多个比例的雪碧图
+ *
+ * @param input 输入目录
+ * @param output 输出文件路径（不包含扩展名）
+ * @param ratios 像素比率数组 (默认: [1, 2])
+ * @param unique 是否使用 unique 模式 (默认: false)
+ * @returns Promise<SpriteResult[]> 生成结果数组
+ *
+ * @example
+ * ```typescript
+ * import { generateSpriteMultiple } from '@sakitam-gis/sprite-cli';
+ *
+ * // 生成 1x 和 2x 两个版本
+ * const results = await generateSpriteMultiple('icons/', 'output/sprite');
+ *
+ * // 生成 1x、2x、3x 三个版本
+ * const results2 = await generateSpriteMultiple('icons/', 'output/sprite', [1, 2, 3]);
+ * ```
+ */
+declare function generateSpriteMultiple(input: string, output: string, ratios?: number[], unique?: boolean): Promise<SpriteResult[]>;
+/**
+ * 从已加载的图片缓冲区生成雪碧图
+ * 适用于需要自定义图片加载逻辑的场景
+ *
+ * @param buffers 图片缓冲区数组
+ * @param output 输出文件路径（不包含扩展名）
+ * @param options 额外选项
+ * @returns Promise<SpriteResult> 生成结果
+ *
+ * @example
+ * ```typescript
+ * import { generateSpriteFromBuffers } from '@sakitam-gis/sprite-cli';
+ * import fs from 'fs/promises';
+ *
+ * const buffers = [
+ *   { id: 'icon1', svg: await fs.readFile('icon1.svg') },
+ *   { id: 'icon2', svg: await fs.readFile('icon2.svg') },
+ * ];
+ *
+ * const result = await generateSpriteFromBuffers(buffers, 'output/sprite');
+ * ```
+ */
+declare function generateSpriteFromBuffers(buffers: ImageBuffer[], output: string, options?: {
+    ratio?: number;
+    unique?: boolean;
+    format?: boolean;
+}): Promise<SpriteResult>;
+
+/**
+ * 获取目录中所有图片文件的路径（支持 SVG 和 PNG）
+ * @param dir 目录路径
+ * @returns 文件路径数组
+ */
+declare function getFilePaths(dir: string): Promise<string[]>;
+/**
+ * 加载单个图片文件（支持 SVG 和 PNG）
+ * @param filePath 文件路径
+ * @returns 图片缓冲区对象
+ */
+declare function loadFile(filePath: string): Promise<ImageBuffer>;
+/**
+ * 根据 ID 排序
+ * @param a 第一个图片缓冲区
+ * @param b 第二个图片缓冲区
+ * @returns 排序结果
+ */
+declare function sortById(a: ImageBuffer, b: ImageBuffer): number;
+
+/**
+ * Sprite layout generation
+ * Migrated from @mapbox/spritezero with TypeScript enhancements
+ */
+
+/**
+ * 清除 SVG 尺寸缓存
+ * 用于测试或内存管理
+ */
+declare function clearDimensionsCache(): void;
+/**
+ * Generate sprite layout
+ * @param options - Layout options
+ * @returns Layout object
+ */
+declare function generateLayout(options: LayoutOptions): Promise<Layout>;
+/**
+ * Generate unique sprite layout (deduplicates identical images)
+ * @param options - Layout options
+ * @returns Layout object
+ */
+declare function generateLayoutUnique(options: LayoutOptions): Promise<Layout>;
+
+/**
+ * Sprite image generation
+ * Migrated from @mapbox/spritezero with TypeScript enhancements
+ *
+ * 支持：
+ * - 标准PNG输出
+ * - 优化PNG输出（颜色量化、压缩）
+ */
+
+/**
+ * Generate sprite image from layout
+ * @param layout - Sprite layout (must include SVG data)
+ * @returns PNG image buffer
+ * @throws Error if layout is empty or invalid
+ */
+declare function generateImage(layout: Layout): Promise<Buffer>;
+/**
+ * PNG 优化选项
+ */
+interface OptimizeOptions {
+    /** 颜色数量 (default: 256) */
+    colors?: number;
+    /** 压缩质量 0-100 (default: 80) */
+    quality?: number;
+    /** 是否使用调色板模式 (default: true) */
+    palette?: boolean;
+}
+/**
+ * 生成优化的PNG雪碧图
+ *
+ * 使用 sharp 进行 PNG 优化：
+ * - 颜色量化（减少到指定颜色数）
+ * - PNG 压缩优化
+ * - 减小文件大小 30-50%
+ *
+ * @param layout - Sprite layout
+ * @param options - 优化选项
+ * @returns 优化后的PNG buffer
+ *
+ * @example
+ * ```ts
+ * const optimizedPng = await generateOptimizedImage(layout, {
+ *   colors: 256,
+ *   quality: 80,
+ *   palette: true
+ * });
+ * ```
+ */
+declare function generateOptimizedImage(layout: Layout, options?: OptimizeOptions): Promise<Buffer>;
+
+/**
+ * SVG Metadata Extraction
+ *
+ * 支持从SVG中提取Mapbox样式的stretch元数据和placeholder元数据
+ * 用于实现9-patch风格的图像拉伸和文本占位符
+ *
+ * 元数据通过特殊命名的SVG路径标记提取：
+ * - id="mapbox-stretch-x" 或 id="mapbox-stretch" : 水平拉伸区域
+ * - id="mapbox-stretch-y" 或 id="mapbox-stretch" : 垂直拉伸区域
+ * - id="mapbox-content" : 内容区域
+ * - id="mapbox-text-placeholder" : 文本占位符区域
+ *
+ * @see https://docs.mapbox.com/mapbox-gl-js/style-spec/sprite/#stretch-metadata
+ */
+
+/**
+ * 从SVG Buffer中提取元数据
+ *
+ * 使用简化的方法：
+ * 1. 使用 svgo 优化 SVG（转换形状为路径等）
+ * 2. 使用 DOMParser 解析优化后的 SVG
+ * 3. 查找带有 mapbox- 前缀的路径
+ * 4. 使用 svg-boundings 计算边界
+ * 5. 按像素比率缩放并返回
+ *
+ * @param svg - SVG文件内容
+ * @param pixelRatio - 像素比率，用于缩放边界坐标
+ * @returns Promise<SpriteMetadata> 提取的元数据
+ */
+declare function extractMetadata(svg: Buffer, pixelRatio?: number): Promise<SpriteMetadata>;
+/**
+ * 检查SVG是否包含元数据标记
+ *
+ * @param svg - SVG文件内容
+ * @returns boolean 是否包含元数据
+ */
+declare function hasMetadata(svg: Buffer): boolean;
+
+export { type GenerateOptions, type ImageBuffer, type Layout, type LayoutItem, type LayoutOptions, type SpriteMetadata, type SpriteOptions, type SpriteResult, clearDimensionsCache, extractMetadata, generateImage, generateLayout, generateLayoutUnique, generateOptimizedImage, generateSprite, generateSpriteFromBuffers, generateSpriteMultiple, getFilePaths, hasMetadata, loadFile, sortById };