Создание нового проекта

Для начала работы с фреймворком Stencil необходимо установить его с помощью менеджера пакетов, например, npm или yarn. В первую очередь, убедитесь, что на вашем компьютере установлены Node.js и npm (или yarn). Для этого можно выполнить команду:

node -v
npm -v

Если версии установлены, можно переходить к следующему шагу. Для создания нового проекта с использованием Stencil, выполните следующую команду:

npm init stencil

Это инициирует процесс создания нового проекта и предложит несколько вариантов шаблонов. Для большинства случаев подойдет шаблон component, который создаёт базовую структуру для разработки компонентов.

npm init stencil component

После выполнения этой команды, вам будет предложено указать имя проекта и другие параметры, такие как тип пакета и версия фреймворка. После завершения установки все необходимые файлы и зависимости будут скачаны.

Структура проекта

После создания проекта, структура каталогов и файлов будет следующей:

my-stencil-project/
├── src/
│   ├── components/          # Компоненты Stencil
│   ├── index.ts             # Основной входной файл
│   └── global/              # Глобальные стили и утилиты
├── www/                     # Публикация для фронтенда
├── package.json             # Зависимости и скрипты
└── tsconfig.json            # Конфигурация TypeScript
  • src/ — каталог с исходным кодом проекта, где создаются компоненты, добавляются глобальные стили и утилиты.
  • www/ — папка для скомпилированных и готовых к использованию в браузере файлов. Это папка, которая будет развернута в конечном проекте.
  • package.json — описание проекта, его зависимости и скрипты для сборки и разработки.
  • tsconfig.json — настройки компилятора TypeScript, включающие пути и опции компиляции.

Запуск проекта в разработке

После того как проект создан, можно сразу же запустить локальный сервер для разработки. Для этого выполните команду:

npm start

Это запустит сервер на локальном хосте (обычно http://localhost:3333) и откроет ваш проект в браузере. В процессе разработки Stencil использует горячую перезагрузку (hot-reload), что позволяет изменять код и видеть результат без перезапуска сервера.

Структура компонентов Stencil

Компоненты Stencil — это основная единица разработки. Каждый компонент представляет собой класс, аннотированный с помощью декораторов, таких как @Component, @Prop и других. Стандартная структура компонента выглядит следующим образом:

import { Component, Prop, h } from '@stencil/core';

@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true
})
export class MyComponent {
  @Prop() name: string;

  render() {
    return (
      <div>
        <h1>Hello, {this.name}!</h1>
      </div>
    );
  }
}
  • @Component — декоратор, который определяет компонент, его тег и пути к стилям.
  • @Prop — декоратор для определения входных свойств компонента.
  • h() — функция, которая используется для рендеринга JSX.

Для работы с компонентами Stencil обязательно необходимо следовать правилам именования тегов, которые должны быть в нижнем регистре и содержать дефисы (например, <my-component>).

Стилизация компонентов

Для стилизации компонентов Stencil используется CSS, поддерживающий как стандартные стили, так и новые возможности, такие как CSS-переменные и кастомные свойства. Каждый компонент может иметь свои локальные стили, что позволяет избежать конфликтов между компонентами.

Стилевой файл компонента указывается через свойство styleUrl в декораторе @Component. В примере выше файл стилей для компонента находится по пути my-component.css.

Stencil также поддерживает Shadow DOM, что гарантирует изоляцию стилей компонента от других элементов на странице. Для использования Shadow DOM в компоненте достаточно задать свойство shadow: true в декораторе @Component.

Доступ к состоянию компонента

Stencil позволяет работать с состоянием компонента с помощью декоратора @State. Состояние компонента хранится внутри компонента и не передается напрямую в родительский компонент. Чтобы отслеживать изменения состояния, можно использовать метод render, который будет автоматически перерендеривать компонент при изменении состояния.

Пример использования состояния:

import { Component, h, State } from '@stencil/core';

@Component({
  tag: 'counter-component',
  styleUrl: 'counter-component.css',
  shadow: true
})
export class CounterComponent {
  @State() count: number = 0;

  increment() {
    this.count++;
  }

  render() {
    return (
      <div>
        <button onCl ick={() => this.increment()}>Increment</button>
        <p>Count: {this.count}</p>
      </div>
    );
  }
}

Компоненты и события

Stencil также поддерживает события, которые позволяют компонентам обмениваться данными с родительскими или дочерними элементами. С помощью декоратора @Event можно создавать собственные события. При этом событие можно передать как синхронно, так и асинхронно, и подписаться на его обработку с помощью слушателей событий.

Пример компонента, генерирующего событие:

import { Component, Event, EventEmitter, h } from '@stencil/core';

@Component({
  tag: 'event-emitter',
  styleUrl: 'event-emitter.css',
  shadow: true
})
export class EventEmitterComponent {
  @Event() customEvent: EventEmitter<string>;

  triggerEvent() {
    this.customEvent.emit('Hello from Stencil!');
  }

  render() {
    return (
      <div>
        <button onCl ick={() => this.triggerEvent()}>Trigger Event</button>
      </div>
    );
  }
}

Чтобы обработать событие в родительском компоненте:

<event-emitter onCustomEv ent={(event) => console.log(event.detail)}></event-emitter>

Сборка проекта

Когда проект готов и компоненты протестированы, можно выполнить сборку для подготовки файлов к публикации. Для этого используйте команду:

npm run build

Это создаст скомпилированные файлы, которые можно разместить на сервере или в статическом хостинге. Также можно использовать команду npm run test, чтобы протестировать компоненты с помощью встроенных тестов.

Stencil поддерживает различные форматы сборки: CommonJS, ES Modules, и другие, что позволяет использовать компоненты в разных экосистемах и на разных платформах.

Оглавление