Özel uygulamalar

Uygulama API'si

Özel uygulamanın çalıştığı iframe, yaşam döngüsü, sayfa ile telefon arasındaki her mesaj, seçiciler, diyaloglar, odak ve bir uygulamanın kullanabileceği Lua özellikleri.

#iframe

Sayfa şu sorgu parametreleriyle yüklenir:

Parametre Örnek Anlamı
phone fx-phone Her zaman fx-phone
app garage Uygulamanın id'si
resource my-garage Uygulamayı kaydeden resource
theme dark light ya da dark, önceden çözümlenmiş (asla auto değil)
insetTop 59 Durum çubuğu ve Dynamic Island'ın kapladığı piksel
insetBottom 34 Ana ekran çizgisinin kapladığı piksel
scale 1 Oyuncunun telefon boyutu

Parametreler sayfanın kendi sorgu dizesine eklenir ve ui içindeki aynı adlı parametrelerin yerini alır. Kendi ?tab=garage parametresi olan bir ui onu korur.

Frame hakkında bilgiler:

  • Telefonun bütün ekranını doldurur. Dokunulabilir içeriği insetTop ile insetBottom arasında tut.
  • Son ui adresi https:// olmalıdır. Resource sayfaları https://cfx-nui-<resource>/ olarak zaten böyledir. Başka her şey boş bir sayfa olarak açılır.
  • Script'ler, same-origin, formlar, modal'lar, popup'lar ve indirmelere izin verilmiş bir sandbox içindedir. Otomatik oynatma ve panoya yazma izinlidir.
  • Telefon mesajları yalnızca sayfanın origin'ine gönderir ve yalnızca senin iframe'inden gelen mesajları alır.

#Yaşam döngüsü

  1. Oyuncu uygulamayı açar. iframe oluşturulur ve sayfa yüklenir.
  2. Telefon şu sırayla gönderir: ready, componentsLoaded dizesi, visibility, landscape, stage ve uygulama veriyle açıldıysa open.
  3. Uygulama, uygulama değiştiricide olduğu sürece iframe yüklü kalır; böylece oyuncu ana ekrana gidip geri geldiğinde sayfa durumunu korur. Önde değilken visibility false bildirir.
  4. Oyuncu çok sayıda uygulama açarsa en eskileri değiştiriciden çıkar. Sayfaları kaldırılır ve bir sonraki sefer baştan yüklenir.
  5. keepOpen = true ile kaydedilmiş bir uygulama kaldırılmaz. Uygulama silinene kadar yüklü kalır ve gizlendiğinde bunu visibility ile öğrenir.
  6. Kaydeden resource durduğunda ya da RemoveCustomApp çağrıldığında uygulama telefondan kaldırılır.

Lua tarafında, uygulama öne geldiğinde ya da önden çekildiğinde fx-phone:customApp:opened ve fx-phone:customApp:closed uygulama id'siyle tetiklenir.

#Uygulamaya gelen mesajlar

window.addEventListener('message', ...) ile dinle. Telefondan gelen mesajlar type: 'fx-phone' taşır.

Mesaj Ne zaman
{ type: 'fx-phone', action: 'ready', theme, insets: { top, bottom } } İlk olarak, sayfa yüklendikten hemen sonra
'componentsLoaded' (düz bir dize) ready'den hemen sonra, lb-phone'un sırasıyla
{ type: 'fx-phone', action: 'visibility', visible } ready'den sonra ve her değiştiğinde. visible yalnızca uygulaman öndeyken ve telefon açık ve kilitsizken true olur
{ type: 'fx-phone', action: 'landscape', landscape } ready'den sonra ve uygulaman öndeyken telefon her yan döndüğünde ya da dik konuma geldiğinde
{ type: 'fx-phone', action: 'stage', stage, scale } ready'den sonra ve her değiştiğinde. Telefon uygulaman için ekranın ortasındayken stage true olur. scale, telefonun düzen boyutundan ne kadar büyük çizildiğidir
{ type: 'fx-phone', action: 'open', data } ready'den sonra ve boş olmayan data ile yapılan sonraki her OpenApp(appId, data) çağrısında
{ type: 'fx-phone', action: 'theme', theme } Tema değişti. Sayfa yeniden yüklenmez
{ type: 'fx-phone', action: 'key', state, code, repeat } Klavye senin sayfanda değil telefonun sayfasındayken sahiplenilmiş bir tuşa basıldı. state, down ya da up olur
{ type: 'fx-phone', action: 'pickResult', id, data } Bir pick isteğine yanıt. İptal edildiğinde data null olur
{ type: 'fx-phone', action: 'contextMenu:result', data: { id, button } } contextMenu yanıtı. button seçilen düğmenin id'sidir, kapatıldığında null
{ type: 'fx-phone', action: 'popUp:result', data: { id, button } } popUp yanıtı. button seçilen düğmenin id'sidir, kapatıldığında null
Lua'nın SendCustomAppMessage(appId, data) ile gönderdiği her şey Olduğu gibi, type olmadan gönderilir

