Конфигурация на активи

Преглед на опциите за конфигурация за Nette Assets.

assets:
	# базов път за разрешаване на относителни пътища на мапъри
	basePath: ...            # (string) по подразбиране е %wwwDir%

	# базов URL за разрешаване на относителни URL адреси на мапъри
	baseUrl: ...             # (string) по подразбиране е %baseUrl%

	# активиране на версииране на активи глобално?
	versioning: ...           # (bool) по подразбиране е true

	# дефинира мапъри на активи
	mapping: ...             # (array) по подразбиране е път 'assets'

basePath задава директорията на файловата система по подразбиране за разрешаване на относителни пътища в мапъри. По подразбиране използва уеб директорията (%wwwDir%).

baseUrl задава URL префикса по подразбиране за разрешаване на относителни URL адреси в мапъри. По подразбиране използва основния URL адрес (%baseUrl%).

Опцията versioning глобално контролира дали параметрите за версии се добавят към URL адресите на активи за изчистване на кеша. Отделните мапъри могат да презапишат тази настройка.

Мапъри

Мапърите могат да бъдат конфигурирани по три начина: проста нотация на низ, подробна нотация на масив или като препратка към услуга.

Най-простият начин за дефиниране на мапър:

assets:
	mapping:
		default: assets     # Създава мапър на файлова система за %wwwDir%/assets/
		images: img         # Създава мапър на файлова система за %wwwDir%/img/
		scripts: js         # Създава мапър на файлова система за %wwwDir%/js/

Всеки мапър създава FilesystemMapper, който:

• Търси файлове в %wwwDir%/<path>
• Генерира URL адреси като %baseUrl%/<path>
• Наследява глобалната настройка за версииране

За повече контрол, използвайте подробната нотация:

assets:
	mapping:
		images:
			# директория, където се съхраняват файловете
			path: ...                    # (string) опционално, по подразбиране е ''

			# URL префикс за генерирани връзки
			url: ...                     # (string) опционално, по подразбиране е path

			# активиране на версииране за този мапър?
			versioning: ...              # (bool) опционално, наследява глобалната настройка

			# автоматично добавяне на разширение(я) при търсене на файлове
			extension: ...               # (string|array) опционално, по подразбиране е null

Разбиране как се разрешават стойностите на конфигурацията:

Разрешаване на пътя

Относителните пътища се разрешават от basePath (или %wwwDir%, ако basePath не е зададен)

Абсолютните пътища се използват такива, каквито са

Разрешаване на URL

Относителните URL адреси се разрешават от baseUrl (или %baseUrl%, ако baseUrl не е зададен)

Абсолютните URL адреси (със схема или //) се използват такива, каквито са

Ако url не е указан, той използва стойността на path

assets:
	basePath: /var/www/project/www
	baseUrl: https://example.com/assets

	mapping:
		# Относителен път и URL
		images:
			path: img                    # Разрешено до: /var/www/project/www/img
			url: images                  # Разрешено до: https://example.com/assets/images

		# Абсолютен път и URL
		uploads:
			path: /var/shared/uploads    # Използва се както е: /var/shared/uploads
			url: https://cdn.example.com # Използва се както е: https://cdn.example.com

		# Указан е само пътят
		styles:
			path: css                    # Път: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Персонализирани мапъри

За персонализирани мапъри, препратете или дефинирайте услуга:

services:
	s3mapper: App\Assets\S3Mapper(%s3.bucket%)

assets:
	mapping:
		cloud: @s3mapper
		database: App\Assets\DatabaseMapper(@database.connection)

Vite Mapper

Vite мапърът изисква само да добавите type: vite. Това е пълен списък с опции за конфигурация:

assets:
	mapping:
		default:
			# тип мапър (задължителен за Vite)
			type: vite                # (string) задължителен, трябва да е 'vite'

			# директория за изход на Vite build
			path: ...                 # (string) опционално, по подразбиране е ''

			# URL префикс за изградени активи
			url: ...                  # (string) опционално, по подразбиране е path

			# местоположение на Vite manifest файл
			manifest: ...             # (string) опционално, по подразбиране е <path>/.vite/manifest.json

			# конфигурация на Vite dev сървър
			devServer: ...            # (bool|string) опционално, по подразбиране е true

			# версииране за файлове в публична директория
			versioning: ...           # (bool) опционално, наследява глобалната настройка

			# автоматично разширение за файлове в публична директория
			extension: ...            # (string|array) опционално, по подразбиране е null

Опцията devServer контролира как се зареждат активи по време на разработка:

• true (по подразбиране) – Автоматично открива Vite dev сървъра на текущия хост и порт. Ако dev сървърът работи и вашето приложение е в режим на отстраняване на грешки, активите се зареждат от него с поддръжка на гореща подмяна на модули. Ако dev сървърът не работи, активите се зареждат от изградените файлове в публичната директория.
• false – Напълно деактивира интеграцията на dev сървъра. Активите винаги се зареждат от изградените файлове.
• Персонализиран URL (напр. https://localhost:5173) – Ръчно указва URL адреса на dev сървъра, включително протокол и порт. Полезно, когато dev сървърът работи на различен хост или порт.

Опциите versioning и extension се прилагат само за файлове в публичната директория на Vite, които не се обработват от Vite.

Ръчна конфигурация

Когато не използвате Nette DI, конфигурирайте мапърите ръчно:

use Nette\Assets\Registry;
use Nette\Assets\FilesystemMapper;
use Nette\Assets\ViteMapper;

$registry = new Registry;

// Добавяне на мапър на файлова система
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

// Добавяне на Vite мапър
$registry->addMapper('app', new ViteMapper(
	baseUrl: '/build',
	basePath: __DIR__ . '/www/build',
	manifestPath: __DIR__ . '/www/build/.vite/manifest.json',
	devServer: 'https://localhost:5173',
));