API Host TypedDocumentOptions

TypedDocumentOptions

TDoc serialization options

命名空间：AuroraScript.Runtime.Serialization。类型：sealed record。适用版本：4.0.0。

Namespace: AuroraScript.Runtime.Serialization. Kind: sealed record. Applies to 4.0.0.

.NET Host API 目录 · TDoc 格式

.NET Host API Directory · TDoc Format

介绍

Introduction

TypedDocumentOptions 控制 TDoc 的格式、类型名输出和最大嵌套深度。它是不可变 record；使用对象初始化器创建，或使用 with 从已有选项派生。

TypedDocumentOptions controls TDoc formatting, type-name emission, and maximum nesting depth. It is an immutable record; create it with an object initializer or derive it from existing options using with.

快速开始

Quick Start

var options = new TypedDocumentOptions
{
    Indented = false,
    EmitTypeNames = true,
    MaxDepth = 64,
};

var text = TypedDocumentSerializer.Serialize(engine, value, options);

成员

Members

static readonly TypedDocumentOptions Default

默认选项。其 Indented 为 true，EmitTypeNames 为 false，MaxDepth 为 128。

Default options. Its Indented is true, EmitTypeNames is false, and MaxDepth is 128.

Parameters:

• 无。

  None.

Returns

默认 TypedDocumentOptions 实例。

Default TypedDocumentOptions instance.

简单示例

Simple Example

var text = TypedDocumentSerializer.Serialize(engine, value, TypedDocumentOptions.Default);

bool Indented

控制输出格式。默认 true，使用四个空格的缩进、换行与尾逗号；为 false 时输出不含空白格式化的紧凑文本。

Controls output formatting. It defaults to true, using four-space indentation, newlines, and trailing commas; false produces compact text without formatting whitespace.

该选项不改变字符串值。字符串内原本存在的回车、换行或换页字符始终写为 \r、\n、\f 转义，以便读取后精确恢复原值；它们不是紧凑格式产生的物理换行。

This option does not alter string values. Carriage return, line feed, and form-feed characters originally inside a string are always written as \r, \n, and \f escapes so reading restores the exact value; they are not physical line breaks introduced by compact formatting.

Parameters:

• 无。

  None.

Returns

是否输出缩进文本。

Whether indented text is emitted.

简单示例

Simple Example

var options = new TypedDocumentOptions { Indented = false };
var text = TypedDocumentSerializer.Serialize(engine, ScriptDatum.FromNumber(42), options);
// 42

bool EmitTypeNames

控制是否在每个有类型的值前输出类型名。默认 false：仅输出无法由原始字面量唯一推断的类型名。

Controls whether a type name is written before each typed value. It defaults to false, emitting only type names that cannot be uniquely inferred from raw literals.

设为 true 时强制输出所有可用类型名。无论此值为何，StringBuffer、Date、Regex、Path、HashMap、全部 Packed Array 和已注册 CLR/CIL 类型都必须输出类型名，因为原始形状不能唯一确定其类型。

When set to true, it forces every available type name. Regardless of this value, StringBuffer, Date, Regex, Path, HashMap, every packed array, and registered CLR/CIL type must emit a type name because their raw shapes do not uniquely determine the type.

Parameters:

• 无。

  None.

Returns

是否输出所有可用类型名。

Whether all available type names are emitted.

简单示例

Simple Example

var options = new TypedDocumentOptions
{
    Indented = false,
    EmitTypeNames = true,
};

var text = TypedDocumentSerializer.Serialize(engine, ScriptDatum.FromString("Aurora"), options);
// String "Aurora"

int MaxDepth

限制读取和写入的嵌套值深度。默认 128，必须大于零；小于或等于零会在操作开始前抛出 ArgumentOutOfRangeException。

Limits nested value depth for both reading and writing. It defaults to 128 and must be greater than zero; zero or a negative value throws ArgumentOutOfRangeException before the operation begins.

Parameters:

• 无。

  None.

Returns

允许的最大嵌套值深度。

Maximum permitted nested-value depth.

简单示例

Simple Example

var options = new TypedDocumentOptions { MaxDepth = 32 };
var value = TypedDocumentSerializer.Deserialize(engine, "Array [1, 2]", options);

选择建议

Selection Guidance

场景	建议选项
人工维护的配置	默认值
网络或缓存中的紧凑文本	Indented = false
评审、差异比较或显式数据契约	EmitTypeNames = true
面向不可信或过深输入	设置较小、符合业务的 MaxDepth

Use defaults for human-maintained configuration, Indented = false for compact cache or wire text, EmitTypeNames = true for review, diffs, or explicit data contracts, and set a business-appropriate smaller MaxDepth for untrusted or deeply nested input.

相关 API

Related APIs

• TypedDocumentSerializer

  TypedDocumentSerializer

• AuroraTypedDocument

  AuroraTypedDocument

• TDoc 格式

  TDoc Format