README и документация

Stencil — это современный фреймворк для создания веб-компонентов. Его основная цель — предоставить разработчикам инструмент для создания повторно используемых, высокоэффективных пользовательских интерфейсов, которые могут работать с любым JavaScript-окружением, включая фреймворки как Angular, React и Vue. Одной из ключевых особенностей Stencil является использование Web Components стандартов, что позволяет интегрировать компоненты в любой проект.

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

Проект, созданный с помощью Stencil, имеет четко организованную структуру, которая упрощает поддержку и развитие компонентов. Обычно структура выглядит следующим образом:

my-component/
├── src/
│   ├── components/
│   ├── global/
│   ├── index.ts
│   └── style/
├── www/
│   ├── index.html
│   └── assets/
├── stencil.config.ts
└── package.json

src/

В этой папке находятся все исходные файлы приложения. Компоненты и стили лежат в соответствующих подкаталогах.

  • components/ — здесь размещаются все компоненты, написанные с использованием Stencil.
  • global/ — глобальные утилиты, такие как директивы или сервисы.
  • style/ — стили, которые могут быть использованы глобально в проекте.

www/

Эта директория содержит файлы, которые будут скомпилированы и размещены в результирующем проекте.

  • index.html — основной HTML-файл проекта.
  • assets/ — различные статичные ресурсы, такие как изображения и шрифты.

stencil.config.ts

Это основной конфигурационный файл Stencil, который управляет процессом сборки и настройками проекта.

package.json

Файл, который описывает зависимости проекта, команды и скрипты для запуска сборки и разработки.

Основные концепции

Компоненты Stencil

Компоненты в Stencil представляют собой элементы, реализующие стандарт Web Components. Эти компоненты инкапсулируют логику, разметку и стили, обеспечивая повторное использование и изоляцию от остальной части приложения.

Компонент создается с помощью декоратора @Component(), который предоставляет информацию о метаданных компонента:

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

@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true
})
export class MyComponent {
  render() {
    return <div>Hello, Stencil!</div>;
  }
}
  • tag — имя тега, с которым компонент будет доступен в HTML.
  • styleUrl — путь к файлу стилей для компонента.
  • shadow — включает или отключает теневой DOM для компонента.

Параметры и события

Stencil поддерживает два типа свойств для компонентов: Props и States.

  • Props — это публичные свойства компонента, которые могут быть переданы через атрибуты в HTML.
  • States — это внутренние состояния компонента, которые могут изменяться внутри компонента и отслеживаются системой.

Для создания этих свойств используются декораторы:

@Component({ /* параметры компонента */ })
export class MyComponent {
  @Prop() name: string;
  @State() count: number;

  render() {
    return (
      <div>
        <p>Hello, {this.name}</p>
        <p>Count: {this.count}</p>
      </div>
    );
  }
}

События можно использовать для отправки сообщений от компонента родительским элементам. Для этого используется декоратор @Event():

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

@Component({
  tag: 'my-button',
})
export class MyButton {
  @Event() buttonClick: EventEmitter;

  handleClick() {
    this.buttonClick.emit('clicked');
  }

  render() {
    return <button onCl ick={() => this.handleClick()}>Click me</button>;
  }
}

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

Stencil поддерживает различные подходы к стилизации компонентов. Основные методы включают:

  • Scoped CSS — для изолированной стилизации, которая применима только к данному компоненту.
  • Global CSS — для применения стилей ко всему приложению.
  • CSS Variables — для создания настраиваемых стилей, которые могут быть изменены извне.

Stencil поддерживает препроцессоры, такие как Sass и Less, а также позволяет интегрировать сторонние библиотеки стилей.

Директивы и жизненный цикл компонентов

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

Жизненный цикл компонента включает в себя несколько ключевых методов, таких как:

  • componentWillLoad() — вызывается до загрузки компонента.
  • componentDidLoad() — вызывается после того, как компонент был загружен и отрисован.
  • componentWillUpdate() — вызывается перед обновлением компонента.
  • componentDidUpdate() — вызывается после обновления компонента.
  • componentDidUnload() — вызывается перед удалением компонента.

Эти методы позволяют управлять состоянием компонента и выполнять необходимые действия в нужный момент жизненного цикла.

Сборка и конфигурация

stencil.config.ts

Файл конфигурации Stencil позволяет настроить множество аспектов сборки проекта. В нем можно указать параметры, такие как:

  • outputTargets — настройка различных целей сборки (например, для браузеров, для компонента с SSR, или для упаковки в пакет).
  • devMode — включает или отключает режим разработки.
  • namespace — используется для установки пространства имен для компонентов, что полезно при создании нескольких компонентов.

Пример базовой конфигурации:

import { Config } from '@stencil/core';

export const config: Config = {
  namespace: 'my-components',
  outputTargets: [
    {
      type: 'dist',
      dir: 'dist',
    },
    {
      type: 'www',
      dir: 'www',
      serviceWorker: null, // не использовать сервис-воркеры
    },
  ],
};

Команды для разработки

Stencil предоставляет набор команд для работы с проектом, которые можно запускать через npm или Yarn:

  • npm start — запускает локальный сервер для разработки.
  • npm build — создает скомпилированные файлы для продакшн-режима.
  • npm test — запускает тесты компонента.

Тестирование компонентов

Stencil поддерживает тестирование компонентов с использованием Jest. Для каждого компонента автоматически создается базовая настройка тестов, что позволяет писать юнит-тесты и проверять корректность работы компонентов.

Пример теста для компонента:

import { newSpecPage } from '@stencil/core/testing';
import { MyButton } from './my-button';

describe('my-button', () => {
  it('renders the button with correct text', async () => {
    const page = await newSpecPage({
      components: [MyButton],
      html: `<my-button></my-button>`,
    });
    expect(page.root).toEqualHtml(`
      <my-button>
        <button>Click me</button>
      </my-button>
    `);
  });
});

Ресурсы и документация

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

Официальная документация доступна на сайте: https://stenciljs.com/docs. Также полезны такие ресурсы, как GitHub-репозиторий фреймворка, форумы и различные обучающие материалы, которые позволяют быстро освоить Stencil и использовать его в реальных проектах.

Заключение

Stencil представляет собой мощный инструмент для создания веб-компонентов с возможностью их повторного использования в любых веб-приложениях. Его гибкость и интеграция с другими JavaScript-библиотеками и фреймворками делают его отличным выбором для разработки современных, высокоэффективных пользовательских интерфейсов.

Оглавление