|
| 1 | +# Extending the Preferences Panel |
| 2 | + |
| 3 | +The editor allows each extension to register its own configuration, and then displays some or all of the editor configuration within the Preferences panel. In this panel, the modifications are editor feature-related configurations. |
| 4 | + |
| 5 | +For project-related configurations, please review the [Project Settings](./contributions-project.md) documentation. |
| 6 | + |
| 7 | +## Description of the Preferences Panel |
| 8 | + |
| 9 | +The Preferences panel can be opened via the top menu **Cocos Creator -> Preferences**. |
| 10 | + |
| 11 | + |
| 12 | + |
| 13 | +The Preferences panel is divided into left and right sides. |
| 14 | + |
| 15 | +- The left side shows the names of functional extensions that provide configuration items. |
| 16 | +- On the right side is an action panel rendered according to the configuration. |
| 17 | + |
| 18 | +Changes made in the panel are immediately modified to the corresponding configuration items. |
| 19 | + |
| 20 | +Normally, the configuration is stored at the global level. If the configuration needs to be put into a project, then move the mouse over the configuration entry and select **Record to project** on the small icon that appears on the left side. This data will be saved to the project, and changes to it will not affect other projects. |
| 21 | + |
| 22 | +> **Notes**: |
| 23 | +> 1. If the auto-rendered configuration is stored in the project, the icon on the left side will turn yellow to indicate it. To reuse the global configuration, click the icon on the left side and select **Restore to Global Configuration**, doing so will discard the project settings. |
| 24 | +> 2. Only auto-rendered configurations will automatically add icons. If properties are not defined, implement the icon change function in the panel as needed. |
| 25 | +
|
| 26 | +Also, there are some configurations that cannot switch between global and local storage location, such as preview scenes, which must be stored in the project. This part of the configuration should use the custom panel. |
| 27 | + |
| 28 | +For more information about the **Preferences** panel, please refer to the [Preferences](../../editor/preferences/index.md) documentation. |
| 29 | + |
| 30 | +## Registration Methods |
| 31 | + |
| 32 | +Preferences allow to display configurations in two ways. |
| 33 | + |
| 34 | +1. General configuration |
| 35 | +2. Lab configuration |
| 36 | + |
| 37 | +General settings are displayed directly as tabs, while lab switches are displayed centrally in a separate tab. |
| 38 | + |
| 39 | +- When the functionality provided by the extension is more stable it is recommended to place the configuration data within the generic functionality. |
| 40 | +- When the functionality provided by the extension is in the development stage, it is recommended that the switch configuration data of the functionality be placed in the lab configuration. |
| 41 | + |
| 42 | +First define the configuration in `contributions.profile.editor`. The data to be displayed in the **Preferences** panel can then be defined in `contributions.preferences`. |
| 43 | + |
| 44 | +For details on how to define a `profile`, please review the [Profile](./profile.md) documentation. |
| 45 | + |
| 46 | +## Registering Preferences Data |
| 47 | + |
| 48 | +`package.json` |
| 49 | + |
| 50 | +```JSON5 |
| 51 | +{ |
| 52 | + "name": "hello-world", |
| 53 | + "contributions": { |
| 54 | + "profile": { |
| 55 | + "editor": { |
| 56 | + "foo": { |
| 57 | + "default": 0, |
| 58 | + "label": "foo" |
| 59 | + }, |
| 60 | + "bar": { |
| 61 | + "default": false, |
| 62 | + "label": "bar" |
| 63 | + } |
| 64 | + } |
| 65 | + }, |
| 66 | + "preferences": { |
| 67 | + "properties": { |
| 68 | + "foo": { |
| 69 | + "ui": "ui-num-input" |
| 70 | + } |
| 71 | + }, |
| 72 | + "laboratory": ["bar"] |
| 73 | + } |
| 74 | + } |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +Two editor configurations, `foo` and `bar`, have been defined and added the configurations to the `preferences`. |
| 79 | +- The `foo` is stored in the general profile. |
| 80 | +- The `bar` is stored in the `laboratory` profile. |
| 81 | + |
| 82 | +The defined `profile` data will be automatically registered to `default`. Using `Editor.Profile.getConfig` will get the default values. |
| 83 | + |
| 84 | +The `contributions` of `package.json` need to be defined like the following: |
| 85 | + |
| 86 | +```typescript |
| 87 | +interface package |
| 88 | +{ |
| 89 | + "name": string; |
| 90 | + "contributions": { |
| 91 | + "profile": { |
| 92 | + "editor": { |
| 93 | + [key:string]: ProfileItem; |
| 94 | + }; |
| 95 | + }; |
| 96 | + "preferences": { |
| 97 | + /** |
| 98 | + * The properties data can be filled in to auto-render the configuration. |
| 99 | + * The key in properties corresponds to the editor configuration key, and the value corresponds to the information needed for auto-rendering. |
| 100 | + * If there is a ui defined in properties then it will be automatically rendered under the tab of the functional extension name. |
| 101 | + **/ |
| 102 | + "properties": { |
| 103 | + [key:string]: UIInfo |
| 104 | + }; |
| 105 | + /** |
| 106 | + * If the configuration is more complex and auto-rendering can't meet the demand, you can fill in custom data. |
| 107 | + * Fill in the entry for the custom panel there. |
| 108 | + * The panel will appear below the autorender (if properties are defined). |
| 109 | + **/ |
| 110 | + "custom": string; |
| 111 | + /** |
| 112 | + * The labs are listed as a separate tab within the editor, mainly to provide a switch display for some experimental functions. |
| 113 | + * You can fill in laboratory data to add an editor configuration of type Boolean to the lab switches. |
| 114 | + * Laboratory is an array, the key in the array points to the key in the editor configuration, the corresponding data must be of Boolean type. |
| 115 | + * The key filled in here will be displayed in the Lab tab of Preferences. |
| 116 | + **/ |
| 117 | + "laboratory": string[]; |
| 118 | + }; |
| 119 | + ... |
| 120 | + } |
| 121 | + ... |
| 122 | +} |
| 123 | +``` |
| 124 | + |
| 125 | +```typescript |
| 126 | +interface UIInfo { |
| 127 | + // which ui element to use for rendering, e.g. "ui-num-input" |
| 128 | + ui: string; |
| 129 | + attributes: { |
| 130 | + // The attribute data allowed on the ui element, each ui allows different parameters, see the ui-kit chapter for details |
| 131 | + // Assuming the ui is "ui-num-input" |
| 132 | + // This can be filled with "step": 1 |
| 133 | + [key:string]: any; |
| 134 | + }; |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +For more information on how to customize the panel please review the [Panel Definition](./panel.md) documentation. |
0 commit comments