Notificações e barras de progresso FiveM: ESX, QBCore e ox_lib

Cada framework tem seu próprio jeito de mostrar uma mensagem ou uma barra de progresso, e um script escrito para um falha em outro:

attempt to index a nil value (global 'lib')

Este artigo lista as chamadas para ESX, QBCore e ox_lib, para notificações e para barras de progresso, depois mostra uma única função ponte para que seu script funcione em qualquer um que o servidor execute.

#Notificações no ESX

No cliente:

ESX.ShowNotification('You picked up a package')

No servidor, a partir do objeto do jogador:

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.showNotification('Your order is ready')

ESX aqui é o objeto de ESX = exports['es_extended']:getSharedObject(). Versões recentes do ESX também aceitam um tipo e uma duração após o texto. Se você depender deles, teste em sua versão.

#Notificações no QBCore

No cliente:

local QBCore = exports['qb-core']:GetCoreObject()

QBCore.Functions.Notify('You picked up a package', 'success', 5000)

O tipo é 'primary', 'success' ou 'error', e o último valor é o tempo em milissegundos. Do servidor, envie o evento ao jogador:

TriggerClientEvent('QBCore:Notify', source, 'Your order is ready', 'success')

No QBox as mesmas chamadas QBCore continuam funcionando através de sua camada de compatibilidade, e as notificações ox_lib são uma boa alternativa.

#Notificações com ox_lib

ox_lib tem sua própria notificação, e funciona igual em todos os frameworks. No cliente:

lib.notify({
    title = 'Delivery',
    description = 'You picked up a package',
    type = 'success',
    duration = 5000,
})

O tipo é 'inform', 'success', 'warning' ou 'error'. Do servidor, dispare o evento no jogador:

TriggerClientEvent('ox_lib:notify', source, {
    title = 'Delivery',
    description = 'Your order is ready',
    type = 'success',
})

O global lib precisa de shared_script '@ox_lib/init.lua' em seu fxmanifest.lua, como descrito no guia do menu de contexto ox_lib. Sem isso você recebe o erro lib nil acima.

#Barras de progresso

Com ox_lib, uma barra de progresso é uma chamada que aguarda e retorna se terminou:

if lib.progressBar({
    duration = 5000,
    label = 'Repairing the engine',
    useWhileDead = false,
    canCancel = true,
    disable = {
        move = true,
        car = true,
        combat = true,
    },
    anim = {
        dict = 'mini@repair',
        clip = 'fixing_a_ped',
    },
}) then
    print('finished')
else
    print('cancelled')
end

lib.progressCircle leva as mesmas opções e mostra um círculo em vez de uma barra. Ambos também podem anexar uma prop ao jogador.

A versão do QBCore usa um retorno de chamada em vez de aguardar:

QBCore.Functions.Progressbar('repair_engine', 'Repairing the engine', 5000, false, true, {
    disableMovement = true,
    disableCarMovement = true,
    disableMouse = false,
    disableCombat = true,
}, {
    animDict = 'mini@repair',
    anim = 'fixing_a_ped',
    flags = 49,
}, {}, {}, function()
    print('finished')
end, function()
    print('cancelled')
end)

Os argumentos são, em ordem: um nome, o rótulo, a duração, useWhileDead, canCancel, os controles desabilitados, a animação, duas props, depois os retornos de chamada de conclusão e cancelamento. ESX não tem sua própria barra de progresso que todo servidor compartilha, então no ESX use lib.progressBar.

#Uma função ponte para todos eles

Para manter seus scripts livres de framework, escreva o detalhe do framework uma vez e chame suas próprias funções em toda parte. Coloque isto em um arquivo do cliente:

local function started(name)
    return GetResourceState(name) == 'started'
end

function Notify(message, notifyType)
    notifyType = notifyType or 'inform'

    if started('ox_lib') then
        lib.notify({ description = message, type = notifyType })
    elseif started('qb-core') then
        local qbType = notifyType == 'inform' and 'primary' or notifyType
        exports['qb-core']:GetCoreObject().Functions.Notify(message, qbType)
    elseif started('es_extended') then
        exports['es_extended']:getSharedObject().ShowNotification(message)
    else
        print(message)
    end
end

-- returns true when finished, false when cancelled
function Progress(label, duration)
    if started('ox_lib') then
        return lib.progressBar({
            duration = duration,
            label = label,
            canCancel = true,
            disable = { move = true, car = true },
        })
    end

    local p = promise.new()
    exports['qb-core']:GetCoreObject().Functions.Progressbar('bridge_progress', label, duration, false, true, {
        disableMovement = true,
        disableCarMovement = true,
    }, {}, {}, {}, function() p:resolve(true) end, function() p:resolve(false) end)
    return Citizen.Await(p)
end

Agora seu script apenas chama Notify('Done', 'success') e Progress('Working', 5000). Se ox_lib está instalado, é usado primeiro. Caso contrário, QBCore é usado, e notificações voltam para ESX.

A barra de progresso de fallback cobre apenas QBCore. Em um servidor com neither ox_lib nem QBCore, adicione seu próprio ramo ou faça ox_lib uma dependência obrigatória com dependency 'ox_lib'.

Dica: faça o mesmo no servidor com uma função NotifyPlayer(source, message, type), usando as chamadas do servidor nas seções acima. Então nenhum outro arquivo precisa saber qual framework roda.

#Lista de verificação