Начало работы

Есть два основных способа использовать LitElement:

• Создание повторно используемых компонентов для других разработчиков. Отдельные компоненты или наборы связанных компонентов обычно публикуются в npm. Чтобы создать проект с повторно используемыми компонентами, см. Создание проекта компонентов LitElement.

• Создание компонентов для конкретного приложения. Исходный код этих компонентов может быть частью проекта приложения. Чтобы добавить компоненты LitElement в приложение, см. Добавление LitElement в существующий проект.

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

Чтобы начать локальную работу над компонентом, можно использовать один из этих стартовых проектов:

• Стартовый проект LitElement на JavaScript
• Стартовый проект LitElement на TypeScript

В обоих проектах определён компонент LitElement. Кроме того, в них добавлен набор дополнительных инструментов для разработки, проверки стиля кода и тестирования компонента:

• Node.js и npm для управления зависимостями. Требуется Node.js версии 10 или выше.
• Локальный сервер разработки ES dev server.
• Проверка кода с помощью ESLint и lit-analyzer.
• Тестирование с помощью Karma.
• Статический сайт документации, созданный с помощью web component analyzer и eleventy.

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

Самый быстрый способ опробовать проект локально — скачать один из стартовых проектов в виде ZIP-архива.

1. Скачайте стартовый проект с GitHub в виде ZIP-архива:

   • Стартовый проект на JavaScript
   • Стартовый проект на TypeScript

2. Распакуйте ZIP-архив.

3. Установите зависимости.

   cd <project folder>
   npm i

1. Если вы используете версию стартового проекта на TypeScript, соберите JavaScript-версию проекта:

   npm run build

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

   npm run build:watch

   Если вы используете версию стартового проекта на JavaScript, этап сборки не требуется.

2. Запустите сервер разработки:

   npm run serve

3. Откройте демонстрационную страницу проекта в новой вкладке браузера. Например:

   http://localhost:8000/dev/

   Сервер может использовать другой номер порта. Правильный номер порта указан в URL в выводе терминала.

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

• JavaScript. Отредактируйте файл my-element.js в корневом каталоге проекта.
• TypeScript. Отредактируйте файл my-element.ts в каталоге src.

Обратите внимание на следующие особенности кода:

• В коде определяется класс компонента (MyElement) и регистрируется в браузере как пользовательский элемент с именем <my-element>.

  JavaScript

  export class MyElement extends LitElement { ... }
  
  customElements.define('my-element', MyElement);

  TypeScript

  @customElement('my-element')
  export class MyElement extends LitElement { ... }

• Метод render компонента определяет шаблон, который будет отрисован как часть компонента. В данном случае он содержит текст, привязки данных и кнопку. Подробнее см. в разделе Шаблоны.

  export class MyElement extends LitElement {
    ...
    render() {
      return html`
        <h1>Hello, ${this.name}!</h1>
        <button @click=${this._onClick}>
          Click Count: ${this.count}
        </button>
        <slot></slot>
      `;
    }
  }

• В компоненте определены некоторые свойства. Компонент реагирует на изменения этих свойств (например, при необходимости повторно отрисовывая шаблон). Подробнее см. в разделе Свойства.

  JavaScript

  export class MyElement extends LitElement {
  
    static get properties() {
      return {
        name: {type: String}
      }
    }
  
    constructor() {
      super();
      this.name = 'World';
    }
    ...
  }

  TypeScript

  export class MyElement extends LitElement {
    ...
    @property({type: String})
    name = 'World';
    ...
  }

Вероятно, вы захотите заменить имя компонента «my-element» на более подходящее. Проще всего сделать это с помощью IDE или другого текстового редактора, который позволяет искать и заменять текст во всём проекте.

1. Если вы используете версию на TypeScript, удалите сгенерированные файлы:

   npm run clean

2. Найдите и замените «my-element» на новое имя компонента во всех файлах проекта (кроме папки node_modules).

3. Найдите и замените «MyElement» на новое имя класса во всех файлах проекта (кроме папки node_modules).

4. Переименуйте исходные файлы и файлы тестов в соответствии с новым именем компонента:

   JavaScript:

   • src/my-element.js
   • src/test/my-element_test.js

   TypeScript:

   • src/my-element.ts
   • src/test/my-element_test.ts

5. Если вы используете версию на TypeScript, пересоберите проект:

   npm run build

6. Проверьте, что компонент продолжает работать:

   npm run serve

Готовы добавить новые возможности в компонент? Перейдите к разделу Шаблоны, чтобы узнать, как писать шаблоны для компонентов LitElement.

Подробнее о запуске тестов и использовании других инструментов см. в файле README стартового проекта:

• Файл README проекта на TypeScript
• Файл README проекта на JavaScript

Для проектов LitElement не требуется много инструментов. Скорее всего, если у вас уже есть набор инструментов, вы сможете интегрировать LitElement с минимальными изменениями. В этих инструкциях предполагается, что вы используете npm для управления пакетами и такой инструмент, как Rollup или webpack, для сборки кода для production.

Подробнее о сборке проектов, включая примеры конфигураций Rollup, см. в разделе Сборка для production.

Ваша система сборки должна поддерживать использование спецификаторов bare-модулей:

import {LitElement, html} from 'lit-element';

Webpack автоматически обрабатывает спецификаторы bare-модулей; для Rollup понадобится плагин (@rollup/plugin-node-resolve).

LitElement доступен в npm:

npm i lit-element

Выберите место для хранения компонентов LitElement и создайте тестовый элемент:

components/my-element.js

import {LitElement, html} from 'lit-element';

class MyElement extends LitElement {
  render() {
    return html`
      <div>Hello from MyElement!</div>
    `;
  }
}

customElements.define('my-element', MyElement);

Импортируйте компонент:

Index.js

import './components/my-elements.js';

Используйте компонент:

index.html

<my-element></my-element>

Теперь вы должны иметь возможность собрать и запустить проект и увидеть сообщение «Hello from MyElement!».

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

Подробнее и примеры конфигураций сборки см. в разделе Сборка для production.

Если у вас уже есть сервер разработки, совместимый с системой сборки, он должен работать с LitElement. ES dev server — это альтернативный сервер разработки, предоставляющий простой рабочий процесс без сборщика. Он выполняет несколько полезных преобразований, в том числе преобразует спецификаторы bare-модулей, при необходимости транспилирует код в ES5 и добавляет полифилы для старых браузеров.

1. Установите es-dev-server

   npm i -D es-dev-server

2. Добавьте команду запуска сервера разработки в package.json:

   {
     "scripts": {
       "serve": "es-dev-server --app-index index.html --node-resolve --watch --open"
     }
   }

3. Запустите ES dev server:

   npm run serve

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

Подробнее см. в разделе Сборка для production.

Готовы добавить новые возможности в проект? Перейдите к разделу Шаблоны, чтобы узнать, как писать шаблоны для компонентов LitElement.

Подробнее о создании приложений с использованием веб-компонентов см. в рекомендациях open-wc по сборке.

Редактировать эту страницу