更新 '频谱样式开发教程'

%E9%A2%91%E8%B0%B1%E6%A0%B7%E5%BC%8F%E5%BC%80%E5%8F%91%E6%95%99%E7%A8%8B.md

@@ -1,7 +1,7 @@
 # 频谱样式开发
 
-上面介绍了ADV-Plugin的一些配置项，现在我们将从零开始一个完整的第三方Style开发的项目。
-第三方的Style是SAO Utils 2中的一个插件形式存在，ADV-Plugin会自动识别`catalog`为`top.mashiros.advp-style`的Style插件。
+上面介绍了ADV-Plugin的一些配置项，现在我们将从零开始开发一个完整的第三方频谱样式项目。
+第三方的频谱样式是SAO Utils 2中的一个插件形式存在，ADV-Plugin会识别`catalog`为`top.mashiros.advp-style`的频谱样式插件并加入样式选项列表中。
 
 ## 目录结构
 
@@ -9,36 +9,41 @@
 
 ```powershell
 top.mashiros.3rd-party-style-demo.advp
- ├── demo1				 (示例文件夹)
- │   └── Style.qml		 (必须)
- ├── demo2				 (示例文件夹)
- │   ├── Config.qml		 (可选)
- │   └── Style.qml		 (必须)
- └── package.json		 (必须)
+ ├── Demo1.qml
+ ├── Demo2.qml
+ └── package.json
 ```
 
-* `package.json`：<font color='red'>必须</font>，SAO Utils 2的插件定义文件
-* `Style.qml`：<font color='red'>必须</font>，Style插件入口文件
-* `Config.qml`：可选，为Style插件定义配置项
+其中`package.json`为SAO Utils 2的插件声明文件，`Demo1.qml`为Demo1的样式文件，`Demo2.qml`为Demo2的样式文件。
 
 ## 开发接口(API)
 
-ADV-Plugin提供了`StyleAPI`组件与`CfgAPI`组件作为接口使用。
-
-* `StyleAPI`：Canvas组件的封装。下面为一些常用的属性与函数。
-  * `width`：只读，画布的宽度，也为插件的显示宽度。
-  * `height`：只读，画布的长度，也为插件的显示长度。
-  * `context`：只读，Canvas的2D上下文。
-  * `configs`：只读，若此Style的路径下有*Config.qml*，则其值为`CfgAPI`的设置值(JSON格式)；否则为`undefined`。
-  * `onAudioDataUpdeted`：可写，数据更新时的处理代码，带有一个长度为129数组参数：`data`。前64个数据为左声道FFT数据，后64个数据为右声道FFT数据，每一个声道的FFT数据位从低到高对应频谱频率的由低到高。最后一个数据为动态归一化的峰值数据（自动归一化时，第i个频谱数据大小 = data[i] / data[128]）。
-  * `onConfigsUpdated`：可写，属性`configs`或者`context`改变时的处理代码，函数无参数。
-  * `requestPaint`：函数，调用此函数使Canvas绘制图形。
-* `CfgAPI`：NERvGear.Preferences.DialogPreference的封装，插件设置项的API，支持NERvGear.Preferences中的各种Preference样式。
-  * `version`：可写，版本号，默认为`""`。防止选项更改后加载历史选项值导致的插件错误，版本号更新后会自动加载最新选项的默认值。可在选项列表的最上方查看到`version`值，若为空则不显示。
-  * `cfg_height`：可写，设置页面的高度，默认为580。
-
-更多属性与方法可参考QML中的canvas组件，细节可参考demo与SAO Utils 2的官方开发说明。
+ADV-Plugin的插件接口Qml文件一般使用QtObject，其必须包括`style`(`Component`类型)、`preference`(`Component`类型)与`defaultValues`(`var`类型)这3个属性，可直接使用`top.mashiros.widget.advp/qml/api`路径下的`AdvpStyleTemplate.qml`组件。
+### `style`属性
+`AdvpStyleTemplate`的`style`属性为`Component`类型，为显示在挂件中的组件。一般可使用`top.mashiros.widget.advp/qml/api`路径下的`AdvpCanvasTemplate.qml`组件，其为`Canvas`组件的封装。下面为它的一些常用的属性与函数。
+- `width`：只读，画布的宽度，也为插件的显示宽度。
+- `height`：只读，画布的长度，也为插件的显示长度。
+- `context`：只读，Canvas的2D上下文。
+- `configs`：只读，若此样式包含配置项，则其值为`preference`组件所保存的设置值(JSON格式)；否则为`undefined`。
+- `onAudioDataUpdeted`：可写，数据更新时的处理代码，带有一个长度为129数组参数：`data`。前64个数据为左声道FFT数据，后64个数据为右声道FFT数据，每一个声道的FFT数据位从低到高对应频谱频率的由低到高。最后一个数据为动态归一化的峰值数据（自动归一化时，第i个频谱数据大小 = `data[i]/data[128]`）。
+- `onConfigsUpdated`：可写，属性`configs`或者`context`改变时的处理代码，函数无参数。
+- `requestPaint`：函数，调用此函数使Canvas绘制图形。
+### `preference`属性
+`AdvpStyleTemplate`的`preference`属性也为`Component`类型，为样式的可配置选项。推荐使用`top.mashiros.widget.advp/qml/api`路径下的`AdvpPreference.qml`组件，其为`NERvGear.Preferences.PreferenceGroup`的封装，支持NERvGear.Preferences中的各种Preference组件。其中的`AdvpPreference`组件的`version`属性为版本号，默认为空字符串`""`。可在选项列表的最上方查看到`version`值，若为空则不显示。
+为防止选项更新后导致插件错误，同时尽可能保留用户设置，版本号更新后会自动将历史挂件设置值与现有版本的选项默认值合并更新，效果参考`Object.assign`操作，且支持嵌套的一级子对象的更新操作，如：
+```javascript
+更新前设置值：
+{"demo":{"data1":1}}
+更新选项的默认值：
+{"demo":{"data1":2,"data2":3}}
+更新后的设置值：
+{"demo":{"data1":1,"data2":3}}
+```
+**注意：旧设置会覆盖新设置，并添加新增设置，尽量避免更改旧设置的数据类型以免造成插件错误，尽量避免使用两级以上的对象嵌套，如`{"demo":{"demo1":{"data":0}}}`。**
+### `defaultValues`属性
+`AdvpStyleTemplate`的`defaultValues`属性为`var`类型，其主要是`preference`配置项的值，为`Object`。因为插件默认配置为`defaultValues`的配置，所以`preference`组件中的默认值推荐使用`defaultValues`中的值。
 
+更多属性与方法可参考QML中的canvas组件，细节可参考下面的demo与SAO Utils 2的官方开发说明。
 demo1与demo2的示例教程见对应的wiki页面：<br>
 [demo1](https://nvg.dev/Mashiro_Sorata/ADV-Plugin/wiki/demo1)<br>
-[demo2](https://nvg.dev/Mashiro_Sorata/ADV-Plugin/wiki/demo2)
+[demo2](https://nvg.dev/Mashiro_Sorata/ADV-Plugin/wiki/demo2)<br>