SerializedObject

描述

SerializedObject 和 SerializedProperty 两个类能够以完全通用的方式编辑 Unity 对象上的可序列化字段。这些类可自动处理个别序列化字段的脏化，以便 Undo 系统处理这些字段，并在检视面板中绘制时针对预制件重载正确设置这些字段的样式。

在许多情况下，您可以创建工具来修改项目中的对象。例如，以下脚本示例可创建一个菜单项，该菜单项用于重置当前选定的所有游戏对象的本地位置。将其放在名为 Example1.cs 的文件中，然后将文件放在名为 Editor 的文件夹中：

using UnityEditor;
using UnityEngine;

static class Example1
{
    [MenuItem("Edit/Reset Selected Objects Position (No Undo)")]
    static void ResetPosition()
    {
        // this action will not be undoable
        foreach (var go in Selection.gameObjects)
            go.transform.localPosition = Vector3.zero;
    }
}

虽然您可以从对象的 API 角度通过这种方式来编辑对象，但您还必须使用其他编辑器 API 来指定哪些组件已脏化，以便此操作可以撤消，并在下次保存场景时此操作被检测为更改，诸如此类。相反，使用 SerializedObject 会自动处理此过程。以下脚本示例与前一个示例效果相同，但也可以撤消，并作为场景中的更改进行跟踪。将其放在名为 Example2.cs 的文件中，然后将文件放在名为 Editor 的文件夹中：

using System.Linq;
using UnityEditor;
using UnityEngine;

static class Example2
{
    [MenuItem("Edit/Reset Selected Objects Position")]
    static void ResetPosition()
    {
        var transforms = Selection.gameObjects.Select(go => go.transform).ToArray();
        var so = new SerializedObject(transforms);
        // you can Shift+Right Click on property names in the Inspector to see their paths
        so.FindProperty("m_LocalPosition").vector3Value = Vector3.zero;
        so.ApplyModifiedProperties();
    }
}

SerializedObject 一次可打开一个或多个目标 Unity 对象的数据流，这允许您同时编辑对象共享的序列化数据。例如，如果您的数据流中有多个不同类型的行为，则这些行为的唯一共同属性可能是“m_Enabled”。

首次创建 SerializedObject 实例后，实例是最新的。对于在此数据流中访问的 SerializedProperty 进行的任何更改，必须最终通过 SerializedObject.ApplyModifiedProperties 方法来刷新。如果在多个帧中保留对 SerializedObject 实例的引用，则必须确保首先手动调用其 SerializedObject.Update 方法，然后再从此实例中读取任何数据，因为一个或多个目标对象可能已在其他位置修改过，例如在单独的 SerializedObject 流中。请注意，具有相同目标对象的两个不同的 SerializedObject 流彼此独立，如果在几个帧的过程中保持其中一个或多个流，则必须以这种方式手动同步这些流。

SerializedObject 和 SerializedProperty 两个类的最常见用法是在创建自定义编辑器时使用，在此情况下，建议的方法是使用 SerializedObject，而不是直接修改所检查的目标对象。

以下示例脚本定义的组件将使用正弦函数为对象的本地位置生成动画。将其放入名为 SineAnimation.cs 的脚本中：

using UnityEngine;

public class SineAnimation : MonoBehaviour
{
    public Vector3 axis { get { return m_Axis; } set { m_Axis = value; } }
    [SerializeField]
    private Vector3 m_Axis = Vector3.up;

    public float period { get { return m_Period; } set { m_Period = value; } }
    [SerializeField]
    private float m_Period = 1f / Mathf.PI;

    public float amplitude { get { return m_Amplitude; } set { m_Amplitude = value; } }
    [SerializeField]
    private float m_Amplitude = 1f;

    public float phaseShift { get { return m_PhaseShift; } set { m_PhaseShift = Mathf.Clamp01(value); } }
    [SerializeField, Range(0f, 1f)]
    private float m_PhaseShift;

    void Update()
    {
        transform.localPosition = m_Axis * m_Amplitude * Mathf.Sin((Time.time + m_PhaseShift) / m_Period);
    }

    void OnValidate()
    {
        m_PhaseShift = Mathf.Clamp01(m_PhaseShift);
    }
}

以下示例脚本为 SineAnimation 定义了一个自定义 Editor，用于在默认控件之后添加一个按钮来随机化正弦函数参数。将其放在名为 SineAnimationEditor.cs 的文件中，然后将文件放在名为 Editor 的文件夹中：

using UnityEditor;
using UnityEngine;

[CustomEditor(typeof(SineAnimation)), CanEditMultipleObjects]
public class SineAnimationEditor : Editor
{
    public override void OnInspectorGUI()
    {
        base.OnInspectorGUI();
        if (GUILayout.Button("Randomize Sine Function", EditorStyles.miniButton))
        {
            serializedObject.FindProperty("m_Period").floatValue = Random.Range(0f, 10f);
            serializedObject.FindProperty("m_Amplitude").floatValue = Random.Range(0f, 10f);
            serializedObject.FindProperty("m_PhaseShift").floatValue = Random.Range(0f, 1f);
            serializedObject.ApplyModifiedProperties();
        }
    }
}

Editor 类有一个 serializedObject 属性，该属性为所有被检查目标（在本例中为 SineAnimation 组件）提供了一个流，从而更轻松地支持同时编辑多个对象。由于此 SerializedObject 实例在 Editor 实例的生命周期内持续存在，因此 OnInspectorGUI 的基本实现在绘制任何控件之前处理 Update 调用，并在任何用户交互之后处理调用 ApplyModifiedProperties 的调用。因此，在方法退出前，必须通过 ApplyModifiedProperties 来刷新按下此检视面板中添加的按钮时进行的所有修改，否则下次 Editor.OnInspectorGUI 的基本实现在 serializedObject 实例上调用 SerializedObject.Update 方法时，这些修改将丢失。

请注意，如果通过 SerializedObject.ApplyModifiedProperties 将数据刷新到 Unity 对象，那么将忽略您在与序列化字段关联的属性 setter 中可能具有的任何数据验证逻辑。在此示例中，“m_PhaseShift”字段的值在 phaseShift 属性 setter 和 UI 中被钳制在 0 到 1 之间（通过 RangeAttribute）。因为用户可以通过 SerializedProperty（以及通过编辑磁盘上的资源）访问“m_PhaseShift”，而不仅仅通过“phaseShift”API 或 UI，所以有必要在 MonoBehaviour.OnValidate 回调中将其钳制为有效范围，从而在加载 Unity 对象时清理数据。

另请注意，虽然 SerializedObject 设计为可处理多个目标，但 SerializedProperty 类（例如，floatValue、vector3Value）中的值 getter 属性对于多选操作并不友好。因此，如果为这些属性分配一个值，将影响所有目标，但如果从这些属性中读取一个值，则仅返回与列表中第一个目标关联的值。

另请参阅：SerializedProperty、SerializeField、Editor、MonoBehaviour.OnValidate、hasMultipleDifferentValues。

变量

构造函数

公共函数