@cocos/cocos-cli-types 0.0.1-alpha.15.1 → 0.0.1-alpha.17.1

package/assets.d.ts

@@ -965,6 +965,99 @@ declare enum NormalImportSetting {
     recalculate = 3
 }
 
+/**
+ * Listen to Asset Added Event // 监听资源添加事件
+ * @param listener Callback function that receives asset information
+ * @returns Function to remove the listener
+ *
+ * 推荐用法：
+ * ```typescript
+ * const removeListener = onAssetAdded((info) => {
+ *     console.log(`资源已添加: ${info.name}`);
+ *     console.log(`  逻辑路径: ${info.url}`);
+ *     console.log(`  物理路径: ${info.file}`);
+ * });
+ * // 稍后移除监听
+ * removeListener();
+ * ```
+ */
+export declare function onAssetAdded(listener: (info: IAssetInfo) => void): () => void;
+
+/**
+ * Listen to Asset Changed Event // 监听资源变更事件
+ * @param listener Callback function that receives asset information
+ * @returns Function to remove the listener
+ *
+ * 推荐用法：
+ * ```typescript
+ * const removeListener = onAssetChanged((info) => {
+ *     console.log(`资源已变更: ${info.name}`);
+ * });
+ * // 稍后移除监听
+ * removeListener();
+ * ```
+ */
+export declare function onAssetChanged(listener: (info: IAssetInfo) => void): () => void;
+
+/**
+ * Listen to Asset Removed Event // 监听资源删除事件
+ * @param listener Callback function that receives asset information
+ * @returns Function to remove the listener
+ *
+ * 推荐用法：
+ * ```typescript
+ * const removeListener = onAssetRemoved((info) => {
+ *     console.log(`资源已删除: ${info.name}`);
+ * });
+ * // 稍后移除监听
+ * removeListener();
+ * ```
+ */
+export declare function onAssetRemoved(listener: (info: IAssetInfo) => void): () => void;
+
+/**
+ * Register listener for when a specific database finishes starting.
+ *
+ * 注册单个数据库启动完成后的事件监听。
+ *
+ * **注意事项 (Notice)**:
+ * - 这个事件可能会被触发多次（如果项目存在多个子数据库，如 `assets`, `internal`）。
+ * - 主要用于需要做更精细化并行控制的上层逻辑，通常情况下普通的业务逻辑不需要关心此事件，直接监听 `onReady` 即可。
+ *
+ * @param listener 回调函数，接收启动完成的 dbInfo
+ * @returns 移除监听的函数
+ */
+export declare function onDBReady(listener: (dbInfo: IAssetDBInfo) => void): () => void;
+
+/**
+ * Register listener for initialization progress.
+ *
+ * 注册初始化过程中的进度监听。
+ *
+ * **注意事项 (Notice)**:
+ * - **仅在启动阶段有效**。一旦触发过一次 `ready` 事件（即启动阶段结束），将不再会有新的进度消息。
+ * - 启动时的资源冷导入会抛出密集的进度信息，建议在 UI 层面进行适当的节流（throttle）渲染。
+ *
+ * @param listener 回调函数，包含当前进度、总数、当前处理的资源 url 和导入状态
+ * @returns 移除监听的函数
+ */
+export declare function onProgress(listener: (current: number, total: number, url: string, state: 'processing' | 'success' | 'failed') => void): () => void;
+
+/**
+ * Register listener for when all asset databases are fully initialized.
+ *
+ * 注册数据库初始化完全完成后的事件监听。
+ *
+ * **注意事项 (Notice)**:
+ * - 触发此事件代表**所有**注册的资源数据库都已经完全导入并初始化完成（启动阶段结束）。
+ * - 收到此事件后，表示所有的资源查询、操作 API 都可以安全调用。
+ * - 第一次 ready 后，将不再有 progress 进度消息。
+ *
+ * @param listener 回调函数
+ * @returns 移除监听的函数
+ */
+export declare function onReady(listener: () => void): () => void;
+
 /** 粒子资源的 userData */
 declare interface ParticleAssetUserData {
     totalParticles: number;
@@ -1246,6 +1339,11 @@ declare interface SpriteFrameVertices {
     maxPos: number[];
 }
 
+/**
+ * Start Asset DB // 启动资源数据库，开始扫描和导入资源
+ */
+export declare function start(): Promise<void>;
+
 /** 支持创建的资源类型常量数组（用于 Zod enum 和 TypeScript type） */
 declare const SUPPORT_CREATE_TYPES: readonly ['animation-clip', 'typescript', 'auto-atlas', 'effect', 'scene', 'prefab', 'material', 'terrain', 'physics-material', 'label-atlas', 'render-texture', 'directory', 'effect-header'];
 

package/builder.d.ts

@@ -4842,7 +4842,7 @@ declare class StatsQuery {
  */
 declare namespace StatsQuery {
     namespace ConstantManager {
-        type PlatformType = 'WEB_EDITOR' | 'WEB_MOBILE' | 'WEB_DESKTOP' | 'WECHAT' | 'WECHAT_MINI_PROGRAM' | 'BYTEDANCE' | 'XIAOMI' | 'ALIPAY' | 'TAOBAO' | 'TAOBAO_MINIGAME' | 'OPPO' | 'VIVO' | 'HUAWEI' | 'MIGU' | 'HONOR' | 'COCOS_RUNTIME' | 'NATIVE_EDITOR' | 'ANDROID' | 'WINDOWS' | 'IOS' | 'MAC' | 'OHOS' | 'OPEN_HARMONY' | 'LINUX' | 'HTML5' | 'NATIVE' | 'NODEJS' | 'INVALID_PLATFORM';
+        type PlatformType = 'WEB_EDITOR' | 'WEB_MOBILE' | 'WEB_DESKTOP' | 'WECHAT' | 'WECHAT_MINI_PROGRAM' | 'BYTEDANCE' | 'XIAOMI' | 'ALIPAY' | 'TAOBAO' | 'TAOBAO_MINIGAME' | 'OPPO' | 'VIVO' | 'HUAWEI' | 'MIGU' | 'HONOR' | 'COCOS_RUNTIME' | 'SUD' | 'SUDV2' | 'NATIVE_EDITOR' | 'ANDROID' | 'WINDOWS' | 'IOS' | 'MAC' | 'OHOS' | 'OPEN_HARMONY' | 'LINUX' | 'HTML5' | 'NATIVE' | 'NODEJS' | 'INVALID_PLATFORM';
         type IPlatformConfig = { [key in PlatformType]: boolean };
         interface IInternalFlagConfig {
             SERVER_MODE: boolean;

package/configuration.d.ts

@@ -1,3 +1,56 @@
+import { EventEmitter } from 'events';
+
+/**
+ * 配置范围
+ */
+export declare type ConfigurationScope = 'default' | 'project';
+
+declare type EventEmitterMethods = Pick<EventEmitter, 'on' | 'off' | 'once' | 'emit'>;
+
+export declare function get<T>(key: string, scope?: ConfigurationScope): Promise<T>;
+
+/**
+ * 配置基类接口
+ */
+export declare interface IBaseConfiguration extends EventEmitterMethods {
+    /**
+     * 模块名
+     */
+    moduleName: string;
+    /**
+     * 默认配置数据
+     */
+    getDefaultConfig(): Record<string, any> | undefined;
+    /**
+     * 获取配置值
+     * @param key 配置键名，支持点号分隔的嵌套路径
+     * @param scope 配置作用域，不指定时按优先级查找
+     */
+    get<T>(key?: string, scope?: ConfigurationScope): Promise<T>;
+    /**
+     * 获取指定范围的所有配置，默认是 project
+     * @param scope
+     */
+    getAll(scope?: ConfigurationScope): Record<string, any> | undefined;
+    /**
+     * 设置配置值
+     * @param key 配置键名，支持点号分隔的嵌套路径
+     * @param value 新的配置值
+     * @param scope 配置作用域，默认为 'project'
+     */
+    set<T>(key: string, value: T, scope?: ConfigurationScope): Promise<boolean>;
+    /**
+     * 移除配置值
+     * @param key 配置键名，支持点号分隔的嵌套路径
+     * @param scope 配置作用域，默认为 'project'
+     */
+    remove(key: string, scope?: ConfigurationScope): Promise<boolean>;
+    /**
+     * 保存配置
+     */
+    save(): Promise<boolean>;
+}
+
 /**
  * 配置的格式
  */
@@ -10,8 +63,16 @@ export declare interface IConfiguration {
 
 export declare function init(projectPath: string): Promise<void>;
 
+export declare function migrate(): Promise<void>;
+
 export declare function migrateFromProject(): Promise<IConfiguration>;
 
 export declare function reload(): Promise<void>;
 
+export declare function remove(key: string, scope?: ConfigurationScope): Promise<boolean>;
+
+export declare function save(force?: boolean): Promise<void>;
+
+export declare function set<T>(key: string, value: T, scope?: ConfigurationScope): Promise<boolean>;
+
 export { };

package/index.d.ts

@@ -1,5 +1,7 @@
 /// <reference types="node" />
 
+import { EventEmitter } from 'events';
+
 /** 动画剪辑资源的 userData */
 declare interface AnimationClipAssetUserData {
     /** 动画名称 */
@@ -208,6 +210,10 @@ declare interface AssetOperationOption {
 export declare namespace Assets {
     export {
         init,
+        start,
+        onReady,
+        onDBReady,
+        onProgress,
         deleteAsset,
         refresh,
         queryAssetInfo,
@@ -232,6 +238,9 @@ export declare namespace Assets {
         queryAssetUserDataConfig,
         updateAssetUserData,
         queryAssetConfigMap,
+        onAssetAdded,
+        onAssetChanged,
+        onAssetRemoved,
         CreateAssetOptions,
         IAssetConfig,
         IAssetDBInfo,
@@ -346,10 +355,22 @@ export declare namespace Configuration {
         init_3 as init,
         migrateFromProject,
         reload,
-        IConfiguration
+        migrate,
+        get,
+        set,
+        remove,
+        save,
+        IConfiguration,
+        ConfigurationScope,
+        IBaseConfiguration
     };
 }
 
+/**
+ * 配置范围
+ */
+declare type ConfigurationScope = 'default' | 'project';
+
 /**
  * Create Asset // 创建资源
  */
@@ -428,6 +449,8 @@ export declare namespace Engine {
     };
 }
 
+declare type EventEmitterMethods = Pick<EventEmitter, 'on' | 'off' | 'once' | 'emit'>;
+
 declare interface ExecuteAssetDBScriptMethodOptions {
     name: string;
     method: string;
@@ -476,6 +499,8 @@ declare interface FontDefDictionary {
     [charId: number]: FontDef;
 }
 
+declare function get<T>(key: string, scope?: ConfigurationScope): Promise<T>;
+
 /** glTF 动画资源的 userData */
 declare interface GltfAnimationAssetUserData {
     gltfIndex: number;
@@ -752,6 +777,48 @@ declare type IAssetType =
 | 'RenderStage'            // 渲染阶段
 | 'RenderFlow';
 
+/**
+ * 配置基类接口
+ */
+declare interface IBaseConfiguration extends EventEmitterMethods {
+    /**
+     * 模块名
+     */
+    moduleName: string;
+    /**
+     * 默认配置数据
+     */
+    getDefaultConfig(): Record<string, any> | undefined;
+    /**
+     * 获取配置值
+     * @param key 配置键名，支持点号分隔的嵌套路径
+     * @param scope 配置作用域，不指定时按优先级查找
+     */
+    get<T>(key?: string, scope?: ConfigurationScope): Promise<T>;
+    /**
+     * 获取指定范围的所有配置，默认是 project
+     * @param scope
+     */
+    getAll(scope?: ConfigurationScope): Record<string, any> | undefined;
+    /**
+     * 设置配置值
+     * @param key 配置键名，支持点号分隔的嵌套路径
+     * @param value 新的配置值
+     * @param scope 配置作用域，默认为 'project'
+     */
+    set<T>(key: string, value: T, scope?: ConfigurationScope): Promise<boolean>;
+    /**
+     * 移除配置值
+     * @param key 配置键名，支持点号分隔的嵌套路径
+     * @param scope 配置作用域，默认为 'project'
+     */
+    remove(key: string, scope?: ConfigurationScope): Promise<boolean>;
+    /**
+     * 保存配置
+     */
+    save(): Promise<boolean>;
+}
+
 /**
  * 配置的格式
  */
@@ -1034,6 +1101,8 @@ declare interface MeshSimplifyOptions {
     lockBoundary?: boolean;
 }
 
+declare function migrate(): Promise<void>;
+
 declare function migrateFromProject(): Promise<IConfiguration>;
 
 /**
@@ -1060,6 +1129,99 @@ declare enum NormalImportSetting {
     recalculate = 3
 }
 
+/**
+ * Listen to Asset Added Event // 监听资源添加事件
+ * @param listener Callback function that receives asset information
+ * @returns Function to remove the listener
+ *
+ * 推荐用法：
+ * ```typescript
+ * const removeListener = onAssetAdded((info) => {
+ *     console.log(`资源已添加: ${info.name}`);
+ *     console.log(`  逻辑路径: ${info.url}`);
+ *     console.log(`  物理路径: ${info.file}`);
+ * });
+ * // 稍后移除监听
+ * removeListener();
+ * ```
+ */
+declare function onAssetAdded(listener: (info: IAssetInfo) => void): () => void;
+
+/**
+ * Listen to Asset Changed Event // 监听资源变更事件
+ * @param listener Callback function that receives asset information
+ * @returns Function to remove the listener
+ *
+ * 推荐用法：
+ * ```typescript
+ * const removeListener = onAssetChanged((info) => {
+ *     console.log(`资源已变更: ${info.name}`);
+ * });
+ * // 稍后移除监听
+ * removeListener();
+ * ```
+ */
+declare function onAssetChanged(listener: (info: IAssetInfo) => void): () => void;
+
+/**
+ * Listen to Asset Removed Event // 监听资源删除事件
+ * @param listener Callback function that receives asset information
+ * @returns Function to remove the listener
+ *
+ * 推荐用法：
+ * ```typescript
+ * const removeListener = onAssetRemoved((info) => {
+ *     console.log(`资源已删除: ${info.name}`);
+ * });
+ * // 稍后移除监听
+ * removeListener();
+ * ```
+ */
+declare function onAssetRemoved(listener: (info: IAssetInfo) => void): () => void;
+
+/**
+ * Register listener for when a specific database finishes starting.
+ *
+ * 注册单个数据库启动完成后的事件监听。
+ *
+ * **注意事项 (Notice)**:
+ * - 这个事件可能会被触发多次（如果项目存在多个子数据库，如 `assets`, `internal`）。
+ * - 主要用于需要做更精细化并行控制的上层逻辑，通常情况下普通的业务逻辑不需要关心此事件，直接监听 `onReady` 即可。
+ *
+ * @param listener 回调函数，接收启动完成的 dbInfo
+ * @returns 移除监听的函数
+ */
+declare function onDBReady(listener: (dbInfo: IAssetDBInfo) => void): () => void;
+
+/**
+ * Register listener for initialization progress.
+ *
+ * 注册初始化过程中的进度监听。
+ *
+ * **注意事项 (Notice)**:
+ * - **仅在启动阶段有效**。一旦触发过一次 `ready` 事件（即启动阶段结束），将不再会有新的进度消息。
+ * - 启动时的资源冷导入会抛出密集的进度信息，建议在 UI 层面进行适当的节流（throttle）渲染。
+ *
+ * @param listener 回调函数，包含当前进度、总数、当前处理的资源 url 和导入状态
+ * @returns 移除监听的函数
+ */
+declare function onProgress(listener: (current: number, total: number, url: string, state: 'processing' | 'success' | 'failed') => void): () => void;
+
+/**
+ * Register listener for when all asset databases are fully initialized.
+ *
+ * 注册数据库初始化完全完成后的事件监听。
+ *
+ * **注意事项 (Notice)**:
+ * - 触发此事件代表**所有**注册的资源数据库都已经完全导入并初始化完成（启动阶段结束）。
+ * - 收到此事件后，表示所有的资源查询、操作 API 都可以安全调用。
+ * - 第一次 ready 后，将不再有 progress 进度消息。
+ *
+ * @param listener 回调函数
+ * @returns 移除监听的函数
+ */
+declare function onReady(listener: () => void): () => void;
+
 declare function open_2(projectPath: string): Promise<void>;
 
 /** 粒子资源的 userData */
@@ -1243,6 +1405,8 @@ declare function reimportAsset(pathOrUrlOrUUID: string): Promise<IAssetInfo>;
 
 declare function reload(): Promise<void>;
 
+declare function remove(key: string, scope?: ConfigurationScope): Promise<boolean>;
+
 /**
  * Rename Asset // 重命名资源
  */
@@ -1264,6 +1428,8 @@ declare interface RtSpriteFrameAssetUserData {
     height?: number;
 }
 
+declare function save(force?: boolean): Promise<void>;
+
 /**
  * Save Asset // 保存资源
  */
@@ -1289,6 +1455,8 @@ declare interface SerializedAssetFinder {
     scenes?: Array<string | null>;
 }
 
+declare function set<T>(key: string, value: T, scope?: ConfigurationScope): Promise<boolean>;
+
 declare interface SimplifyOptions {
     // 压缩比例
     targetRatio?: number;
@@ -1359,6 +1527,11 @@ declare interface SpriteFrameVertices {
     maxPos: number[];
 }
 
+/**
+ * Start Asset DB // 启动资源数据库，开始扫描和导入资源
+ */
+declare function start(): Promise<void>;
+
 /** 支持创建的资源类型常量数组（用于 Zod enum 和 TypeScript type） */
 declare const SUPPORT_CREATE_TYPES: readonly ['animation-clip', 'typescript', 'auto-atlas', 'effect', 'scene', 'prefab', 'material', 'terrain', 'physics-material', 'label-atlas', 'render-texture', 'directory', 'effect-header'];
 

package/package.json

@@ -2,7 +2,7 @@
     "name": "@cocos/cocos-cli-types",
     "description": "types for cocos cli",
     "author": "cocos cli",
-    "version": "0.0.1-alpha.15.1",
+    "version": "0.0.1-alpha.17.1",
     "main": "index.d.ts",
     "types": "index.d.ts",
     "files": [