Створіть пакет UX
Дата оновлення перекладу 2024-05-29
Створіть пакет UX
Tip
Перед тим як це читати, радимо переглянути Кращі практики для повторно використовуваних пакетів.
Ось декілька секретів, щоб зробити так, щоб ваш пакет встановлювався як пакет UX.
Файл composer.json
Ваш файл composer.json
повинен мати ключове слово symfony-ux
:
1 2 3
{
"keywords": ["symfony-ux"]
}
Розташування ресурсів
Ваші ресурси мають бути розташовані в одному з наступних каталогів з файлом package.json
, щоб Flex міг їх обробляти
під час встановлення/оновлення:
/assets
(рекомендовано)/Resources/assets
/src/Resources/assets
Файл package.json
Ваш файл package.json
повинен містити конфігурацію symfony
з визначеними контролерами, а також
додавати обовʼязкові пакети до peerDependencies
і importmap
(список
пакетів у importmap
має бути таким самим, як і у peerDependencies
):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
{
"name": "@acme/feature",
"version": "1.0.0",
"symfony": {
"controllers": {
"slug": {
"main": "dist/controller.js",
"fetch": "eager",
"enabled": true,
"autoimport": {
"@acme/feature/dist/bootstrap4-theme.css": false,
"@acme/feature/dist/bootstrap5-theme.css": true
}
}
},
"importmap": {
"@hotwired/stimulus": "^3.0.0",
"slugify": "^1.6.5"
}
},
"peerDependencies": {
"@hotwired/stimulus": "^3.0.0",
"slugify": "^1.6.5"
}
}
У цьому випадку буде розкрито файл, розташований за адресою [assets directory]/dist/controller.js
.
Tip
Ви можете або написати сирий JS у цьому файлі dist/controller.js
, або ви можете, наприклад,
написати свій контролер за допомогою TypeScript і трансполювати його в JavaScript.
Ось приклад, як це зробити:
Додайте наступне до вашого файлу
package.json
:1 2 3 4 5 6 7 8 9 10 11 12 13 14
{ "scripts": { "build": "babel src --extensions .ts -d dist" }, "devDependencies": { "@babel/cli": "^7.20.7", "@babel/core": "^7.20.12", "@babel/plugin-proposal-class-properties": "^7.18.6", "@babel/preset-env": "^7.20.2", "@babel/preset-typescript": "^7.18.6", "@hotwired/stimulus": "^3.2.1", "typescript": "^4.9.5" } }
Додайте наступне до вашого файлу
babel.config.js
(повинен бути розташований поруч з вашим файломpackage.json
):1 2 3 4 5 6 7 8 9 10 11 12
module.exports = { presets: [ ['@babel/preset-env', { "loose": true, "modules": false }], ['@babel/preset-typescript', { allowDeclareFields: true }] ], assumptions: { superIsCallableConstructor: false, }, };
- Запустіть
npm install
для встановлення нових залежностей. - Напишіть ваш контролер Stimulus за допомогою TypeScript у файлі
src/controller.ts
. - Запустіть
npm run build
, щоб трансполювати ваш контролер TypeScript у JavaScript.
Щоб використовувати ваш контролер у шаблоні (наприклад, визначеному у вашому пакунку), ви можете використовувати його таким чином:
1 2 3 4 5 6 7 8 9 10
<div
{{ stimulus_controller('acme/feature/slug', { modal: 'my-value' }) }}
{#
will render:
data-controller="acme--feature--slug"
data-acme--feature--slug-modal-value="my-value"
#}
>
...
</div>
Не забудьте додати symfony/stimulus-bundle:^2.9
як залежність композитора для використання
функцій Twig stimulus_*
.
Tip
Іменування контролерів: У цьому прикладі name
пакета PHP буде acme/feature
, а ім'я
контролера в package.json
- slug
. Отже, повне ім'я контролера для Stimulus буде таким
acme--feature--slug
, хоча у функції stimulus_controller()
ви можете використовувати
acme/feature/slug
.
Кожен контролер має ряд опцій у файлі package.json
:
????? | ???? |
---|---|
enabled | ?? ??? ???? ????????? ????????? ?? ?????????????. |
main | ???? ?? ????? ??????????. |
fetch | ?? ??????????? ?????????? ?? ?????????? ??? ???????????? ????????.
?????????????? eager (?? ?????????????), ??? ???????? ????????? ?? ?????????? ? JavaScript, ????
?????????????? ??? ???????????? ????????.
?????????????? lazy , ??? ??????? ????????? ? ?????????? ???????????? ? ???????? ????? ? ?????????????
?? ?????? ??????????, ???? (? ????) ?? ???????? ?'????????? HTML ????????? ?????. |
autoimport | ?????? ?????? ??? ??????? ? ???????????. ???????, ?????????, ???? ? ?????? ?????? CSS ??????? ??? ????????????????? ????????-?????????? (?????????, Bootstrap 4 ??? 5, Tailwind CSS...). ???????? ??? ???? ??'????? ? ??????? ? ?????? ?????? ? ??????? ????????? ??? ??????? ?????, ??? ?????????? ?? ???????? ??????????? ????. |
Особливості Asset Mapper
Щоб змусити ресурси вашого пакету працювати з AssetMapper, ви повинні додати конфігурацію importmap
як показано вище у ваш файл package.json
, і додати деяку конфігурацію
до контейнера:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39
namespace Acme\FeatureBundle;
use Symfony\Component\AssetMapper\AssetMapperInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Symfony\Component\HttpKernel\Bundle\AbstractBundle;
class AcmeFeatureBundle extends AbstractBundle
{
public function prependExtension(ContainerConfigurator $configurator, ContainerBuilder $container): void
{
if (!$this->isAssetMapperAvailable($container)) {
return;
}
$container->prependExtensionConfig('framework', [
'asset_mapper' => [
'paths' => [
__DIR__ . '/../assets/dist' => '@acme/feature-bundle',
],
],
]);
}
private function isAssetMapperAvailable(ContainerBuilder $container): bool
{
if (!interface_exists(AssetMapperInterface::class)) {
return false;
}
// перевірте, чи встановлено FrameworkBundle 6.3 або новіше
$bundlesMetadata = $container->getParameter('kernel.bundles_metadata');
if (!isset($bundlesMetadata['FrameworkBundle'])) {
return false;
}
return is_file($bundlesMetadata['FrameworkBundle']['path'] . '/Resources/config/asset_mapper.php');
}
}