[Roblox] 中文API 翻译 | Classes

本文链接：https://blog.csdn.net/weixin_50340398/article/details/141820961

[Roblox] 中文API 翻译 | Classes | Instance

写在前面的话
Roblox Engine Classes

写在前面的话

roblox 更新了新的API文档，去除了原本中文版本开发文档，虽然全英文阅读API是每个程序员的基础技能，但是为了提高自己学习引擎效率（第一次接触编程学习），我抽时间翻译了全篇roblox API开发文档，并且使用中英文对照翻译的方式，加深学习。文档仅供学习参考，roblox官方经常更新文档API以及增删功能，如有错误，还请指正

翻译文章顺序基于我学习API的顺序展开，可能会优先翻译核心的API，比如对象创建，事件处理等等，API顺序依照官网顺序排列
roblox脚本基于Lua 翻译时间 2024.9.2

Roblox Engine Classes

类表示 Roblox 引擎中的核心对象和服务。它们包含属性、方法、事件和回调

Instance 实例对象

Not Creatable 不可创建 您不能使用 Instance.new 构造函数创建此类的实例。
Not Browsable 不可浏览 此成员不会显示在 Roblox Studio 的对象浏览器中。

定义

Instance is the base class for all classes in the Roblox class hierarchy. Every other class that the Roblox engine defines inherits all of the members of Instance. It is not possible to directly create Instance objects.

Instance 是 Roblox 类层次结构中所有类的基类。Roblox引擎定义的所有其他类都继承 Instance 的所有成员。但是无法直接创建 Instance 对象。

Instance has a special function called Instance.new() which is used to create objects via code. This function takes the name of the class as a parameter and returns the created object. Abstract classes and services cannot be created with the Instance.new function.
Instance 有一个名为 Instance.new() 的特殊函数，用于通过代码创建对象。此函数将类的名称作为参数，返回值是创建的对象实例。抽象类和服务不能使用 Instance.new 函数创建。

Instance.new（）使用：

local newPart = Instance.new("Part")  -- 创建一个新的 Part 对象
newPart.Name = "MyNewPart"           -- 设置对象的名称
newPart.Parent = workspace           -- 将对象添加到场景中

抽象类：不能通过 Instance.new() 创建抽象类的实例。抽象类是那些只用作其他类的基础的类，而不能直接实例化。例如，GuiBase 是一个抽象类，你不能直接创建它的实例。
服务（Services）：同样地，不能通过 Instance.new() 创建服务（如 Players、Lighting 等），因为这些服务已经由引擎自动管理。你可以通过 game:GetService(“ServiceName”) 方法访问这些服务。

总结 Summary

Properties 属性

属性名称	数据类型	可读性	备注
Archivable	bool	读取并行	确定是否可以使用 Instance:Clone() 克隆实例及其后代，以及是否可以保存/发布
Capabilities	SecurityCapabilities	读取并行 Roblox 脚本安全¹	-
ClassName	string	只读未复制读取并行	表示此Instance实例所属的类的只读字符串
Name	string	读取并行	实例的非唯一标识符
Parent	Instance	未复制读取并行	确定实例的分层父级
RobloxLocked	bool	隐藏读取并行插件安全² 荒废的³	用于保护 CoreGui 对象的已弃用属性
Sandboxed	bool	未复制读取并行Roblox 脚本安全	-
className	string	未复制不可编写脚本⁴ 读取并行 Roblox 安全	-

Methods 方法

