Nette Assets
Έχετε κουραστεί να διαχειρίζεστε χειροκίνητα στατικά αρχεία στις εφαρμογές ιστού σας; Ξεχάστε την ενσωμάτωση σκληρών διαδρομών, την αντιμετώπιση της ακύρωσης της κρυφής μνήμης ή την ανησυχία για την έκδοση αρχείων. Το Nette Assets μεταμορφώνει τον τρόπο που εργάζεστε με εικόνες, φύλλα στυλ, σενάρια και άλλους στατικούς πόρους.
- Έξυπνη έκδοση διασφαλίζει ότι τα προγράμματα περιήγησης φορτώνουν πάντα τα πιο πρόσφατα αρχεία
- Αυτόματη ανίχνευση τύπων αρχείων και διαστάσεων
- Απρόσκοπτη ενσωμάτωση Latte με διαισθητικές ετικέτες
- Ευέλικτη αρχιτεκτονική που υποστηρίζει συστήματα αρχείων, CDN και Vite
- Lazy loading για βέλτιστη απόδοση
Γιατί Nette Assets;
Η εργασία με στατικά αρχεία συχνά σημαίνει επαναλαμβανόμενο κώδικα επιρρεπή σε σφάλματα. Κατασκευάζετε χειροκίνητα διευθύνσεις URL, προσθέτετε παραμέτρους έκδοσης για την εκκαθάριση της κρυφής μνήμης και χειρίζεστε διαφορετικούς τύπους αρχείων με διαφορετικό τρόπο. Αυτό οδηγεί σε κώδικα όπως:
<img src="/images/logo.png?v=1699123456" width="200" height="100" alt="Logo">
<link rel="stylesheet" href="/css/style.css?v=2">
Με το Nette Assets, όλη αυτή η πολυπλοκότητα εξαφανίζεται:
{* Everything automated - URL, versioning, dimensions *}
<img n:asset="images/logo.png">
<link n:asset="css/style.css">
{* Or just *}
{asset 'css/style.css'}
Αυτό είναι όλο! Η βιβλιοθήκη αυτόματα:
- Προσθέτει παραμέτρους έκδοσης με βάση την ώρα τροποποίησης του αρχείου
- Ανιχνεύει τις διαστάσεις της εικόνας και τις συμπεριλαμβάνει στο HTML
- Δημιουργεί το σωστό στοιχείο HTML για κάθε τύπο αρχείου
- Χειρίζεται τόσο το περιβάλλον ανάπτυξης όσο και το περιβάλλον παραγωγής
Εγκατάσταση
Εγκαταστήστε το Nette Assets χρησιμοποιώντας το Composer:
composer require nette/assets
Απαιτεί PHP 8.1 ή νεότερο και λειτουργεί τέλεια με το Nette Framework, αλλά μπορεί επίσης να χρησιμοποιηθεί αυτόνομα.
Πρώτα Βήματα
Το Nette Assets λειτουργεί άμεσα χωρίς καμία ρύθμιση. Τοποθετήστε τα
στατικά σας αρχεία στον κατάλογο www/assets/
και αρχίστε να τα
χρησιμοποιείτε:
{* Display an image with automatic dimensions *}
{asset 'logo.png'}
{* Include a stylesheet with versioning *}
{asset 'style.css'}
{* Load a JavaScript module *}
{asset 'app.js'}
Για περισσότερο έλεγχο στο παραγόμενο HTML, χρησιμοποιήστε το
χαρακτηριστικό n:asset
ή τη συνάρτηση asset()
.
Πώς Λειτουργεί
Το Nette Assets βασίζεται σε τρεις βασικές έννοιες που το καθιστούν ισχυρό αλλά απλό στη χρήση:
Assets – Τα Αρχεία σας Έγιναν Έξυπνα
Ένα asset αντιπροσωπεύει οποιοδήποτε στατικό αρχείο στην εφαρμογή σας. Κάθε αρχείο γίνεται ένα αντικείμενο με χρήσιμες ιδιότητες μόνο για ανάγνωση:
$image = $assets->getAsset('photo.jpg');
echo $image->url; // '/assets/photo.jpg?v=1699123456'
echo $image->width; // 1920
echo $image->height; // 1080
echo $image->mimeType; // 'image/jpeg'
Διαφορετικοί τύποι αρχείων παρέχουν διαφορετικές ιδιότητες:
- Εικόνες: πλάτος, ύψος, εναλλακτικό κείμενο, lazy loading
- Σενάρια: τύπος ενότητας (module), hashes ακεραιότητας, crossorigin
- Φύλλα στυλ: media queries, ακεραιότητα
- Ήχος/Βίντεο: διάρκεια, διαστάσεις
- Γραμματοσειρές: σωστή προφόρτωση με CORS
Η βιβλιοθήκη ανιχνεύει αυτόματα τους τύπους αρχείων και δημιουργεί την κατάλληλη κλάση asset.
Mappers – Από Πού Προέρχονται τα Αρχεία
Ένας mapper γνωρίζει πώς να βρίσκει αρχεία και να δημιουργεί
διευθύνσεις URL για αυτά. Μπορείτε να έχετε πολλούς mappers για
διαφορετικούς σκοπούς – τοπικά αρχεία, CDN, αποθήκευση στο cloud ή
εργαλεία δημιουργίας (το καθένα από αυτά έχει ένα όνομα). Ο
ενσωματωμένος FilesystemMapper
χειρίζεται τα τοπικά αρχεία, ενώ ο
ViteMapper
ενσωματώνεται με σύγχρονα εργαλεία δημιουργίας.
Οι mappers ορίζονται στην Διαμόρφωση.
Registry – Η Κύρια Διεπαφή σας
Το registry διαχειρίζεται όλους τους mappers και παρέχει το κύριο API:
// Inject the registry in your service
public function __construct(
private Nette\Assets\Registry $assets
) {}
// Get assets from different mappers
$logo = $this->assets->getAsset('images:logo.png'); // 'image' mapper
$app = $this->assets->getAsset('app:main.js'); // 'app' mapper
$style = $this->assets->getAsset('style.css'); // uses default mapper
Το registry επιλέγει αυτόματα τον σωστό mapper και αποθηκεύει τα αποτελέσματα στην κρυφή μνήμη για καλύτερη απόδοση.
Εργασία με Assets σε PHP
Το Registry παρέχει δύο μεθόδους για την ανάκτηση assets:
// Throws Nette\Assets\AssetNotFoundException if file doesn't exist
$logo = $assets->getAsset('logo.png');
// Returns null if file doesn't exist
$banner = $assets->tryGetAsset('banner.jpg');
if ($banner) {
echo $banner->url;
}
Καθορισμός Mappers
Μπορείτε να επιλέξετε ρητά ποιον mapper θα χρησιμοποιήσετε:
// Use default mapper
$file = $assets->getAsset('document.pdf');
// Use specific mapper with prefix
$image = $assets->getAsset('images:photo.jpg');
// Use specific mapper with array syntax
$script = $assets->getAsset(['scripts', 'app.js']);
Ιδιότητες και Τύποι Asset
Κάθε τύπος asset παρέχει σχετικές ιδιότητες μόνο για ανάγνωση:
// Image properties
$image = $assets->getAsset('photo.jpg');
echo $image->width; // 1920
echo $image->height; // 1080
echo $image->mimeType; // 'image/jpeg'
// Script properties
$script = $assets->getAsset('app.js');
echo $script->type; // 'module' or null
// Audio properties
$audio = $assets->getAsset('song.mp3');
echo $audio->duration; // duration in seconds
// All assets can be cast to string (returns URL)
$url = (string) $assets->getAsset('document.pdf');
Ιδιότητες όπως διαστάσεις ή διάρκεια φορτώνονται με lazy loading μόνο όταν προσπελαστούν, διατηρώντας τη βιβλιοθήκη γρήγορη.
Χρήση Assets σε Πρότυπα Latte
Το Nette Assets παρέχει διαισθητική ενσωμάτωση Latte με ετικέτες και συναρτήσεις.
{asset}
Η ετικέτα {asset}
αποδίδει πλήρη στοιχεία HTML:
{* Renders: <img src="/assets/hero.jpg?v=123" width="1920" height="1080"> *}
{asset 'hero.jpg'}
{* Renders: <script src="/assets/app.js?v=456" type="module"></script> *}
{asset 'app.js'}
{* Renders: <link rel="stylesheet" href="/assets/style.css?v=789"> *}
{asset 'style.css'}
Η ετικέτα αυτόματα:
- Ανιχνεύει τον τύπο asset και δημιουργεί το κατάλληλο HTML
- Περιλαμβάνει έκδοση για την εκκαθάριση της κρυφής μνήμης
- Προσθέτει διαστάσεις για εικόνες
- Ορίζει τα σωστά χαρακτηριστικά (type, media, κ.λπ.)
Όταν χρησιμοποιείται μέσα σε χαρακτηριστικά HTML, εξάγει μόνο τη διεύθυνση URL:
<div style="background-image: url({asset 'bg.jpg'})">
<img srcset="{asset 'logo@2x.png'} 2x">
n:asset
Για πλήρη έλεγχο των χαρακτηριστικών HTML:
{* The n:asset attribute fills in src, dimensions, etc. *}
<img n:asset="product.jpg" alt="Product" class="rounded">
{* Works with any relevant element *}
<script n:asset="analytics.js" defer></script>
<link n:asset="print.css" media="print">
<audio n:asset="podcast.mp3" controls></audio>
Χρησιμοποιήστε μεταβλητές και mappers:
{* Variables work naturally *}
<img n:asset="$product->image">
{* Specify mapper with curly brackets *}
<img n:asset="images:{$product->image}">
{* Specify mapper with array notation *}
<img n:asset="[images, $product->image]">
asset()
Για μέγιστη ευελιξία, χρησιμοποιήστε τη συνάρτηση asset()
:
{var $logo = asset('logo.png')}
<img src={$logo} width={$logo->width} height={$logo->height}>
{* Or directly *}
<img src={asset('logo.png')} alt="Logo">
Προαιρετικά Assets
Χειριστείτε τα ελλείποντα assets με χάρη με {asset?}
, n:asset?
και
tryAsset()
:
{* Optional tag - renders nothing if asset missing *}
{asset? 'optional-banner.jpg'}
{* Optional attribute - skips if asset missing *}
<img n:asset?="user-avatar.jpg" alt="Avatar" class="avatar">
{* With fallback *}
{var $avatar = tryAsset('user-avatar.jpg') ?? asset('default-avatar.jpg')}
<img n:asset=$avatar alt="Avatar">
{preload}
Βελτιώστε την απόδοση φόρτωσης σελίδας:
{* In your <head> section *}
{preload 'critical.css'}
{preload 'important-font.woff2'}
{preload 'hero-image.jpg'}
Δημιουργεί κατάλληλους συνδέσμους προφόρτωσης:
<link rel="preload" href="/assets/critical.css?v=123" as="style">
<link rel="preload" href="/assets/important-font.woff2" as="font" crossorigin>
<link rel="preload" href="/assets/hero-image.jpg" as="image">
Προηγμένες Λειτουργίες
Αυτόματη Ανίχνευση Επέκτασης
Χειριστείτε αυτόματα πολλαπλές μορφές:
assets:
mapping:
images:
path: img
extension: [webp, jpg, png] # Try in order
Τώρα μπορείτε να ζητήσετε χωρίς επέκταση:
{* Finds logo.webp, logo.jpg, or logo.png automatically *}
{asset 'images:logo'}
Ιδανικό για προοδευτική βελτίωση με σύγχρονες μορφές.
Έξυπνη Έκδοση
Τα αρχεία εκδίδονται αυτόματα με βάση την ώρα τροποποίησης:
{asset 'style.css'}
{* Output: <link rel="stylesheet" href="/assets/style.css?v=1699123456"> *}
Όταν ενημερώνετε το αρχείο, η χρονοσφραγίδα αλλάζει, αναγκάζοντας την ανανέωση της κρυφής μνήμης του προγράμματος περιήγησης.
Έλεγχος έκδοσης ανά asset:
// Disable versioning for specific asset
$asset = $assets->getAsset('style.css', ['version' => false]);
// In Latte
{asset 'style.css', version: false}
Assets Γραμματοσειρών
Οι γραμματοσειρές λαμβάνουν ειδική μεταχείριση με σωστό CORS:
{* Proper preload with crossorigin *}
{preload 'fonts:OpenSans-Regular.woff2'}
{* Use in CSS *}
<style>
@font-face {
font-family: 'Open Sans';
src: url('{asset 'fonts:OpenSans-Regular.woff2'}') format('woff2');
font-display: swap;
}
</style>
Προσαρμοσμένοι Mappers
Δημιουργήστε προσαρμοσμένους mappers για ειδικές ανάλογες ανάγκες όπως αποθήκευση στο cloud ή δυναμική δημιουργία:
use Nette\Assets\Mapper;
use Nette\Assets\Asset;
use Nette\Assets\Helpers;
class CloudStorageMapper implements Mapper
{
public function __construct(
private CloudClient $client,
private string $bucket,
) {}
public function getAsset(string $reference, array $options = []): Asset
{
if (!$this->client->exists($this->bucket, $reference)) {
throw new Nette\Assets\AssetNotFoundException("Asset '$reference' not found");
}
$url = $this->client->getPublicUrl($this->bucket, $reference);
return Helpers::createAssetFromUrl($url);
}
}
Καταχωρήστε στη διαμόρφωση:
assets:
mapping:
cloud: CloudStorageMapper(@cloudClient, 'my-bucket')
Χρησιμοποιήστε όπως οποιονδήποτε άλλο mapper:
{asset 'cloud:user-uploads/photo.jpg'}
Η μέθοδος Helpers::createAssetFromUrl()
δημιουργεί αυτόματα τον σωστό τύπο
asset με βάση την επέκταση αρχείου.