Tabelas | Documentação - Central de Criadores Roblox

O tipo de dado tabela pode armazenar múltiplos valores de qualquer tipo que não seja nil, incluindo booleanos, números, strings, funções e outras tabelas. Construa tabelas com chaves ():


-- Construa uma tabela vazia atribuída à variável "t"
local t = {}
print(t) -- {}

Você pode usar uma tabela como um array ou um dicionário. Arrays usam uma lista ordenada de números como índices, mas dicionários podem ter números, strings e objetos como índices.

Para mais informações sobre funções internas para trabalhar com tabelas, veja a biblioteca table.

Arrays

Um array é uma lista ordenada de valores. Arrays são úteis para armazenar coleções de dados, como um grupo de jogadores com permissões especiais.

Criar arrays

Para criar um array usando uma tabela Luau, declare os valores em ordem sequencial, separados por vírgulas.


-- Construa um array com três itens
local testArray = {"Uma string", 3.14159, true}
print(testArray)

Ler de arrays

Para ler de um array, adicione um par de colchetes após sua referência e especifique o número do índice do elemento dentro ([pos]):


-- Construa um array com três itens
local testArray = {"Uma string", 3.14159, true}

print(testArray[1]) -- Uma string
print(testArray[2]) -- 3.14159
print(testArray[3]) -- true

Ao contrário de algumas linguagens, Luau usa indexação baseada em 1 para arrays, então o primeiro item no array é [1], não [0].

Escrever em arrays

Para definir ou reescrever o valor de um array em um índice, declare o número do índice entre colchetes ([index]) seguido de = e o valor:


local testArray = {"Uma string", 3.14159, true}

testArray[2] = 12345
testArray[4] = "Nova string"

print(testArray[2]) -- 12345
print(testArray[4]) -- Nova string

Iterar sobre arrays