Lua'dan veri gönderme:

luaexports['fx-phone']:SendCustomAppMessage('garage', { action = 'vehicles', list = vehicles })
jswindow.addEventListener('message', ({ data }) => {
  if (data?.action === 'vehicles') render(data.list);
});

O id ile kayıtlı bir uygulama yoksa SendCustomAppMessage, false, 'not_found' döndürür. SendCustomNUIMessage adıyla da kullanılabilir.

#Uygulamadan gelen mesajlar

Telefona şöyle gönder:

jsparent.postMessage({ type: 'fx-phone', appId, action, data }, '*');

type: 'cylex_phone' da kabul edilir.

Eylem Veri Ne olur
notification { title?, description?, icon? } Uygulamandan bir bildirim afişi. title varsayılan olarak uygulama adıdır. icon (ya da thumbnail) bir görsel URL'sidir. Yalnızca görüntülenir, ses yok
close Ekrandaysa uygulamayı kapatır
openApp { app } Oyuncunun görmesine izin varsa başka bir uygulamayı id'siyle açar
setFocus { focused } Metin alanlarından birinde odak varken true; böylece yazmak karakteri hareket ettirmez. Odak kaybolunca false
setLandscape { on } true, uygulaman öndeyken telefonu yan çevirir. false yeniden dik konuma getirir. Telefon bir landscape mesajıyla yanıt verir
setStage { on } true, telefonu oyun ekranının ortasına, sığan en büyük boyutta taşır. false geri koyar. Telefon bir stage mesajıyla yanıt verir
claimKeys { alt } alt: true, uygulaman öndeyken sol Alt'ı sahiplenir. Alt artık etrafa bakmaz; klavye telefonun kendi sayfasındayken basış sana bir key mesajı olarak ulaşır
pick { id, type, opts? } Bir seçici açar. Yanıt aynı id ile pickResult olarak geri gelir
contextMenu { id, title?, items } Vazgeç satırı olan bir eylem menüsü. contextMenu:result ile yanıtlanır
popUp { id, title, description, buttons } Bir uyarı penceresi. popUp:result ile yanıtlanır
nuiCallback { action, data } Resource'unda appId, action, data ile <resource>:phoneApp:event client event'ini tetikler

Bilinmeyen eylemler yok sayılır.

#Sayfadan bildirimler

jssend('notification', { title: 'Garage', description: 'Your car is ready', icon: 'https://cfx-nui-my-garage/html/car.png' });
  • Afiş senin uygulama id'nle gösterilir; böylece oyuncunun uygulama bazlı bildirim anahtarı geçerli olur.
  • Yalnızca görüntülenir. Ses çıkarmaz ve çevrimdışı oyuncular için saklanmaz.
  • Sunucunun izin vermediği bir sunucudaki görsel atılır ve afiş görselsiz gösterilir. Bir resource'tan gelen dosyalar ve data:image/ değerleri her zaman geçer.

Sesli ya da çevrimdışı bir oyuncu için saklanan bir bildirim için onu Lua'dan gönder. Bkz. Client export'ları: bildirimler ve Server export'ları: bildirimler.

#Seçiciler

jssend('pick', { id: 'shots', type: 'gallery', opts: { multiple: true, max: 3 } });
send('pick', { id: 'selfie', type: 'camera', opts: { kind: 'photo' } });

Türler: contact, gallery, camera, gif, emoji, color.

Seçenek Hangisi için Anlamı
title hepsi Sayfa başlığı
multiple, max contact, gallery max kadar birden fazla seçim. Bu durumda data bir listedir
kind gallery, camera photo ya da video

Sonuçlar ShowComponent export'undakiyle aynıdır: bir kişi { id, number, firstname, lastname, avatar, ... }, bir galeri öğesi { id, url, thumbnail, kind, ... } olur. Bkz. Client export'ları: diyaloglar.

camera, Kamera uygulamasını Kullan / Yeniden Çek incelemesiyle açar, kaydedilen öğeyle yanıt verir, sonra uygulamana döner.

#Bağlam menüleri ve popup'lar

contextMenu.items ve popUp.buttons içindeki düğmeler { id?, title, style? } biçimindedir. title gibi label da okunur. id varsayılan olarak dize hâlinde sırasıdır ('1', '2', ...). style: 'destructive' ya da lb-phone'un color: 'red' değeri düğmeyi kırmızı çizer.