方法名称	参数	返回值	备注	可读性
`AddTag(tag : string)`	tag : string	void	为实例应用一个标签。	Write Parallel
`ClearAllChildren()`	-	void	销毁实例的所有子对象。	Write Parallel
`Clone()`	-	Instance	创建一个实例及其所有后代的副本，忽略不具备 Archivable 属性的实例。	Write Parallel
`Destroy()`	-	void	将 Instance.Parent 属性设置为 nil，锁定 Instance.Parent 属性，断开所有连接，并对所有子对象调用 Destroy。	Write Parallel
`FindFirstAncestor(name : string)`	name : string	Instance	返回实例的第一个祖先，其 Instance.Name 等于给定名称。	Write Parallel
`FindFirstAncestorOfClass(className : string)`	className : string	Instance	返回实例的第一个祖先，其 Instance.ClassName 等于给定的 className。	Write Parallel
`FindFirstAncestorWhichIsA(className : string)`	className : string	Instance	返回实例的第一个祖先，对于该实例，Instance:IsA() 对给定的 className 返回 true。	Write Parallel
`FindFirstChild(name : string, recursive : bool)`	name : string, recursive : bool	Instance	返回实例中使用给定名称找到的第一个子对象。	Write Parallel
`FindFirstChildOfClass(className : string)`	className : string	Instance	返回实例中 ClassName 等于给定 className 的第一个子对象。	Write Parallel
`FindFirstChildWhichIsA(className : string, recursive : bool)`	className : string, recursive : bool	Instance	返回实例中，对于该实例，Instance:IsA() 对给定的 className 返回 true 的第一个子对象。	Write Parallel
`FindFirstDescendant(name : string)`	name : string	Instance	返回找到的第一个名称为给定 Instance.Name 的后代。	Write Parallel
`GetActor()`	-	Actor	返回与实例关联的 Actor（如果有）。	Write Parallel
`GetAttribute(attribute : string)`	attribute : string	Variant	返回已分配给给定属性名称的值。	Write Parallel
`GetAttributeChangedSignal(attribute : string)`	attribute : string	RBXScriptSignal	返回一个事件，当给定属性更改时触发。	Write Parallel
`GetAttributes()`	-	Dictionary	返回实例属性的字典。	Write Parallel
`GetChildren()`	-	Objects	返回包含实例所有子对象的数组。	Write Parallel
`GetDebugId(scopeLength : number)`	scopeLength : number	string	返回内部使用的调试 ID 的编码字符串。	Not Browsable, Plugin Security
`GetDescendants()`	-	Array	返回包含实例所有后代的数组。	Write Parallel
`GetFullName()`	-	string	返回描述实例祖先的字符串。	Write Parallel
`GetPropertyChangedSignal(property : string)`	property : string	RBXScriptSignal	获取当实例的给定属性更改时触发的事件。	Write Parallel
`GetTags()`	-	Array	获取应用于实例的所有标签的数组。	Write Parallel
`HasTag(tag : string)`	tag : string	bool	检查实例是否具有给定的标签。	Write Parallel
`IsA(className : string)`	className : string	bool	如果实例的类与给定的类匹配或继承自给定类，则返回 true。	Write Parallel
`IsAncestorOf(descendant : Instance)`	descendant : Instance	bool	如果实例是给定后代的祖先，则返回 true。	Write Parallel
`IsDescendantOf(ancestor : Instance)`	ancestor : Instance	bool	如果实例是给定祖先的后代，则返回 true。	Write Parallel
`Remove()`	-	void	已弃用。将对象的 Parent 设置为 nil，并对其所有后代执行相同操作。	Write Parallel
`RemoveTag(tag : string)`	tag : string	void	从实例中移除一个标签。	Write Parallel
`SetAttribute(attribute : string, value : Variant)`	attribute : string, value : Variant	void	设置具有给定名称的属性为给定值。	Write Parallel
`WaitForChild(childName : string, timeOut : number)`	childName : string, timeOut : number	Instance	可挂起。返回具有给定名称的实例子对象。如果子对象不存在，它将挂起当前线程直到找到该对象。	Write Parallel
`children()`	-	Objects	已弃用。返回对象的子对象数组。	Write Parallel
`clone()`	-	Instance	已弃用。	Write Parallel
`destroy()`	-	void	已弃用。	Write Parallel
`findFirstChild(name : string, recursive : bool)`	name : string, recursive : bool	Instance	已弃用。	Write Parallel
`getChildren()`	-	Objects	已弃用。	Write Parallel
`isA(className : string)`	className : string	bool	已弃用。	Write Parallel
`isDescendantOf(ancestor : Instance)`	ancestor : Instance	bool	已弃用。	Write Parallel
`remove()`	-	void	已弃用。	Write Parallel

Events 事件

事件名称	参数	返回值	备注	可读性
`AncestryChanged(child : Instance, parent : Instance)`	child : Instance, parent : Instance	RBXScriptSignal	当对象或其祖先的 Instance.Parent 属性发生更改时触发。	Write Parallel
`AttributeChanged(attribute : string)`	attribute : string	RBXScriptSignal	当实例上的属性发生更改时触发。	Write Parallel
`Changed(property : string)`	property : string	RBXScriptSignal	在实例的属性更改后立即触发，但有一些限制。	Write Parallel
`ChildAdded(child : Instance)`	child : Instance	RBXScriptSignal	在一个对象被设为该实例的子对象后触发。	Write Parallel
`ChildRemoved(child : Instance)`	child : Instance	RBXScriptSignal	在一个子对象从该实例中移除后触发。	Write Parallel
`DescendantAdded(descendant : Instance)`	descendant : Instance	RBXScriptSignal	在一个后代被添加到该实例后触发。	Write Parallel
`DescendantRemoving(descendant : Instance)`	descendant : Instance	RBXScriptSignal	在该实例的一个后代被移除之前立即触发。	Write Parallel
`Destroying()`	-	RBXScriptSignal	在实例通过 Instance:Destroy() 被销毁之前立即触发。	Write Parallel
`childAdded(child : Instance)`	child : Instance	RBXScriptSignal	已弃用。	Write Parallel

Properties 属性

Archivable

bool
Read Parallel

此属性决定了实例是否应该在体验发布或保存时包含，或者在对某个实例的祖先调用 Clone() 时被包含。如果直接对一个实例调用 Clone()，如果该实例Archivable属性为false，将返回 nil。