Para iterar sobre um array, você pode usar um loop for. Como os arrays têm índices numéricos, você também pode usar um loop for numérico de 1 até o comprimento do array (#array).


local testArray = {"Uma string", 3.14159, true, "Nova string"}

-- Loop usando iteração geral
for index, value in testArray do
	print(index, value)
end

-- Iterar usando o operador de comprimento do array (#)
for index = 1, #testArray do
	print(index, testArray[index])
end

Inserir itens

Existem duas maneiras internas de inserir um item ao final de um array:

Passar uma referência para o array e o valor do item para a função table.insert() de Luau.
Adicionar o novo item ao array usando a sintaxe array[#array+1].


local testArray = {"Uma string", 3.14159}

table.insert(testArray, "Nova string")
testArray[#testArray+1] = "Outra nova string"

print(testArray[3]) -- Nova string
print(testArray[4]) -- Outra nova string

Para inserir um item entre o início e o fim de um array, inclua um valor de posição como o segundo argumento de table.insert(). Isso insere o novo item e empurra os itens seguintes para cima uma posição de índice.


local testArray = {"Primeiro item", "Próximo item"}

table.insert(testArray, 2, "NOVO ITEM #2")

print(testArray[1]) -- Primeiro item
print(testArray[2]) -- NOVO ITEM #2
print(testArray[3]) -- Próximo item

Remover itens

Para remover um item de um array, use table.remove(). Isso remove o item na posição especificada e move quaisquer itens seguintes de volta uma posição de índice.


local testArray = {"Primeiro item", "Próximo item", "Último item"}

table.remove(testArray, 2)

print(testArray[1]) -- Primeiro item
print(testArray[2]) -- Último item

Dicionários

Dicionários são uma extensão de arrays. Dicionários armazenam um conjunto de pares chave-valor, onde as chaves podem ser qualquer número, string ou objeto.

Criar dicionários

Para criar uma tabela de dicionário, defina cada chave seguida de = e o valor. Separe cada par chave-valor com uma vírgula:


local testDictionary = {
	nomeFruta = "Limão",
	corFruta = "Amarelo",
	azedo = true
}

As chaves para dicionários podem ser números, strings e objetos. Por exemplo, uma chave também pode ser um Instance. Para usar objetos como chaves, declare a chave entre colchetes ([key]):


local part = Instance.new("Part")

local testDictionary = {
	tipoParte = "Block",
	[part] = true
}

Ler de dicionários

Para ler de um dicionário, adicione um par de colchetes após sua referência e especifique o nome da chave. Referencie diretamente uma chave string usando (["key"]) ou (.key), ou em vez disso, use um valor de variável ([key]).


local part = Instance.new("Part")

local testDictionary = {
	tipoParte = "Block",
	[part] = true
}
-- Inclua aspas para chaves string
print(testDictionary["tipoParte"]) -- Block
-- Ou use . para indexar chaves string sem espaços
print(testDictionary.tipoParte) -- Block
-- Omitir aspas para chaves não-string
print(testDictionary[part]) -- true

Escrever em dicionários

Para definir ou reescrever o valor de uma nova chave de dicionário ou existente, declare o nome da chave entre colchetes ([key]) ou, se a chave for uma string, use (.key) seguido de = e o valor:


local testDictionary = {
	nomeFruta = "Limão",
	azedo = true
}

-- Mudar o valor das chaves existentes
testDictionary["nomeFruta"] = "Cereja"
testDictionary.azedo = false

-- Inserir novo par chave-valor
testDictionary.contagemFruta = 10

print(testDictionary.nomeFruta) -- Cereja
print(testDictionary.azedo) -- false
print(testDictionary.contagemFruta) -- 10

Iterar sobre dicionários

Para iterar sobre um dicionário, use um loop for:


local testDictionary = {
	nomeFruta = "Limão",
	corFruta = "Amarelo",
	azedo = true
}

for key, value in testDictionary do
	print(key, value)
end

--[[ Saída resultante:
nomeFruta Limão
azedo true
corFruta Amarelo
]]

Remover pares chave-valor

Para remover ou apagar um par chave-valor de um dicionário, defina seu valor para uma chave como nil.


local testDictionary = {
	nomeFruta = "Limão",
	corFruta = "Amarelo",
	azedo = true
}

testDictionary.azedo = nil

for key, value in testDictionary do
	print(key, value)
end
--[[ Saída resultante:
nomeFruta Limão
corFruta Amarelo
]]

Tabelas como referências

Se você armazenar uma tabela em uma nova variável, Luau não cria uma cópia dessa tabela. Em vez disso, a variável se torna uma referência, ou ponteiro, para a tabela original. Qualquer referência a uma tabela reflete quaisquer mudanças na tabela original:


local originalArray = {10, 20}

local arrayReference = originalArray

print("Original:", originalArray[1], originalArray[2])
print("Referência:", arrayReference[1], arrayReference[2])

-- Mudar valores no array original
originalArray[1] = 1000
originalArray[2] = 2000

print("Referência:", arrayReference[1], arrayReference[2])

--[[ Saída resultante:
Original: 10 20
Referência: 10 20
Referência: 1000 2000
]]

Clonar tabelas

Clones rasos

Para copiar uma tabela sem quaisquer tabelas aninhadas, Luau oferece o método table.clone().


local original = {
	chave = "valor",
	motor = "Roblox",
	playerID = 505306092
}

local clone = table.clone(original)

Clones profundos

Para copiar uma tabela mais complexa com tabelas aninhadas dentro dela, você precisará usar uma função recursiva semelhante à seguinte:


-- A função usada para clonar profundamente uma tabela
local function deepClone(original)
	-- Defina a nova tabela para a cópia
	local clone = table.clone(original) 

	-- Loop pela tabela original para verificar valores de tabela
	-- Se uma tabela for encontrada como valor, clone profundamente para a chave (índice)
	for key, value in original do
		if type(value) == "table" then
			clone[key] = deepClone(value)
		end
	end

	-- Retorne a cópia finalizada da tabela clonada profundamente
	return clone
end

Com a função em vigor, você pode fazer uma cópia profunda da seguinte forma:


local original = {
	chave = "valor",
	informacoesJogador = {
		playerID = 505306092,
		nomeJogador = "NomeDoJogador"
	},
	outrasInformacoes = {
		{
			{1, 3, 5, 7, 9}
		}
	}
}

local clone = deepClone(original)

Congelar tabelas

Congelar uma tabela a torna somente leitura, o que é útil para criar valores constantes que você não deseja modificar. O congelamento é permanente; não há um método "descongelar" ou "descongelar". Para verificar se uma tabela está congelada, use table.isfrozen().

Congelamentos rasos

Para congelar uma tabela sem quaisquer tabelas aninhadas, Luau oferece o método table.freeze().


local target = {
	chave = "valor",
	motor = "Roblox",
	playerID = 505306092
}

table.freeze(target)
target.playerID = 1 --> tentativa de modificar uma tabela somente leitura

Congelamentos profundos

Para congelar uma tabela mais complexa com tabelas aninhadas dentro dela, use uma função recursiva semelhante à seguinte:


local function deepFreeze(target)
	-- Congele a tabela de forma rasa
	table.freeze(target)

	-- Verifique cada chave da tabela e congele se for uma tabela
	for _, value in target do
		-- Certifique-se de que o valor não está congelado; se já estiver, ocorrerá um erro
		if type(value) == "table" and table.isfrozen(value) == false then
			deepFreeze(value)
		end
	end
end

Com a função em vigor, você pode congelar profundamente uma tabela da seguinte forma:


local target = {
	chave = "valor",
	informacoesJogador = {
		playerID = 505306092,
		nomeJogador = "NomeDoJogador"
	},
	outrasInformacoes = {
		{
			{1, 3, 5, 7, 9}
		}
	}
}

deepFreeze(target)
target.informacoesJogador.playerID = 1 --> tentativa de modificar uma tabela somente leitura