jssend('contextMenu', {
  id: 'row-7',
  title: 'Vehicle',
  items: [{ id: 'track', title: 'Track' }, { id: 'sell', title: 'Sell', style: 'destructive' }],
});

window.addEventListener('message', ({ data: msg }) => {
  if (msg?.type === 'fx-phone' && msg.action === 'contextMenu:result' && msg.data.button === 'sell') confirmSale();
});

#Yatay görünüm

landscape = true ile kaydedilmiş bir uygulama, oyuncu telefonu Denetim Merkezi'nden döndürdüğünde ya da bir script SetLandscape(true) çağırdığında yan döner. Bu olmayan bir uygulama da, örneğin bir video tam ekrana geçtiğinde, setLandscape mesajıyla yatay görünümü kendisi isteyebilir.

Telefon yan yatarken sayfan 852'ye 393 olarak yerleştirilir ve landscape: true alır. Telefon yeniden dik konuma geldiğinde landscape: false alır: oyuncu alt kenardan yukarı kaydırmış, Denetim Merkezi'ni açmış ya da uygulamadan çıkmıştır. Yatay görünümdeki ilk yukarı kaydırma yalnızca telefonu dik konuma getirir; bu yüzden landscape: false aldığında tam ekran görünümünden çık.

#Stage

on: true ile setStage, telefonu oyun ekranının ortasına, sığan en büyük boyutta taşır. Oyunlar için düşünülmüştür. Uygulaman önden çekildiğinde, telefon kilitlendiğinde ya da kaldırıldığında kendiliğinden biter.

Telefon bir stage mesajıyla yanıt verir. Keskin kalmak için bir canvas'ın piksel oranını scale değeriyle çarp.

#Resource'unu çağırmak

iframe, https://cfx-nui-<resource>/ adresindeki senin sayfandır; bu yüzden normal bir NUI sayfası gibi resource'unun RegisterNUICallback işleyicilerini doğrudan çağırabilir:

jsconst res = await fetch(`https://${resource}/getVehicles`, { method: 'POST', body: '{}' });

nuiCallback, lb-phone'un yedek yolu için yazılmış uygulamalara yönelik alternatiftir. Bir client event'i olarak gelir:

luaAddEventHandler(GetCurrentResourceName() .. ':phoneApp:event', function(appId, action, data)
    if action == 'refresh' then
        -- ...
    end
end)

Uygulamanın sahibi bir resource yoksa (resource içermeyen bir Config.CustomApps girdisi) iletim not_found, action bir dize değilse invalid yanıtını verir.

Sayfanın resource'una gönderdiği her şey oyuncunun client'ından gelir. Buna göre işlem yapmadan önce server tarafında kontrol et.

#Odak

NUI odağı telefona aittir. Config.WalkWhileOpen = true olduğunda telefon açıkken hareket tuşları oyunda kalır. Bir metin alanında odak varken focused: true, odak kaybolunca focused: false ile setFocus gönder. Lua'dan SetInputFocus(focused) ve ToggleFocusKeepInput(keepInput) aynı işi yapar.

Uygulaman açıkken SetNuiFocus'u asla kendin çağırma.

#Uygulamayı veriyle açma

luaexports['fx-phone']:OpenApp('garage', { plate = 'ABC123' })

Veri sayfaya ready'den sonra bir open mesajı olarak ulaşır; böylece sayfa henüz yüklenmemiş olsa bile derin bağlantı çalışır. Boş olmayan veriyle yapılan her OpenApp çağrısı bir kez iletilir.

#Diğer telefon özellikleri

Aksi belirtilmedikçe bunların hepsi client export'larıdır.

Özellik Export Başvuru
Simgende bir sayı; 0 temizler SetAppBadge(id, count) Özel uygulamalar
Uygulama id'nle Lua'dan bildirim SendNotification({ app = 'garage', title = ..., content = ... }) Bildirimler
true ya da false döndüren onay sayfası DoPhoneConfirmation(title, text, icon) Diyaloglar ve seçiciler
Lua'dan seçiciler ShowComponent({ type = 'gallery' }) Diyaloglar ve seçiciler
Lua fonksiyonlarını çağıran popup'lar ve bağlam menüleri SetPopUp, SetContextMenu Diyaloglar ve seçiciler
Kilitli Ekran'da ve Dynamic Island'da Şimdi Çalıyor ShowMusicTray, UpdateMusicTray, RemoveMusicTray Dynamic Island
İlerleme, satırlar ve düğmeler içeren canlı etkinlik ShowLiveTray, UpdateLiveTray, RemoveLiveTray Dynamic Island
Fotoğraf URL'sini Lua koduna geri döndürme OpenCamera({ mode = 'photo' }, cb) Kamera ve fotoğraflar
Yalnızca atama etkinken çalışan, yeniden atanabilir bir tuş AddKeyBind Diğer
Karakter başına anahtar-değer depolaması (server) SetAppData, GetAppDataFor Özel uygulama depolaması