在 Studio 中使用“重复”或“复制/粘贴”选项复制对象时，将忽略其自身的 Archivable 属性，并将复制品的 Archivable 属性设置为 true。

local part = Instance.new("Part")  -- 创建一个新的 Part 对象
print(part:Clone())  -- 输出 Part（表示成功克隆了 Part 对象）
part.Archivable = false  -- 将 Part 对象的 Archivable 属性设置为 false
print(part:Clone())  -- 输出 nil（表示由于 Archivable 为 false，克隆操作失败）

Capabilities

SecurityCapabilities
Read ParallelRoblox Script Security

ClassName

string
Read Only, Not Replicated, Read Parallel

此属性是一个只读的字符串，表示该实例所属的类。

该属性可以与 Instance 的其他函数一起使用，这些函数用于通过类型识别对象，例如 Instance:IsA() 或 Instance:FindFirstChildOfClass()。

注意，这个属性是只读的，不能通过脚本进行修改。开发者如果希望更改实例的类，必须创建一个新的实例。

与 Instance:IsA() 不同，ClassName 可以用来检查一个对象是否属于特定类，而忽略类的继承。例如：

for _, child in workspace:GetChildren() do
    if child.ClassName == "Part" then
        print("Found a Part")
        -- 只会找到模型中的 Part，而不会找到 TrussParts、WedgeParts 等
    end
end

Name

string
Read Parallel

此属性是实例的非唯一标识符。

这个属性是描述对象的标识符。名字不一定是唯一的标识符；一个对象的多个子对象可能共享相同的名字。名字用于保持对象层次结构的组织，同时允许脚本访问特定的对象。实例的名字不能超过 100 个字符。

对象的名字通常用于通过数据模型层次结构访问对象，使用以下方法：

local baseplate = workspace.Baseplate
local baseplate = workspace["Baseplate"]
local baseplate = workspace:FindFirstChild("BasePlate")

为了使对象可以使用点操作符访问，对象的名字必须遵循特定的语法。对象的名字必须以下划线或字母开头，其余部分只能包含字母、数字或下划线（不能包含其他特殊字符）。如果对象的名字不符合此语法，则不能使用点操作符访问，Lua 也不会将其名字解释为标识符。

如果有多个具有相同名字的对象作为兄弟节点，则任何尝试通过该名字索引对象的操作都会返回找到的唯一一个对象，类似于 Instance:FindFirstChild()，但不一定是所需的对象。如果需要通过代码访问特定对象，建议为其指定唯一的名字，或确保没有兄弟对象与其共享相同的名字。

注意，可以使用 Instance:GetFullName() 获取显示实例层次结构的完整名字。

Parent

Instance
Not Replicated, Read Parallel

此属性决定了实例的层级父对象。以下术语在讨论如何设置此属性时常常使用：

当一个对象的 Parent 设置为另一个对象时，该对象就是另一个对象的子对象（被设置为其父对象）。
实例的后代是该对象的子对象，加上子对象的所有后代。
实例的祖先是所有实例的上级对象。

许多其他 API 成员的名称来自此属性，例如 GetChildren 和 FindFirstChild。

Remove 函数将此属性设置为 nil。调用 Destroy 将把实例及其所有后代的 Parent 设置为 nil，并且锁定 Parent 属性。设置已销毁对象的 Parent 会引发错误。

此属性也用于管理对象是否存在于游戏中或需要被移除。只要对象的父对象在数据模型中，或者对象存储在变量中，或由其他对象的属性引用，则该对象将保留在游戏中。否则，对象将自动被移除。顶级数据模型对象（脚本中称为游戏的对象）没有父对象，但游戏引擎始终保持对它的引用，并在会话期间存在。

使用 Instance.new() 创建的新对象将没有父对象，通常在设置父对象之前不会可见或发挥作用。创建对象的最基本步骤是：创建对象，然后设置其父对象。

-- 创建一个 Part 并将其设置为 workspace 的子对象
local part = Instance.new("Part")
part.Parent = workspace
-- Instance.new 也可以接受 Parent 作为第二个参数
Instance.new("NumberValue", workspace)

当在实例在数据模型中时对某些属性进行更改时，引擎可能需要在内部执行额外的工作（例如复制、渲染和 GUI 布局）。尽可能在设置实例的 Parent 之前更改实例的属性，而不是之后，以避免重复执行这些工作。

Object Replication

服务器创建的对象不会在被设置为某个已复制对象的子对象之前复制到客户端。当创建一个对象并设置许多属性时，建议最后设置 Parent。这确保了对象只复制一次，而不是复制多次属性更改。

local part = Instance.new("Part") -- 避免在这里使用第二个参数
part.Anchored = true
part.BrickColor = BrickColor.new("Really red")
-- 这里可能还有许多其他属性更改...
-- 始终最后设置 Parent！
part.Parent = workspace