Configuration System
The Cocos Creator extension provides a configuration management mechanism for saving user settings and data in the extension.
Configuration Types
There are two types of configuration types.
- editor configuration (editor)
- project configuration (project)
Editor Configuration
The editor configuration is used to store some editor-related user settings and data, and is divided into three priority levels, from high to low, as follows.
local -> global -> default
If there is no corresponding configuration in local
, the configuration in global
will be used, and if no corresponding configuration in global
is found, the default default
configuration will be used.
Project Configuration
The project configuration is used to store some project-related user settings and data, and is divided into two priority levels, from highest to lowest.
local -> default
Similar to the rules of Editor Configuration, when fetching configuration data, the configuration item in local
will be used first, and if there is no corresponding configuration item in local
, the default default
configuration will be used.
Registering Configuration
To use the configuration system, you need to define the profile
information in the contributions
field of the extension definition file package.json
, as follows.
{
"name": "hello-world",
"contributions": {
"profile": {
"editor": {
"test.a": {
"default": 0,
"message": "editorTestAChanged",
"label": "Test Editor configuration"
}
},
"project": {
"test.a": {
"default": 1,
"message": "projectTestAChanged",
"label": "Test Project Configuration"
}
}
}
},
}
contributions.profile The related fields are interpreted as follows.
editor
:{} - editor configurationproject
:{} - project configurationtest.a
:{} - key for the configuration of test.adefault
:any - the default value of this configuration item, optional parametermessage
:string - the message that will be triggered when this configuration item is modified, optionallabel
:string - where the configuration can be displayed, this description may be displayed. Supports i18n:key format, optional parameters
The TypeScript interface associated with profile
is defined as follows.
interface ProfileInfo {
editor: { [ key: string ]: ProfileItem };
project: { [ key: string ]: ProfileItem };
}
interface ProfileItem {
// Default data for configuration
default: any;
// This message is automatically sent for notification of configuration changes
message: string;
// A simple description of the role of configuration information, supporting the i18n:key syntax
label: string;
}
Read and Modify Configuration
Importing Extension Definitions
import packageJSON from '../package.json';
If the last parameter of Editor.Profile.getConfig
is empty, a priority match will be performed.
If the fetch location (one of local
, global
, default
) is specified, the corresponding value will be returned. As shown below, local
and global
are undefined
because they are not set.
await Editor.Profile.getConfig(packageJSON.name, 'test.a'); // 0
await Editor.Profile.getConfig(packageJSON.name, 'test.a', 'local'); // undefined
await Editor.Profile.getConfig(packageJSON.name, 'test.a', 'global'); // undefined
Modify the Editor Configuration
Call getConfig
after modifying the configuration with the following code to see the corresponding changes.
await Editor.Profile.setConfig(packageJSON.name, 'test.a', 1);
await Editor.Profile.setConfig(packageJSON.name, 'test.a', 'local', 2);
await Editor.Profile.setConfig(packageJSON.name, 'test.a', 'global', 3);
Read Project Configuration
If the last parameter of Editor.Profile.getProject
is empty, a priority match will be performed.
If the fetch location (either local
, default
) is specified, the corresponding value will be returned. As shown below, the local
is undefined
because it is not set.
await Editor.Profile.getProject(packageJSON.name, 'test.a'); // 1
await Editor.Profile.getProject(packageJSON.name, 'test.a', 'local'); // undefined
Modify the Project Configuration
Call getProject
after modifying the configuration with the following code to see the corresponding changes.
await Editor.Profile.setProject(packageJSON.name, 'test.a', 1);
await Editor.Profile.setProject(packageJSON.name, 'test.a', 'local', 2);
Storage Paths
Editor Configuration Storage Path
Hierarchy | Path |
---|---|
local | {projectPath}/profiles/v2/extensions/{extensionName}.json |
global(mac) | Users/{name}/.CocosCreator/profiles/v2/extensions/{extensionName}.json |
global(window) | c/Users/{name}/.CocosCreator/profiles/v2/extensions/{extensionName}.json |
default | {extensionPath}/package.json |
Project Configuration Storage Path
Hierarchy | Path |
---|---|
local | {projectPath}/settings/v2/extensions/{extensionName}.json |
default | {extensionPath}/package.json |