Depolama örneği. Değerler anahtar başına 16 KB'ye kadar herhangi bir JSON olabilir. Bir client'ın gönderdiğini saklamadan önce doğrula.

lua-- server.lua
RegisterNetEvent('my-app:save', function(value)
    local src = source
    local user = exports['fx-phone']:GetUserDataBySource(src)
    if not user or type(value) ~= 'string' or #value > 200 then return end
    exports['fx-phone']:SetAppData(user.identifier, 'hello', 'note', value)
end)

#Dynamic Island tray'leri

Bir uygulama iki tür tray kullanabilir:

  • Müzik tray'i. Island'da ve Kilitli Ekran'da Şimdi Çalıyor: kapak, başlık, sanatçı, çalma durumu ve kontroller. Düğmeler verdiğin handlers fonksiyonlarını (play, pause, next, prev, seek) çağırır. Island'da sarma çubuğu olmadığından seek henüz çağrılmaz.
  • Canlı etkinlik. Bir simge, bir başlık ve alt başlık, 0 ile 1 arasında bir progress, en fazla 3 düğme ve oyuncu island'ı açtığında gösterilen bir expanded görünümü (4 satır, 3 düğme).

İkisi için de kurallar:

  • Bir tray onu oluşturan resource'a aittir. Yalnızca o resource onu güncelleyebilir ya da kaldırabilir; o resource durduğunda tray de gider.
  • Kendi id'ni yeniden kullan. Aynı id'yi yeniden göstermek, ikinci bir tray eklemek yerine tray'i değiştirir.
  • Telefon kaldırılmışken tray görünür kalır ve telefon açıldığında yine oradadır. Telefon, arayüzü yeniden yüklendikten sonra tray'i yeniden gönderir. Onu yalnızca bir FX Phone yeniden başlatması temizler; bu yüzden fx-phone:client:phoneLoaded olduğunda yeniden göster.
  • Island bir seferde, önceliğe göre tek bir etkinlik gösterir: gelen arama, arama, alarm, zamanlayıcı, müzik, canlı etkinlik.

Müzik tray'i:

lualocal TRAY = 'myradio'

local function showTrack(t)
    exports['fx-phone']:ShowMusicTray({
        id = TRAY,
        title = t.title, artist = t.artist, cover = t.cover,
        playing = true, duration = t.length, position = 0,
        handlers = {
            play  = function() MyPlayer.Resume() end,
            pause = function() MyPlayer.Pause() end,
            next  = function() MyPlayer.Next() end,
            prev  = function() MyPlayer.Previous() end,
        },
    })
end

AddEventHandler('myradio:paused',  function() exports['fx-phone']:UpdateMusicTray(TRAY, 'playing', false) end)
AddEventHandler('myradio:stopped', function() exports['fx-phone']:RemoveMusicTray(TRAY) end)

Canlı etkinlik:

lualocal delivery = exports['fx-phone']:ShowLiveTray({
    id = 'delivery',
    title = 'Delivery', subtitle = '2.4 km',
    icon = 'truck', color = '#30D158', progress = 0,
    buttons = {
        { id = 'gps', icon = 'navigation-arrow', label = 'GPS', onPress = function() SetNewWaypoint(dest.x, dest.y) end },
    },
    expanded = {
        lines = { 'Order #12', 'Tip: $40' },
        buttons = { { id = 'cancel', icon = 'x', label = 'Cancel', onPress = function() TriggerServerEvent('mydelivery:cancel') end } },
    },
})

exports['fx-phone']:UpdateLiveTray(delivery, { progress = 0.5, subtitle = '1.2 km to go' })
exports['fx-phone']:RemoveLiveTray(delivery)

İmzalar ve dönüş değerleri Client export'ları: Dynamic Island sayfasında.

#lb-phone sayfa yardımcıları

lb-phone uygulamaları HTML'lerine https://cfx-nui-lb-phone/ui/components.js dosyasını ekler ve onun tanımladığı global fonksiyonları (fetchNui, setContextMenu, setPopUp, useCamera, selectGallery, getSettings, onSettingsChange, sendNotification ve diğerleri) çağırır. Bu script'in FX Phone sürümü html/compat/lb-components.js dosyasıdır. lb-phone katman resource'u onu ui/components.js olarak sunar; böylece bu sayfalar değiştirilmeden çalışır ve çağrıları bu sayfadaki mesaj protokolünden geçer.

FX Phone için yazılmış yeni bir uygulamanın buna ihtiyacı yoktur. Bkz. lb-phone uyumluluğu.