Ö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
insetTopileinsetBottomarasında tut. - Son
uiadresihttps://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ü
- Oyuncu uygulamayı açar. iframe oluşturulur ve sayfa yüklenir.
- Telefon şu sırayla gönderir:
ready,componentsLoadeddizesi,visibility,landscape,stageve uygulama veriyle açıldıysaopen. - 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
visibilityfalsebildirir. - 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.
keepOpen = trueile kaydedilmiş bir uygulama kaldırılmaz. Uygulama silinene kadar yüklü kalır ve gizlendiğinde bunuvisibilityile öğrenir.- 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
handlersfonksiyonlarını (play,pause,next,prev,seek) çağırır. Island'da sarma çubuğu olmadığındanseekhenü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 birexpandedgö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:phoneLoadedolduğ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.