@cat-of-summer/st-script 1.4.2 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/app/datepicker.min.js +3 -3
- package/dist/app/datepicker.min.js.map +3 -3
- package/dist/app/form.min.js +1 -1
- package/dist/app/form.min.js.map +3 -3
- package/dist/app.esm.min.js +1 -1
- package/dist/app.esm.min.js.map +3 -3
- package/dist/app.min.js +1 -1
- package/dist/app.min.js.map +3 -3
- package/dist/core.esm.min.js +1 -1
- package/dist/core.esm.min.js.map +3 -3
- package/dist/core.min.js +1 -1
- package/dist/core.min.js.map +3 -3
- package/dist/loader.esm.min.js +1 -1
- package/dist/loader.esm.min.js.map +3 -3
- package/dist/loader.min.js +1 -1
- package/dist/loader.min.js.map +3 -3
- package/dist/mask.esm.min.js +1 -1
- package/dist/mask.esm.min.js.map +3 -3
- package/dist/mask.min.js +1 -1
- package/dist/mask.min.js.map +3 -3
- package/dist/modal.esm.min.js +1 -1
- package/dist/modal.esm.min.js.map +3 -3
- package/dist/modal.min.js +1 -1
- package/dist/modal.min.js.map +3 -3
- package/dist/observer.esm.min.js +1 -1
- package/dist/observer.esm.min.js.map +3 -3
- package/dist/observer.min.js +1 -1
- package/dist/observer.min.js.map +3 -3
- package/dist/route.esm.min.js.map +2 -2
- package/dist/route.min.js +1 -1
- package/dist/route.min.js.map +2 -2
- package/dist/select.esm.min.js +1 -1
- package/dist/select.esm.min.js.map +3 -3
- package/dist/select.min.js +1 -1
- package/dist/select.min.js.map +3 -3
- package/dist/shape.esm.min.js +2 -0
- package/dist/shape.esm.min.js.map +7 -0
- package/dist/shape.min.js +2 -0
- package/dist/shape.min.js.map +7 -0
- package/dist/toggle.esm.min.js +1 -1
- package/dist/toggle.esm.min.js.map +3 -3
- package/dist/toggle.min.js +1 -1
- package/dist/toggle.min.js.map +3 -3
- package/dist/typograf.esm.min.js +1 -1
- package/dist/typograf.esm.min.js.map +3 -3
- package/dist/typograf.min.js +1 -1
- package/dist/typograf.min.js.map +3 -3
- package/dist/uploader.esm.min.js +1 -1
- package/dist/uploader.esm.min.js.map +3 -3
- package/dist/uploader.min.js +1 -1
- package/dist/uploader.min.js.map +3 -3
- package/dist/validator.esm.min.js +1 -1
- package/dist/validator.esm.min.js.map +3 -3
- package/dist/validator.min.js +1 -1
- package/dist/validator.min.js.map +3 -3
- package/docs/README.md +90 -0
- package/docs/src/README.md +29 -0
- package/docs/src/_traits/README.md +8 -0
- package/docs/src/_traits/hasInstanceSymbol.js.md +57 -0
- package/docs/src/app/README.md +13 -0
- package/docs/src/app/datepicker/README.md +9 -0
- package/docs/src/app/datepicker/_calendar.js.md +1 -0
- package/docs/src/app/datepicker/index.js.md +153 -0
- package/docs/src/app/form/README.md +8 -0
- package/docs/src/app/form/index.js.md +560 -0
- package/docs/src/app/index.js.md +1386 -0
- package/docs/src/cookie/README.md +8 -0
- package/docs/src/cookie/index.js.md +80 -0
- package/docs/src/core/README.md +8 -0
- package/docs/src/core/index.js.md +224 -0
- package/docs/src/index.js.md +1 -0
- package/docs/src/loader/README.md +8 -0
- package/docs/src/loader/index.js.md +126 -0
- package/docs/src/mask/README.md +10 -0
- package/docs/src/mask/_engine.js.md +1 -0
- package/docs/src/mask/_groups.js.md +1 -0
- package/docs/src/mask/index.js.md +412 -0
- package/docs/src/modal/README.md +8 -0
- package/docs/src/modal/index.js.md +821 -0
- package/docs/src/observer/README.md +9 -0
- package/docs/src/observer/_engine.js.md +28 -0
- package/docs/src/observer/index.js.md +259 -0
- package/docs/src/route/README.md +8 -0
- package/docs/src/route/index.js.md +385 -0
- package/docs/src/select/README.md +8 -0
- package/docs/src/select/index.js.md +115 -0
- package/docs/src/shape/README.md +9 -0
- package/docs/src/shape/_engine.js.md +1 -0
- package/docs/src/shape/index.js.md +99 -0
- package/docs/src/st_button_widget/README.md +9 -0
- package/docs/src/st_button_widget/README.txt.md +4 -0
- package/docs/src/st_button_widget/index.js.md +68 -0
- package/docs/src/st_links_widget/README.md +9 -0
- package/docs/src/st_links_widget/README.txt.md +4 -0
- package/docs/src/st_links_widget/index.js.md +46 -0
- package/docs/src/st_widget/README.md +8 -0
- package/docs/src/st_widget/button/README.md +4 -0
- package/docs/src/toggle/README.md +8 -0
- package/docs/src/toggle/index.js.md +604 -0
- package/docs/src/typograf/README.md +9 -0
- package/docs/src/typograf/_engine.js.md +75 -0
- package/docs/src/typograf/index.js.md +165 -0
- package/docs/src/uploader/README.md +8 -0
- package/docs/src/uploader/index.js.md +113 -0
- package/docs/src/validator/README.md +8 -0
- package/docs/src/validator/index.js.md +114 -0
- package/package.json +3 -2
- package/src/_traits/hasInstanceSymbol.js +14 -1
- package/src/app/index.js +102 -15
- package/src/core/index.js +83 -13
- package/src/index.js +1 -1
- package/src/loader/index.js +13 -3
- package/src/mask/index.js +21 -2
- package/src/modal/index.js +16 -6
- package/src/observer/index.js +3 -3
- package/src/select/index.js +24 -4
- package/src/{cut → shape}/_engine.js +1 -1
- package/src/{cut → shape}/index.js +19 -10
- package/src/toggle/index.js +85 -28
- package/src/typograf/index.js +3 -3
- package/src/uploader/index.js +32 -9
- package/src/validator/index.js +20 -2
- package/dist/cut.esm.min.js +0 -2
- package/dist/cut.esm.min.js.map +0 -7
- package/dist/cut.min.js +0 -2
- package/dist/cut.min.js.map +0 -7
|
@@ -0,0 +1,1386 @@
|
|
|
1
|
+
# app
|
|
2
|
+
|
|
3
|
+
## Обзор
|
|
4
|
+
|
|
5
|
+
`App` (`app.min.js`) — минималистичный реактивный фреймворк, основанный на [Custom Elements](https://developer.mozilla.org/ru/docs/Web/API/CustomElementRegistry). Каждый компонент — это нативный HTML-элемент `<st-app>`. Нет сборщиков, нет зависимостей, нет виртуального DOM — просто один файл и тег `<script>`.
|
|
6
|
+
|
|
7
|
+
**Ключевые возможности:**
|
|
8
|
+
|
|
9
|
+
- Реактивность через `Proxy` — DOM обновляется автоматически при изменении данных
|
|
10
|
+
- Батчировинг обновлений через `Promise.resolve()` — несколько мутаций за один тик сливаются в один проход
|
|
11
|
+
- Директивы шаблона: интерполяция `{{ }}`, `#if/#else-if/#else`, `#for` (с ключами `#key`), `#show`, `#class`, `#attr`, `#model`, `#html`, `@event`, `:attr`
|
|
12
|
+
- Вычисляемые свойства — геттеры с авто-трекингом зависимостей
|
|
13
|
+
- Двусторонняя привязка форм через `#model`
|
|
14
|
+
- Вложенные компоненты с реактивной передачей данных через `:attr`
|
|
15
|
+
- Переключение шаблонов на лету через `applyTemplate()`
|
|
16
|
+
- Наблюдатели через `watch()`
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Подключение
|
|
21
|
+
|
|
22
|
+
### Классический `<script>`
|
|
23
|
+
|
|
24
|
+
Достаточно одного тега. Никакого Node.js, Webpack или npm.
|
|
25
|
+
|
|
26
|
+
```html
|
|
27
|
+
<script src="https://cdn.jsdelivr.net/npm/@cat-of-summer/st-script/dist/app.min.js"></script>
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Класс `App` и тег `<st-app>` становятся глобально доступны.
|
|
31
|
+
|
|
32
|
+
### ES-модуль (import)
|
|
33
|
+
|
|
34
|
+
```html
|
|
35
|
+
<script type="module">
|
|
36
|
+
import App from '@cat-of-summer/st-script/app';
|
|
37
|
+
|
|
38
|
+
App.create({
|
|
39
|
+
app: 'counter',
|
|
40
|
+
count: 0,
|
|
41
|
+
template: `<button @click="count++">{{ count }}</button>`
|
|
42
|
+
});
|
|
43
|
+
</script>
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Или в отдельном `.js`-файле:
|
|
47
|
+
|
|
48
|
+
```js
|
|
49
|
+
import App from '@cat-of-summer/st-script/app';
|
|
50
|
+
|
|
51
|
+
export function initApp() {
|
|
52
|
+
App.create({ app: 'myApp', /* ... */ });
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
> **Важно:** `<st-app>` регистрируется как Custom Element при загрузке класса — это происходит на уровне статического инициализатора (`static { customElements.define('st-app', this) }`). При ES-модульном импорте это отрабатывает автоматически в момент импорта.
|
|
57
|
+
|
|
58
|
+
> **Внимание при ES-модулях:** `<script type="module">` выполняется **после** парсинга DOM (defer по умолчанию). Если `<st-app>` находится в HTML выше `<script type="module">`, фреймворк дождётся регистрации компонента — элемент будет ждать вызова `App.create()`.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## App.create(options) — регистрация компонента
|
|
63
|
+
|
|
64
|
+
```js
|
|
65
|
+
App.create({
|
|
66
|
+
app: 'myApp', // обязательно — уникальный id
|
|
67
|
+
template: `...`, // HTML-шаблон
|
|
68
|
+
setup() { ... }, // вызывается после init реактивности
|
|
69
|
+
events: { }, // объект обработчиков событий компонента
|
|
70
|
+
|
|
71
|
+
// произвольные реактивные свойства:
|
|
72
|
+
count: 0,
|
|
73
|
+
items: [],
|
|
74
|
+
user: { name: 'Иван' },
|
|
75
|
+
|
|
76
|
+
// методы:
|
|
77
|
+
increment() { this.count++; },
|
|
78
|
+
|
|
79
|
+
// вычисляемые свойства (геттеры):
|
|
80
|
+
get total() { return this.items.length; }
|
|
81
|
+
});
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
| Поле | Тип | Описание |
|
|
85
|
+
|---|---|---|
|
|
86
|
+
| `app` | `string` | Уникальный идентификатор; совпадает со значением атрибута `app` на элементе |
|
|
87
|
+
| `template` | `string` | HTML-шаблон компонента. Если пустая строка — используется `innerHTML` элемента |
|
|
88
|
+
| `setup()` | `function` | Вызывается один раз после инициализации реактивности, до рендеринга. `this` — экземпляр компонента |
|
|
89
|
+
| `events` | `object` | Карта `{ eventName: handler }` — навешиваются через `addEventListener` на элемент |
|
|
90
|
+
| `...data` | `any` | Произвольные реактивные свойства. Примитивы, объекты и массивы — все становятся реактивными |
|
|
91
|
+
| `method()` | `function` | Метод компонента. Доступен в шаблоне и через `this` |
|
|
92
|
+
| `get prop()` | `function` | Вычисляемое свойство. Пересчитывается при изменении зависимостей. Доступно в шаблоне |
|
|
93
|
+
| `helpers` | `object` | Значения, видимые в шаблоне, но не реактивные: форматтеры, фасады модулей. См. "Помощники шаблона" |
|
|
94
|
+
|
|
95
|
+
> **Важно:** `App.create()` бросает ошибку, если приложение с таким `app` уже зарегистрировано.
|
|
96
|
+
|
|
97
|
+
**Зарезервированные имена.** `app`, `template`, `setup`, `events` и `helpers` - опции, а не данные: свойствами компонента они не становятся. Данные с таким именем (`events: []` - список событий для `<select>`) `App.create()` и `App.extend()` не примут. Если опция не того вида (`setup` не функция, `template` не строка, `events` или `helpers` не объект), бросается `TypeError` с подсказкой:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
App.create("routes"): "events" - обработчики { имя: функция }, получен массив. Если это данные, переименуйте поле
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Переименуйте поле (`mailEvents: []`). Если такое имя присвоить в `setup()` (`this.events = [...]`), предупреждение в консоли скажет, что имя занято опцией.
|
|
104
|
+
|
|
105
|
+
### Помощники шаблона: `helpers` и `App.helpers()`
|
|
106
|
+
|
|
107
|
+
Форматтеры и фасады, которые шаблон вызывает в `{{ }}` и обработчиках, не нужно класть в конфиг (там методы оборачиваются и вызов из обработчика перерисовывает их читателей) или в `window`:
|
|
108
|
+
|
|
109
|
+
```js
|
|
110
|
+
import { format } from './format.js';
|
|
111
|
+
|
|
112
|
+
App.helpers({ format }); // видно во всех приложениях
|
|
113
|
+
|
|
114
|
+
App.create({
|
|
115
|
+
app: 'list',
|
|
116
|
+
helpers: { Api }, // видно только в этом приложении
|
|
117
|
+
items: [],
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
```html
|
|
122
|
+
<span>{{ format.date(item.updated_at) }}</span>
|
|
123
|
+
<button @click="Api.reload()">Обновить</button>
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Имя ищется по порядку: свойства компонента и переменные цикла, `helpers` конфига, `App.helpers()`, глобальные. Помощники не становятся свойствами элемента и ничего не перерисовывают сами. `App.extend` сливает `helpers` базового и нового конфига.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## App.extend(app, options) — расширение компонента
|
|
131
|
+
|
|
132
|
+
Создаёт новый компонент на основе существующего, переопределяя нужные поля. `events` сливаются, а не заменяются. Геттеры (вычисляемые свойства) переносятся как геттеры и в наследнике считаются от его данных.
|
|
133
|
+
|
|
134
|
+
```js
|
|
135
|
+
App.create({
|
|
136
|
+
app: 'base',
|
|
137
|
+
count: 0,
|
|
138
|
+
label: 'База',
|
|
139
|
+
template: `<p>{{ label }}: {{ count }}</p>`
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
App.extend('base', {
|
|
143
|
+
app: 'extended',
|
|
144
|
+
label: 'Расширенный',
|
|
145
|
+
count: 100
|
|
146
|
+
});
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
```html
|
|
150
|
+
<st-app app="extended"></st-app>
|
|
151
|
+
<!-- Выведет: Расширенный: 100 -->
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## App.toRaw(value) и App.snapshot(value) — данные без реактивности
|
|
157
|
+
|
|
158
|
+
Объекты и массивы конфига отдаются через `Proxy`. Чтобы отправить их на сервер, сравнить с исходником или сохранить копию:
|
|
159
|
+
|
|
160
|
+
- `App.toRaw(value)` — исходный объект под обёрткой, вложенные значения как есть. Значение без обёртки возвращается без изменений.
|
|
161
|
+
- `App.snapshot(value)` — глубокая копия без обёрток: массивы и простые объекты копируются, остальное (`Date`, `File`, `Map`, экземпляры классов) идёт как есть. Циклические ссылки сохраняются.
|
|
162
|
+
|
|
163
|
+
```js
|
|
164
|
+
const body = App.snapshot(this.form); // вместо JSON.parse(JSON.stringify(this.form))
|
|
165
|
+
const changed = App.toRaw(this.item) !== original;
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## Монтирование компонента
|
|
171
|
+
|
|
172
|
+
```html
|
|
173
|
+
<!-- Монтирование по id -->
|
|
174
|
+
<st-app app="counter"></st-app>
|
|
175
|
+
|
|
176
|
+
<!-- Компонент без App.create() — только атрибуты + innerHTML как шаблон -->
|
|
177
|
+
<st-app :title="Привет" :count="42">
|
|
178
|
+
<h1>{{ title }}</h1>
|
|
179
|
+
<p>Счётчик: {{ count }}</p>
|
|
180
|
+
</st-app>
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### Атрибут `app`
|
|
184
|
+
|
|
185
|
+
Связывает HTML-элемент с конфигурацией, зарегистрированной через `App.create()`. Если элемент появляется в DOM раньше вызова `App.create()` — он ждёт регистрации.
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Реактивные данные
|
|
190
|
+
|
|
191
|
+
Все свойства, объявленные в `App.create()`, становятся реактивными автоматически:
|
|
192
|
+
|
|
193
|
+
- **Примитивы** (`number`, `string`, `boolean`) — отслеживаются по ключу
|
|
194
|
+
- **Объекты и массивы** — оборачиваются в `Proxy`. Работает на любой глубине вложенности
|
|
195
|
+
- **Функции** — оборачиваются в прокси, который тригерит зависимости после вызова
|
|
196
|
+
|
|
197
|
+
При изменении данных DOM обновляется асинхронно (батч через `Promise.resolve()`), поэтому несколько синхронных мутаций приводят к одному проходу обновлений.
|
|
198
|
+
|
|
199
|
+
```js
|
|
200
|
+
App.create({
|
|
201
|
+
app: 'reactive',
|
|
202
|
+
user: { profile: { name: 'Иван', age: 25 } },
|
|
203
|
+
|
|
204
|
+
incrementAge() {
|
|
205
|
+
this.user.profile.age++; // глубокое изменение — DOM обновится
|
|
206
|
+
},
|
|
207
|
+
|
|
208
|
+
template: `
|
|
209
|
+
<div>
|
|
210
|
+
<p>{{ user.profile.name }}, {{ user.profile.age }} лет</p>
|
|
211
|
+
<button @click="incrementAge()">+1 год</button>
|
|
212
|
+
</div>
|
|
213
|
+
`
|
|
214
|
+
});
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Реактивные массивы
|
|
218
|
+
|
|
219
|
+
Все мутирующие методы массива (`push`, `pop`, `splice`, `shift`, `unshift`, `sort`, `reverse`) тригерят обновление DOM:
|
|
220
|
+
|
|
221
|
+
```js
|
|
222
|
+
this.items.push('новый элемент'); // ✓ реактивно
|
|
223
|
+
this.items.splice(2, 1); // ✓ реактивно
|
|
224
|
+
this.items = [...this.items, 'x']; // ✓ тоже работает
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## Вычисляемые свойства (геттеры)
|
|
230
|
+
|
|
231
|
+
Геттеры автоматически отслеживают зависимости и пересчитываются при их изменении:
|
|
232
|
+
|
|
233
|
+
```js
|
|
234
|
+
App.create({
|
|
235
|
+
app: 'form',
|
|
236
|
+
username: '',
|
|
237
|
+
email: '',
|
|
238
|
+
agreed: false,
|
|
239
|
+
|
|
240
|
+
get isValid() {
|
|
241
|
+
// зависит от username, email, agreed — пересчитается при изменении любого из них
|
|
242
|
+
return this.username.length >= 3
|
|
243
|
+
&& this.email.includes('@')
|
|
244
|
+
&& this.agreed;
|
|
245
|
+
},
|
|
246
|
+
|
|
247
|
+
template: `
|
|
248
|
+
<div>
|
|
249
|
+
<input #model="username" placeholder="Имя (мин. 3 символа)">
|
|
250
|
+
<input #model="email" placeholder="Email">
|
|
251
|
+
<label><input type="checkbox" #model="agreed"> Согласен</label>
|
|
252
|
+
<button disabled="{{ !isValid }}">Отправить</button>
|
|
253
|
+
<p #show="isValid" style="color:green">Форма валидна!</p>
|
|
254
|
+
</div>
|
|
255
|
+
`
|
|
256
|
+
});
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
> **Геттеры — read-only.** Присваивание в геттер не сработает. Для хранения состояния используйте обычное свойство.
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## Директивы шаблона
|
|
264
|
+
|
|
265
|
+
### `{{ expr }}` — интерполяция
|
|
266
|
+
|
|
267
|
+
Вычисляет любое JS-выражение в контексте компонента (`this`). Поддерживается как в текстовых узлах, так и в значениях атрибутов.
|
|
268
|
+
|
|
269
|
+
```html
|
|
270
|
+
<!-- Текстовый узел -->
|
|
271
|
+
<p>Привет, {{ user.name }}!</p>
|
|
272
|
+
<p>Итого: {{ items.length * price }}</p>
|
|
273
|
+
<p>{{ isActive ? 'Включено' : 'Выключено' }}</p>
|
|
274
|
+
<p>{{ JSON.stringify(data, null, 2) }}</p>
|
|
275
|
+
|
|
276
|
+
<!-- В значении атрибута -->
|
|
277
|
+
<div class="badge-{{ status }}"></div>
|
|
278
|
+
<div style="color: {{ score > 90 ? 'green' : 'red' }}"></div>
|
|
279
|
+
<img src="{{ baseUrl + '/images/' + filename }}">
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Если выражение вернёт `null` или `undefined` — выводится пустая строка.
|
|
283
|
+
|
|
284
|
+
> [!note] Порядок атрибутов не важен
|
|
285
|
+
> `#pre`, `#if` и `#for` обрабатываются раньше остальных атрибутов элемента, где бы они ни стояли. `<li class="{{ row.kind }}" #for="row in rows">` видит переменную цикла, `<b title="{{ x }}" #if="on">` связывается внутри ветки.
|
|
286
|
+
|
|
287
|
+
---
|
|
288
|
+
|
|
289
|
+
### `@event="statement"` — обработчики событий
|
|
290
|
+
|
|
291
|
+
Имя директивы — это имя DOM-события без `@`. Значение — JS-выражение (statement), выполняется в контексте компонента. Доступна переменная `$event` — нативный объект события.
|
|
292
|
+
|
|
293
|
+
```html
|
|
294
|
+
<button @click="count++">+1</button>
|
|
295
|
+
<button @click="increment()">Метод</button>
|
|
296
|
+
<input @keyup="if ($event.key === 'Enter') submit()">
|
|
297
|
+
<form @submit="$event.preventDefault(); save()">
|
|
298
|
+
<div @mousemove="updatePosition($event)">
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
**В циклах** `$index` и переменная цикла корректно захватываются замыканием:
|
|
302
|
+
|
|
303
|
+
```html
|
|
304
|
+
<li #for="item in items">
|
|
305
|
+
<button @click="removeItem($index)">Удалить {{ item }}</button>
|
|
306
|
+
</li>
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
**Модификатор `.self`** — обработчик срабатывает, только если событие отправлено самим элементом (`$event.target` — этот элемент), а не всплыло от потомков:
|
|
310
|
+
|
|
311
|
+
```html
|
|
312
|
+
<!-- Только событие input, которое отправил сам компонент; нативный input из его полей не ловится -->
|
|
313
|
+
<st-app app="editor" @input.self="onEditorInput($event.detail)"></st-app>
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
Вешая обработчик на вложенный `<st-app>`, помните: нативные события его полей (`input`, `change`, `click`) всплывают до него. Для событий компонента используйте `.self` или имя, которое не совпадает с нативным (`commit`, `editor:save`).
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
### `#if="cond"` / `#else-if="cond"` / `#else` — условный рендеринг
|
|
321
|
+
|
|
322
|
+
Элемент добавляется в DOM только при выполнении условия. При ложном условии — удаляется, подписки очищаются. При каждом повторном показе ветка собирается заново из исходной разметки: состояние полей ввода внутри неё не сохраняется (для этого есть `#show`). `#else-if` и `#else` должны идти на **непосредственном следующем** соседнем элементе.
|
|
323
|
+
|
|
324
|
+
```html
|
|
325
|
+
<div #if="score >= 90">🌟 Отлично!</div>
|
|
326
|
+
<div #else-if="score >= 70">👍 Хорошо</div>
|
|
327
|
+
<div #else-if="score >= 50">⚠️ Удовлетворительно</div>
|
|
328
|
+
<div #else>❌ Плохо</div>
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
```html
|
|
332
|
+
<p #if="items.length === 0">Список пуст</p>
|
|
333
|
+
<ul #else>
|
|
334
|
+
<li #for="item in items">{{ item }}</li>
|
|
335
|
+
</ul>
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
> **Отличие от `#show`:** при `#if` элемент физически удаляется из DOM. При `#show` — остаётся, но скрыт через `display: none`. Используйте `#if` когда нужно уничтожить дочерние компоненты; `#show` — когда нужна быстрая смена видимости.
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
### `#show="cond"` — видимость без удаления из DOM
|
|
343
|
+
|
|
344
|
+
```html
|
|
345
|
+
<div #show="isLoading">⏳ Загрузка...</div>
|
|
346
|
+
<p #show="items.length > 0">Найдено {{ items.length }} элементов</p>
|
|
347
|
+
<small #show="error">{{ error }}</small>
|
|
348
|
+
|
|
349
|
+
<!-- Опциональная цепочка работает нормально: -->
|
|
350
|
+
<ul #show="availablePages?.length">...</ul>
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
При `cond === false` устанавливает `style.display = 'none'`. При `true` — убирает этот стиль.
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
### `#class="{ 'имя': условие }"` — классы по условию
|
|
358
|
+
|
|
359
|
+
Ставит и снимает классы поверх статического `class` и `class="{{ }}"`:
|
|
360
|
+
|
|
361
|
+
```html
|
|
362
|
+
<li class="item" #class="{ 'item--active': selected === row.id, 'item--muted item--small': row.hidden }">
|
|
363
|
+
<b #class="[loading && 'is-loading', size]"></b>
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
- Объект: ключ — одно имя или несколько через пробел, значение — условие.
|
|
367
|
+
- Массив или строка: имена; ложные элементы массива пропускаются.
|
|
368
|
+
- Имена лежат в разметке литералами, поэтому их видит очистка неиспользуемого CSS. Склейка имени из частей (`'item--' + kind`) ей не видна.
|
|
369
|
+
- Не дублируйте в `#class` имя из статического `class`: при ложном условии оно снимется.
|
|
370
|
+
|
|
371
|
+
---
|
|
372
|
+
|
|
373
|
+
### `#attr="{ 'имя': значение }"` - атрибуты из выражения
|
|
374
|
+
|
|
375
|
+
Ставит атрибуты по значениям выражения, а не по строке в разметке. Нужна, когда разметку собирает шаблонизатор: Astro печатает `disabled="{{ busy }}"`, пришедший пропсом компонента, как голый `disabled` (для него атрибут булев), и выражение теряется. `#attr` такие шаблонизаторы не трогают.
|
|
376
|
+
|
|
377
|
+
```html
|
|
378
|
+
<button #attr="{ disabled: busy, title: hint, 'aria-selected': tab === 'rules' }">Сохранить</button>
|
|
379
|
+
<input type="checkbox" #attr.checked="row.on">
|
|
380
|
+
<svg #attr="{ viewBox: box }"></svg>
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
- Булевы атрибуты (список в разделе "Boolean-атрибуты") ставятся и снимаются по истинности значения. У `checked`, `selected` и `value` выставляется и свойство, как у привязки через `{{ }}`.
|
|
384
|
+
- Остальные: `null` и `undefined` снимают атрибут, иначе пишется `String(значение)`. Поэтому `'aria-selected': false` даёт `aria-selected="false"`, а не снимает атрибут.
|
|
385
|
+
- Имя, которое пропало из объекта при следующем вычислении, снимается.
|
|
386
|
+
- `#attr.имя="выражение"` - сокращение для одного атрибута. HTML-парсер приводит имена атрибутов к нижнему регистру, поэтому `#attr.viewBox` превратится в `viewbox`. Для имён с заглавными буквами (SVG) используйте объект.
|
|
387
|
+
- Классы - через `#class`, а не через `#attr`.
|
|
388
|
+
|
|
389
|
+
---
|
|
390
|
+
|
|
391
|
+
### `#for="item in collection"` — цикл
|
|
392
|
+
|
|
393
|
+
Работает с **массивами** и **объектами**.
|
|
394
|
+
|
|
395
|
+
#### Цикл по массиву
|
|
396
|
+
|
|
397
|
+
```html
|
|
398
|
+
<ul>
|
|
399
|
+
<li #for="item in items">
|
|
400
|
+
{{ $index + 1 }}. {{ item }}
|
|
401
|
+
<button @click="items.splice($index, 1)">✕</button>
|
|
402
|
+
</li>
|
|
403
|
+
</ul>
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
| Переменная | Значение |
|
|
407
|
+
|---|---|
|
|
408
|
+
| `item` | текущий элемент массива |
|
|
409
|
+
| `$index` | числовой индекс (0, 1, 2, …) |
|
|
410
|
+
|
|
411
|
+
#### Цикл по объекту
|
|
412
|
+
|
|
413
|
+
```html
|
|
414
|
+
<ul>
|
|
415
|
+
<li #for="val in settings">{{ $key }}: {{ val }}</li>
|
|
416
|
+
</ul>
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
| Переменная | Значение |
|
|
420
|
+
|---|---|
|
|
421
|
+
| `val` | значение свойства объекта |
|
|
422
|
+
| `$key` | строковый ключ свойства |
|
|
423
|
+
| `$index` | порядковый номер итерации |
|
|
424
|
+
|
|
425
|
+
#### Вложенные циклы
|
|
426
|
+
|
|
427
|
+
```html
|
|
428
|
+
<div #for="group in groups">
|
|
429
|
+
<h3>{{ group.name }}</h3>
|
|
430
|
+
<ul>
|
|
431
|
+
<li #for="item in group.items">{{ item }}</li>
|
|
432
|
+
</ul>
|
|
433
|
+
</div>
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
> **Переменная цикла изолирована.** После завершения `#for` переменная `item` удаляется. Если у компонента есть одноимённое свойство — оно восстанавливается.
|
|
437
|
+
|
|
438
|
+
#### Ключи: `#key`
|
|
439
|
+
|
|
440
|
+
Без ключа любое изменение коллекции пересоздаёт все строки: поля ввода теряют фокус и набранный текст. С `#key` строки с тем же ключом переиспользуются, создаются только новые, удаляются только пропавшие:
|
|
441
|
+
|
|
442
|
+
```html
|
|
443
|
+
<li #for="row in rows" #key="row.id">
|
|
444
|
+
<input #model="row.name">
|
|
445
|
+
</li>
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
Ключ должен быть уникален в пределах списка, на дубли выводится предупреждение.
|
|
449
|
+
|
|
450
|
+
Ключом может быть и сам элемент: `#key="row"`. Объекты сравниваются по ссылке на исходник, а не на прокси, поэтому строки без `id` (новые, ещё не сохранённые на сервере) не нужно помечать служебным полем:
|
|
451
|
+
|
|
452
|
+
```html
|
|
453
|
+
<li #for="row in rows" #key="row"><input #model="row.name"></li>
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
Одного совпадения ключа мало: строка переиспользуется, только если элемент - **тот же объект**. Позиция не важна. Строка, сдвинутая `unshift`, `splice` или сортировкой, переносится вместе с узлами, полями, фокусом и вложенными `<st-app>`: она получает новые `$index` и путь к элементу, её привязки перезапускаются. Если поле с фокусом пришлось переставить в DOM, фокус и выделение возвращаются ему.
|
|
457
|
+
|
|
458
|
+
> [!warning] Коллекция из метода или геттера, который каждый раз строит новые объекты
|
|
459
|
+
> `#for="row in visible()"`, где `visible()` возвращает `rows.map(r => ({ ...r }))`, копию через JSON или заново полученные с сервера данные, на каждом проходе отдаёт новые объекты. Ключи совпадают, но строки пересоздаются целиком: теряются фокус и набранный текст, анимации и прокрутка внутри строк "прыгают".
|
|
460
|
+
>
|
|
461
|
+
> Перебирайте реактивный список из конфига и меняйте его на месте (правка полей, `push`, `splice`). Фильтруйте через `#show` или `#if` внутри строки, а не новым массивом копий. Если данные приходят с сервера, переносите новые значения в существующие объекты, а не заменяйте их.
|
|
462
|
+
|
|
463
|
+
#### Двусторонняя привязка внутри цикла
|
|
464
|
+
|
|
465
|
+
Работает в рамках реактивного объекта:
|
|
466
|
+
|
|
467
|
+
```html
|
|
468
|
+
<li #for="todo in todos">
|
|
469
|
+
<input type="checkbox" #model="todo.done">
|
|
470
|
+
<span style="{{ todo.done ? 'text-decoration:line-through' : '' }}">{{ todo.text }}</span>
|
|
471
|
+
</li>
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
---
|
|
475
|
+
|
|
476
|
+
### `#model="prop"` — двусторонняя привязка
|
|
477
|
+
|
|
478
|
+
Синхронизирует поле формы с реактивным свойством. Тип преобразования зависит от типа элемента:
|
|
479
|
+
|
|
480
|
+
| Элемент / тип | Событие | Значение |
|
|
481
|
+
|---|---|---|
|
|
482
|
+
| `<input>` (text, email, …) | `input` | `string` |
|
|
483
|
+
| `<input type="number">`, `<input type="range">` | `input` | `number` (через `valueAsNumber`); пустое поле — `null` |
|
|
484
|
+
| `<input type="checkbox">` | `input` | `boolean` (`checked`) |
|
|
485
|
+
| `<input type="checkbox">`, в модели массив | `input` | массив `value` отмеченных флажков группы |
|
|
486
|
+
| `<input type="radio">` | `input` | `string` (`value` выбранного) |
|
|
487
|
+
| `<select>` | `change` | `string` (текущий `value`) |
|
|
488
|
+
| `<select multiple>` | `change` | массив `value` выбранных опций |
|
|
489
|
+
| `<textarea>` | `input` | `string` |
|
|
490
|
+
|
|
491
|
+
```html
|
|
492
|
+
<!-- text -->
|
|
493
|
+
<input type="text" #model="username">
|
|
494
|
+
|
|
495
|
+
<!-- число — автоматически парсится в Number -->
|
|
496
|
+
<input type="number" #model="age">
|
|
497
|
+
<input type="range" #model="volume" min="0" max="100">
|
|
498
|
+
|
|
499
|
+
<!-- checkbox — boolean -->
|
|
500
|
+
<input type="checkbox" #model="agreed">
|
|
501
|
+
|
|
502
|
+
<!-- select -->
|
|
503
|
+
<select #model="country">
|
|
504
|
+
<option value="ru">Россия</option>
|
|
505
|
+
<option value="us">США</option>
|
|
506
|
+
</select>
|
|
507
|
+
|
|
508
|
+
<!-- поле вложенного объекта -->
|
|
509
|
+
<input type="text" #model="user.profile.name">
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
`<select>` с опциями из `#for` работает: значение выставляется после отрисовки опций и сохраняется при их перерисовке.
|
|
513
|
+
|
|
514
|
+
**Множественный выбор.** У `<select multiple>` модель - массив значений выбранных опций. Флажки, у которых в модели массив, работают как группа: флажок отмечен, если его `value` есть в массиве, щелчок добавляет или убирает значение. Если в модели не массив, флажок остаётся `boolean`, как прежде.
|
|
515
|
+
|
|
516
|
+
```html
|
|
517
|
+
<select multiple #model="drivers">
|
|
518
|
+
<option #for="d in allDrivers" value="{{ d.id }}">{{ d.name }}</option>
|
|
519
|
+
</select>
|
|
520
|
+
|
|
521
|
+
<label #for="tag in allTags"><input type="checkbox" value="{{ tag }}" #model="tags"> {{ tag }}</label>
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
Значения - строки из `value`: числа из модели сравниваются по строковому виду, а обратно приходят строками. Группа получает новый массив на каждый щелчок, а не правку на месте.
|
|
525
|
+
|
|
526
|
+
---
|
|
527
|
+
|
|
528
|
+
### `:attr="value"` — атрибуты с привязкой
|
|
529
|
+
|
|
530
|
+
Атрибуты, начинающиеся с `:`, передают данные в компонент. Атрибут `:step` задаёт свойство `step`, kebab-case переводится в camelCase: `:initial-count` → `initialCount`. Писать `:initialCount` бесполезно: браузер приводит имена атрибутов к нижнему регистру.
|
|
531
|
+
|
|
532
|
+
Строка атрибута приводится к **типу значения из конфига**:
|
|
533
|
+
|
|
534
|
+
| Значение в конфиге | Строка атрибута становится |
|
|
535
|
+
|---|---|
|
|
536
|
+
| строка (`pin: ''`) | строкой как есть: `"0123"` → `'0123'`, `"true"` → `'true'` |
|
|
537
|
+
| число (`port: 0`) | `Number(...)`; нечисловая строка остаётся строкой |
|
|
538
|
+
| `boolean` (`open: false`) | `false` для `"false"`, `"0"`, `"null"`, `"undefined"`, иначе `true` |
|
|
539
|
+
| объект или массив | `JSON.parse(...)` |
|
|
540
|
+
| свойства нет в конфиге или там `null` | угадывается по виду: `"true"`/`"false"` → `boolean`, `"42"` → `number`, разбираемое JSON → объект, иначе строка |
|
|
541
|
+
|
|
542
|
+
Модификатор после точки задаёт приведение явно и перекрывает тип из конфига: `.string`, `.number`, `.boolean`, `.json`. Свойство называется по имени до точки.
|
|
543
|
+
|
|
544
|
+
```html
|
|
545
|
+
<st-app app="settings" :pin="0123" :port="8080" :options.json='{"a":1}' :code.string="007"></st-app>
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
**Пустое значение.** Пустой атрибут при монтировании берёт значение из конфига (см. ниже). Если атрибут стал пустым позже, например `:value="{{ draft }}"` при `draft = ''`, свойство получает `''`, а нестроковое свойство получает `null`.
|
|
549
|
+
|
|
550
|
+
#### `:attr` без значения — значение из прототипа
|
|
551
|
+
|
|
552
|
+
Если атрибут `:prop` при монтировании указан **без значения**, фреймворк берёт значение свойства `prop` из конфигурации `App.create()`. Объекты при этом сериализуются в JSON и синхронизируются двусторонне:
|
|
553
|
+
|
|
554
|
+
```html
|
|
555
|
+
<!-- :options без значения — значение берётся из конфига App.create() -->
|
|
556
|
+
<st-app app="myApp" :options></st-app>
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
```js
|
|
560
|
+
App.create({
|
|
561
|
+
app: 'myApp',
|
|
562
|
+
options: { theme: 'dark', limit: 10 }, // ← этот объект будет подставлен
|
|
563
|
+
template: `
|
|
564
|
+
<input #model="options.theme">
|
|
565
|
+
<p>Атрибут :options синхронизирован: {{ JSON.stringify(options) }}</p>
|
|
566
|
+
`
|
|
567
|
+
});
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
#### Реактивная передача данных от родителя к ребёнку
|
|
571
|
+
|
|
572
|
+
Самый важный паттерн для вложенных компонентов. Значение атрибута интерполируется через `{{ }}`:
|
|
573
|
+
|
|
574
|
+
```html
|
|
575
|
+
<!-- В шаблоне родительского компонента -->
|
|
576
|
+
<st-app app="child" :count="{{ sharedCount }}" :name="{{ userName }}"></st-app>
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
При изменении `sharedCount` в родителе атрибут `:count` на дочернем элементе обновляется автоматически, дочерний компонент получает новое значение.
|
|
580
|
+
|
|
581
|
+
---
|
|
582
|
+
|
|
583
|
+
### Boolean-атрибуты
|
|
584
|
+
|
|
585
|
+
Следующие атрибуты обрабатываются как булевы: при falsy-значении атрибут **удаляется** из DOM, при truthy — **добавляется** (со значением `""`):
|
|
586
|
+
|
|
587
|
+
```
|
|
588
|
+
disabled, checked, readonly, required, selected, hidden, open, autofocus
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
```html
|
|
592
|
+
<!-- если isValid === false → атрибут disabled удалится из кнопки -->
|
|
593
|
+
<button disabled="{{ !isValid }}">Отправить</button>
|
|
594
|
+
|
|
595
|
+
<!-- если isRequired === true → добавится required="" -->
|
|
596
|
+
<input type="text" required="{{ isRequired }}">
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
У `checked` и `selected` атрибут задаёт только начальное состояние: после клика пользователя браузер смотрит на свойство. Поэтому привязка выставляет и атрибут, и свойство (`input.checked`, `option.selected`), и флажок продолжает следовать данным после щелчков. То же для `value="{{ }}"` у `<input>`: после ввода поле показывает свойство `value`, и привязка обновляет его, когда меняются данные.
|
|
600
|
+
|
|
601
|
+
Привязка односторонняя. Если пользователь снял флажок, а данные не изменились, флажок останется снятым. Чтобы состояние и поле совпадали, используйте `#model` или меняйте данные в обработчике (`@change="on = $event.target.checked"`).
|
|
602
|
+
|
|
603
|
+
Если разметку собирает шаблонизатор, который сам разбирает булевы атрибуты (Astro), пишите `#attr="{ disabled: !isValid }"`: строка `disabled="{{ }}"` до App может не дойти.
|
|
604
|
+
|
|
605
|
+
---
|
|
606
|
+
|
|
607
|
+
### `#html="expr"` — сырой HTML
|
|
608
|
+
|
|
609
|
+
Записывает результат выражения в `innerHTML` элемента. Директивы и `{{ }}` внутри вставленной разметки не обрабатываются.
|
|
610
|
+
|
|
611
|
+
```html
|
|
612
|
+
<div #html="captchaWidget"></div>
|
|
613
|
+
```
|
|
614
|
+
|
|
615
|
+
> [!warning]
|
|
616
|
+
> Только для доверенной разметки. Пользовательский ввод через `#html` — это XSS.
|
|
617
|
+
|
|
618
|
+
---
|
|
619
|
+
|
|
620
|
+
### `#once` — одноразовая обработка
|
|
621
|
+
|
|
622
|
+
Элемент обрабатывается единожды при первом рендеринге. Атрибут снимается, реактивных эффектов не создаётся:
|
|
623
|
+
|
|
624
|
+
```html
|
|
625
|
+
<p #once>Этот текст никогда не обновится: {{ initialValue }}</p>
|
|
626
|
+
```
|
|
627
|
+
|
|
628
|
+
---
|
|
629
|
+
|
|
630
|
+
### `#pre` — пропуск поддерева
|
|
631
|
+
|
|
632
|
+
Элемент и всё его содержимое пропускаются при обработке директив. Используется для встраивания `{{ }}` как буквального текста (например, в примерах кода):
|
|
633
|
+
|
|
634
|
+
```html
|
|
635
|
+
<pre #pre>
|
|
636
|
+
Здесь {{ это }} не будет обработано как выражение
|
|
637
|
+
</pre>
|
|
638
|
+
```
|
|
639
|
+
|
|
640
|
+
---
|
|
641
|
+
|
|
642
|
+
## Жизненный цикл компонента
|
|
643
|
+
|
|
644
|
+
```
|
|
645
|
+
1. <st-app> добавлен в DOM (connectedCallback)
|
|
646
|
+
↓
|
|
647
|
+
Если <st-app> лежит внутри другого <st-app>, который ещё не взял шаблон, он ждёт:
|
|
648
|
+
родитель заберёт эту разметку в шаблон и создаст копии заново.
|
|
649
|
+
↓
|
|
650
|
+
2. #boot() — копирование конфига, оборачивание данных в Proxy
|
|
651
|
+
↓
|
|
652
|
+
3. Диспатч события 'setup' → вызов setup()
|
|
653
|
+
↓
|
|
654
|
+
4. Применение атрибутов `:attr` (разбор, типизация, создание реактивных свойств)
|
|
655
|
+
↓
|
|
656
|
+
5. Рендеринг шаблона (applyTemplate)
|
|
657
|
+
↓
|
|
658
|
+
6. Диспатч события 'rendered'
|
|
659
|
+
↓
|
|
660
|
+
7. MutationObserver следит за изменениями атрибутов `:*`
|
|
661
|
+
↓
|
|
662
|
+
8. После каждого прохода перерисовки - событие 'updated'
|
|
663
|
+
```
|
|
664
|
+
|
|
665
|
+
`updated` приходит после `rendered`, когда данные изменились и DOM их догнал: один раз на пачку изменений одного тика, без всплытия. Через него внешний код узнаёт, что разметка шаблона могла смениться: элементы `#if` и `#for` пересозданы, у модулей с `refresh()` появились новые узлы (см. "Модули внутри шаблона").
|
|
666
|
+
|
|
667
|
+
```
|
|
668
|
+
9. <st-app> удалён из DOM (disconnectedCallback)
|
|
669
|
+
↓
|
|
670
|
+
Очистка откладывается на микрозадачу. Если элемент к этому моменту снова
|
|
671
|
+
в DOM (перенос в другой контейнер, в Modal), ничего не снимается.
|
|
672
|
+
↓
|
|
673
|
+
Иначе — очистка всех эффектов, подписок, слушателей событий
|
|
674
|
+
↓
|
|
675
|
+
10. Возврат в DOM после очистки — шаблон собирается заново.
|
|
676
|
+
Подписки watch() из setup() не восстанавливаются: setup() повторно не вызывается.
|
|
677
|
+
```
|
|
678
|
+
|
|
679
|
+
### Модули внутри шаблона
|
|
680
|
+
|
|
681
|
+
Toggle, Modal, Mask, Validator, Select, Shape, Uploader, Observer и Typograf находят свои элементы при создании. App пересоздаёт узлы `#if` и `#for`, и о новых узлах модуль не узнает сам. Модули об App не знают, связь - через общий контракт:
|
|
682
|
+
|
|
683
|
+
- элементы передаются селектором или функцией (`trigger: () => this.querySelectorAll('[role=tab]')`): их можно пересканировать;
|
|
684
|
+
- `refresh()` пересканирует: новые элементы привязывает, ушедшие из DOM отпускает;
|
|
685
|
+
- `destroy()` снимает всё.
|
|
686
|
+
|
|
687
|
+
```js
|
|
688
|
+
App.create({
|
|
689
|
+
app: 'settings',
|
|
690
|
+
tabs: ['rules', 'keys'],
|
|
691
|
+
events: {
|
|
692
|
+
rendered() {
|
|
693
|
+
this.tabs_toggle = new Toggle({ trigger: () => this.querySelectorAll('[role=tab]'), group: 'radio', anchor: 'target' });
|
|
694
|
+
},
|
|
695
|
+
updated() { this.tabs_toggle.refresh(); },
|
|
696
|
+
},
|
|
697
|
+
});
|
|
698
|
+
```
|
|
699
|
+
|
|
700
|
+
Строки `#for` с `#key` переносятся, а не пересоздаются, поэтому состояние модуля на них (активная вкладка, маска поля) переживает сортировку. Строка без ключа и ветка `#if` создаются заново, и модуль поднимает их с начальным состоянием из разметки. Таблица модулей и рецепт для Vue - в `docs/README.md`.
|
|
701
|
+
|
|
702
|
+
### setup()
|
|
703
|
+
|
|
704
|
+
`setup()` — правильное место для:
|
|
705
|
+
- вызовов `this.watch()`
|
|
706
|
+
- инициализации данных на основе переданных атрибутов
|
|
707
|
+
- первичного вызова `this.applyTemplate()`
|
|
708
|
+
|
|
709
|
+
```js
|
|
710
|
+
App.create({
|
|
711
|
+
app: 'myApp',
|
|
712
|
+
items: [],
|
|
713
|
+
|
|
714
|
+
async setup() {
|
|
715
|
+
// данные из :attr уже доступны здесь
|
|
716
|
+
this.items = await fetch('/api/items').then(r => r.json());
|
|
717
|
+
|
|
718
|
+
this.watch('items', (newVal) => {
|
|
719
|
+
console.log('items changed:', newVal.length);
|
|
720
|
+
});
|
|
721
|
+
},
|
|
722
|
+
|
|
723
|
+
template: `<ul><li #for="item in items">{{ item.name }}</li></ul>`
|
|
724
|
+
});
|
|
725
|
+
```
|
|
726
|
+
|
|
727
|
+
---
|
|
728
|
+
|
|
729
|
+
## watch() — наблюдатель изменений
|
|
730
|
+
|
|
731
|
+
```js
|
|
732
|
+
let unwatch = this.watch(source, callback, options?)
|
|
733
|
+
```
|
|
734
|
+
|
|
735
|
+
| Параметр | Описание |
|
|
736
|
+
|---|---|
|
|
737
|
+
| `source` | Что наблюдать (см. варианты ниже) |
|
|
738
|
+
| `callback(newVal, oldVal, unwatch)` | Вызывается при изменении; третий аргумент `unwatch()` — остановить наблюдение |
|
|
739
|
+
| `options.immediate` | `boolean` — вызвать `callback` сразу при подписке |
|
|
740
|
+
| `options.deep` | `boolean` — глубокое наблюдение за объектом/массивом |
|
|
741
|
+
|
|
742
|
+
Возвращаемое значение — функция `unwatch()`, вызов которой снимает подписку.
|
|
743
|
+
|
|
744
|
+
### Варианты `source`
|
|
745
|
+
|
|
746
|
+
#### Строка — имя свойства
|
|
747
|
+
|
|
748
|
+
```js
|
|
749
|
+
this.watch('count', (newVal, oldVal, unwatch) => {
|
|
750
|
+
console.log(`count: ${oldVal} → ${newVal}`);
|
|
751
|
+
|
|
752
|
+
// автоматически отменить наблюдение при достижении 10
|
|
753
|
+
if (newVal >= 10) unwatch();
|
|
754
|
+
}, { immediate: true }); // ← вызвать callback сразу
|
|
755
|
+
```
|
|
756
|
+
|
|
757
|
+
#### Строка — путь к вложенному свойству
|
|
758
|
+
|
|
759
|
+
```js
|
|
760
|
+
this.watch('user.name', (newVal) => {
|
|
761
|
+
console.log('Имя изменилось:', newVal);
|
|
762
|
+
});
|
|
763
|
+
```
|
|
764
|
+
|
|
765
|
+
#### Строка — глубокое наблюдение за объектом
|
|
766
|
+
|
|
767
|
+
```js
|
|
768
|
+
this.watch('user', (newVal, oldVal) => {
|
|
769
|
+
// вызывается при изменении любого вложенного свойства
|
|
770
|
+
console.log('Объект user изменился');
|
|
771
|
+
}, { deep: true });
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
#### Строка `'method()'` — перехват вызова метода
|
|
775
|
+
|
|
776
|
+
```js
|
|
777
|
+
this.watch('save()', (args, result, unwatch) => {
|
|
778
|
+
console.log('save() вызван с аргументами:', args);
|
|
779
|
+
console.log('Вернул:', result);
|
|
780
|
+
});
|
|
781
|
+
```
|
|
782
|
+
|
|
783
|
+
> `callback` при перехвате метода получает: `args` — массив аргументов, `result` — возвращённое значение (или Promise).
|
|
784
|
+
|
|
785
|
+
#### Функция-геттер
|
|
786
|
+
|
|
787
|
+
Автоматически отслеживает использованные реактивные свойства:
|
|
788
|
+
|
|
789
|
+
```js
|
|
790
|
+
this.watch(
|
|
791
|
+
() => this.firstName + ' ' + this.lastName, // ← геттер-вычисление
|
|
792
|
+
(newFullName, oldFullName) => {
|
|
793
|
+
console.log('ФИО изменилось:', newFullName);
|
|
794
|
+
}
|
|
795
|
+
);
|
|
796
|
+
```
|
|
797
|
+
|
|
798
|
+
### Полный пример watch()
|
|
799
|
+
|
|
800
|
+
```js
|
|
801
|
+
App.create({
|
|
802
|
+
app: 'watchDemo',
|
|
803
|
+
count: 0,
|
|
804
|
+
user: { name: 'Гость', role: 'user' },
|
|
805
|
+
firstName: 'Иван',
|
|
806
|
+
lastName: 'Петров',
|
|
807
|
+
|
|
808
|
+
setup() {
|
|
809
|
+
// 1. Наблюдение за примитивом, автостоп при 5
|
|
810
|
+
this.watch('count', (newVal, oldVal, unwatch) => {
|
|
811
|
+
console.log('[count]', oldVal, '->', newVal);
|
|
812
|
+
if (newVal >= 5) unwatch();
|
|
813
|
+
}, { immediate: true });
|
|
814
|
+
|
|
815
|
+
// 2. Глубокое наблюдение за объектом
|
|
816
|
+
this.watch('user', (n) => console.log('[user deep]', n), { deep: true });
|
|
817
|
+
|
|
818
|
+
// 3. Путь к вложенному свойству
|
|
819
|
+
this.watch('user.name', (n) => console.log('[user.name]', n));
|
|
820
|
+
|
|
821
|
+
// 4. Функция-геттер
|
|
822
|
+
this.watch(
|
|
823
|
+
() => this.firstName + ' ' + this.lastName,
|
|
824
|
+
(v) => console.log('[fullName]', v)
|
|
825
|
+
);
|
|
826
|
+
|
|
827
|
+
// 5. Перехват метода
|
|
828
|
+
this.watch('save()', (args, result) => console.log('[save()]', result));
|
|
829
|
+
},
|
|
830
|
+
|
|
831
|
+
save() { return { ok: true, ts: Date.now() }; },
|
|
832
|
+
|
|
833
|
+
template: `
|
|
834
|
+
<div>
|
|
835
|
+
<button @click="count++">count: {{ count }}</button>
|
|
836
|
+
<input #model="user.name">
|
|
837
|
+
<input #model="firstName"> <input #model="lastName">
|
|
838
|
+
<button @click="save()">save()</button>
|
|
839
|
+
</div>
|
|
840
|
+
`
|
|
841
|
+
});
|
|
842
|
+
```
|
|
843
|
+
|
|
844
|
+
---
|
|
845
|
+
|
|
846
|
+
## applyTemplate() — переключение шаблонов
|
|
847
|
+
|
|
848
|
+
```js
|
|
849
|
+
this.applyTemplate(html?)
|
|
850
|
+
```
|
|
851
|
+
|
|
852
|
+
- `applyTemplate(htmlStr)` — применяет переданный HTML как шаблон. Старые эффекты и слушатели очищаются. **Базовый шаблон при этом не меняется.**
|
|
853
|
+
- `applyTemplate()` (без аргументов) — возвращается к базовому шаблону из `App.create()`.
|
|
854
|
+
|
|
855
|
+
Реактивные данные (`this.count`, `this.name`, и т.д.) **сохраняются** при любом переключении шаблона.
|
|
856
|
+
|
|
857
|
+
```js
|
|
858
|
+
const TMPL_LOADING = `
|
|
859
|
+
<div style="text-align:center;padding:48px;">
|
|
860
|
+
<p>⏳ Загрузка...</p>
|
|
861
|
+
</div>`;
|
|
862
|
+
|
|
863
|
+
const TMPL_SETTINGS = `
|
|
864
|
+
<div>
|
|
865
|
+
<h3>⚙️ Настройки</h3>
|
|
866
|
+
<label>Имя: <input #model="name"></label>
|
|
867
|
+
<button @click="applyTemplate()">← Назад</button>
|
|
868
|
+
</div>`;
|
|
869
|
+
|
|
870
|
+
App.create({
|
|
871
|
+
app: 'app',
|
|
872
|
+
name: 'Пользователь',
|
|
873
|
+
|
|
874
|
+
setup() {
|
|
875
|
+
// Показать экран загрузки, затем вернуться к основному
|
|
876
|
+
this.applyTemplate(TMPL_LOADING);
|
|
877
|
+
setTimeout(() => this.applyTemplate(), 1500);
|
|
878
|
+
},
|
|
879
|
+
|
|
880
|
+
template: `
|
|
881
|
+
<div>
|
|
882
|
+
<h3>🏠 Главный экран</h3>
|
|
883
|
+
<p>Привет, {{ name }}!</p>
|
|
884
|
+
<button @click="applyTemplate(TMPL_SETTINGS)">⚙️ Настройки</button>
|
|
885
|
+
</div>
|
|
886
|
+
`
|
|
887
|
+
});
|
|
888
|
+
```
|
|
889
|
+
|
|
890
|
+
---
|
|
891
|
+
|
|
892
|
+
## Вложенные компоненты
|
|
893
|
+
|
|
894
|
+
`<st-app>` можно вкладывать внутрь другого `<st-app>`: в строку `template` или в разметку родителя, которую он берёт шаблоном, в том числе внутрь `#for`. Вложенный компонент не отрисовывается, пока родитель не взял шаблон, поэтому каждая копия собирается из исходной разметки. Данные передаются через атрибуты `:attr`, события — через `dispatchEvent` и `@имя.self` (см. `@event`).
|
|
895
|
+
|
|
896
|
+
### Передача данных через `:attr="{{ expr }}"`
|
|
897
|
+
|
|
898
|
+
```js
|
|
899
|
+
// Родитель
|
|
900
|
+
App.create({
|
|
901
|
+
app: 'parent',
|
|
902
|
+
sharedCount: 0,
|
|
903
|
+
userName: 'Пользователь',
|
|
904
|
+
|
|
905
|
+
template: `
|
|
906
|
+
<div>
|
|
907
|
+
<p>Родитель: {{ sharedCount }}</p>
|
|
908
|
+
<button @click="sharedCount++">+1</button>
|
|
909
|
+
<input #model="userName">
|
|
910
|
+
|
|
911
|
+
<!-- Передача реактивных значений дочернему компоненту -->
|
|
912
|
+
<st-app app="child"
|
|
913
|
+
:count="{{ sharedCount }}"
|
|
914
|
+
:name="{{ userName }}">
|
|
915
|
+
</st-app>
|
|
916
|
+
</div>
|
|
917
|
+
`
|
|
918
|
+
});
|
|
919
|
+
|
|
920
|
+
// Дочерний
|
|
921
|
+
App.create({
|
|
922
|
+
app: 'child',
|
|
923
|
+
count: 0, // будет перезаписано из :count
|
|
924
|
+
name: '', // будет перезаписано из :name
|
|
925
|
+
|
|
926
|
+
template: `
|
|
927
|
+
<div style="border: 1px solid #ccc; padding: 10px; margin-top: 10px;">
|
|
928
|
+
<p>Дочерний получил: count={{ count }}, name={{ name }}</p>
|
|
929
|
+
</div>
|
|
930
|
+
`
|
|
931
|
+
});
|
|
932
|
+
```
|
|
933
|
+
|
|
934
|
+
При изменении `sharedCount` или `userName` в родителе дочерний компонент автоматически получает новые значения.
|
|
935
|
+
|
|
936
|
+
### Трёхуровневая вложенность
|
|
937
|
+
|
|
938
|
+
```html
|
|
939
|
+
<!-- grandparent → parent2 → grandchild -->
|
|
940
|
+
<st-app app="grandparent"></st-app>
|
|
941
|
+
```
|
|
942
|
+
|
|
943
|
+
```js
|
|
944
|
+
App.create({
|
|
945
|
+
app: 'grandparent', data: 42,
|
|
946
|
+
template: `
|
|
947
|
+
<div>
|
|
948
|
+
<button @click="data = Math.random() * 100 | 0">🎲</button>
|
|
949
|
+
<st-app app="parent2" :data="{{ data }}"></st-app>
|
|
950
|
+
</div>
|
|
951
|
+
`
|
|
952
|
+
});
|
|
953
|
+
|
|
954
|
+
App.create({
|
|
955
|
+
app: 'parent2', data: 0,
|
|
956
|
+
template: `<st-app app="grandchild" :data="{{ data }}"></st-app>`
|
|
957
|
+
});
|
|
958
|
+
|
|
959
|
+
App.create({
|
|
960
|
+
app: 'grandchild', data: 0,
|
|
961
|
+
template: `<p>Финальные данные: <strong>{{ data }}</strong></p>`
|
|
962
|
+
});
|
|
963
|
+
```
|
|
964
|
+
|
|
965
|
+
---
|
|
966
|
+
|
|
967
|
+
## innerHTML как шаблон
|
|
968
|
+
|
|
969
|
+
Если `template: ''` (или `template` не задан), а у элемента `<st-app>` есть содержимое — оно будет использовано как шаблон:
|
|
970
|
+
|
|
971
|
+
```html
|
|
972
|
+
<st-app app="inlineTemplate">
|
|
973
|
+
<div>
|
|
974
|
+
<h3>{{ title }}</h3>
|
|
975
|
+
<input type="text" #model="message">
|
|
976
|
+
<p>{{ message }}</p>
|
|
977
|
+
</div>
|
|
978
|
+
</st-app>
|
|
979
|
+
```
|
|
980
|
+
|
|
981
|
+
```js
|
|
982
|
+
App.create({
|
|
983
|
+
app: 'inlineTemplate',
|
|
984
|
+
title: 'Заголовок',
|
|
985
|
+
message: 'Привет!',
|
|
986
|
+
template: '' // ← пустой шаблон → берётся innerHTML
|
|
987
|
+
});
|
|
988
|
+
```
|
|
989
|
+
|
|
990
|
+
Также работает без `App.create()` совсем — тогда атрибуты `:attr` задают данные напрямую:
|
|
991
|
+
|
|
992
|
+
```html
|
|
993
|
+
<!-- Без App.create() — данные через атрибуты, шаблон из innerHTML -->
|
|
994
|
+
<st-app :name="Иван" :count="5">
|
|
995
|
+
<p>{{ name }}: {{ count }}</p>
|
|
996
|
+
<button @click="count++">+1</button>
|
|
997
|
+
</st-app>
|
|
998
|
+
```
|
|
999
|
+
|
|
1000
|
+
---
|
|
1001
|
+
|
|
1002
|
+
## Публичный API экземпляра
|
|
1003
|
+
|
|
1004
|
+
### `this.watch(source, callback, options?)` — подробно описан выше
|
|
1005
|
+
|
|
1006
|
+
### `this.applyTemplate(html?)` — подробно описан выше
|
|
1007
|
+
|
|
1008
|
+
### `this.nextTick()`
|
|
1009
|
+
|
|
1010
|
+
Обновление DOM асинхронное: изменения копятся и применяются в микрозадаче. `nextTick()` возвращает промис, который разрешается, когда эффекты и колбэки `watch()` отработали и DOM соответствует данным:
|
|
1011
|
+
|
|
1012
|
+
```js
|
|
1013
|
+
app.count = 5;
|
|
1014
|
+
await app.nextTick();
|
|
1015
|
+
app.querySelector('p').textContent; // '5'
|
|
1016
|
+
```
|
|
1017
|
+
|
|
1018
|
+
Первую отрисовку компонента и вложенных `<st-app>` он не ждёт. Для неё есть событие `rendered`: подписка после отрисовки срабатывает сразу.
|
|
1019
|
+
|
|
1020
|
+
### `this.clone(options?)`
|
|
1021
|
+
|
|
1022
|
+
Создаёт копию компонента через `App.extend()`, используя `app` из текущего атрибута `app`:
|
|
1023
|
+
|
|
1024
|
+
```js
|
|
1025
|
+
// Внутри метода компонента:
|
|
1026
|
+
this.clone({ label: 'Клон', count: 999 });
|
|
1027
|
+
```
|
|
1028
|
+
|
|
1029
|
+
### `this.unwatch()`
|
|
1030
|
+
|
|
1031
|
+
Снимает **все** активные наблюдатели, установленные через `watch()` на данном экземпляре — key-подписки, getter-эффекты и перехваты методов. Перехваченные методы восстанавливаются к своим оригинальным реализациям.
|
|
1032
|
+
|
|
1033
|
+
```js
|
|
1034
|
+
setup() {
|
|
1035
|
+
this.watch('count', (n) => console.log('count:', n));
|
|
1036
|
+
this.watch('user', (n) => console.log('user:', n), { deep: true });
|
|
1037
|
+
this.watch('save()', (args, result) => console.log('saved:', result));
|
|
1038
|
+
|
|
1039
|
+
// ... позже снять сразу все:
|
|
1040
|
+
this.unwatch();
|
|
1041
|
+
}
|
|
1042
|
+
```
|
|
1043
|
+
|
|
1044
|
+
> **Отличие от `unwatch()`, возвращаемой `watch()`:** вызов отдельной функции `unwatch` снимает одну конкретную подписку. `this.unwatch()` снимает сразу все.
|
|
1045
|
+
|
|
1046
|
+
### `this.hasWatchers()`
|
|
1047
|
+
|
|
1048
|
+
Возвращает `number` — суммарное количество активных наблюдателей (key-подписки + getter-подписки + перехваты методов). Полезно для отладки и условной проверки.
|
|
1049
|
+
|
|
1050
|
+
```js
|
|
1051
|
+
setup() {
|
|
1052
|
+
this.watch('count', () => {});
|
|
1053
|
+
this.watch('name', () => {});
|
|
1054
|
+
this.watch('save()', () => {});
|
|
1055
|
+
|
|
1056
|
+
console.log(this.hasWatchers()); // 3
|
|
1057
|
+
|
|
1058
|
+
this.unwatch();
|
|
1059
|
+
console.log(this.hasWatchers()); // 0
|
|
1060
|
+
}
|
|
1061
|
+
```
|
|
1062
|
+
|
|
1063
|
+
### `this.watched(source, callback, options?)`
|
|
1064
|
+
|
|
1065
|
+
Комбинированный метод «заменить подписку»: сначала снимает все существующие подписки для указанного `source`, затем добавляет новую. Сигнатура и варианты `source` идентичны `watch()`.
|
|
1066
|
+
|
|
1067
|
+
Полезен при повторной инициализации — не допускает дублирования наблюдателей:
|
|
1068
|
+
|
|
1069
|
+
```js
|
|
1070
|
+
// Обычный watch — при повторном вызове добавляет вторую подписку
|
|
1071
|
+
this.watch('count', handlerA);
|
|
1072
|
+
this.watch('count', handlerB); // теперь оба активны
|
|
1073
|
+
|
|
1074
|
+
// watched — автоматически снимает предыдущую перед добавлением
|
|
1075
|
+
this.watched('count', handlerA);
|
|
1076
|
+
this.watched('count', handlerB); // handlerA снят, активен только handlerB
|
|
1077
|
+
```
|
|
1078
|
+
|
|
1079
|
+
```js
|
|
1080
|
+
// Поддерживаются все варианты source:
|
|
1081
|
+
this.watched('prop', callback);
|
|
1082
|
+
this.watched('obj.nested', callback, { deep: true });
|
|
1083
|
+
this.watched(() => this.a + this.b, callback);
|
|
1084
|
+
this.watched('method()', (args, result) => { ... });
|
|
1085
|
+
```
|
|
1086
|
+
|
|
1087
|
+
### `this.dispatchEvent(event, detail?, options?)`
|
|
1088
|
+
|
|
1089
|
+
Переопределённый `dispatchEvent`. Если первый аргумент — строка, создаёт и диспатчит `CustomEvent` (по умолчанию не всплывает, `cancelable: true`). Если передан готовый объект `Event` — диспатчит его напрямую. Возвращает `boolean` (результат нативного `dispatchEvent`).
|
|
1090
|
+
|
|
1091
|
+
```js
|
|
1092
|
+
let ok = this.dispatchEvent('my-event', { value: 42 }, { bubbles: true });
|
|
1093
|
+
if (ok) {
|
|
1094
|
+
// событие не было отменено через preventDefault()
|
|
1095
|
+
}
|
|
1096
|
+
```
|
|
1097
|
+
|
|
1098
|
+
```js
|
|
1099
|
+
// Подписка слушателя:
|
|
1100
|
+
document.querySelector('st-app').addEventListener('my-event', e => {
|
|
1101
|
+
console.log(e.detail.value); // 42
|
|
1102
|
+
});
|
|
1103
|
+
```
|
|
1104
|
+
|
|
1105
|
+
### `this.attrs` — объект для работы с атрибутами
|
|
1106
|
+
|
|
1107
|
+
| Метод | Описание |
|
|
1108
|
+
|---|---|
|
|
1109
|
+
| `this.attrs.get(name)` | `getAttribute(name)` |
|
|
1110
|
+
| `this.attrs.set(name, value)` | `setAttribute(name, value)` |
|
|
1111
|
+
| `this.attrs.remove(name)` | `removeAttribute(name)` |
|
|
1112
|
+
| `this.attrs.has(name)` | `hasAttribute(name)` |
|
|
1113
|
+
| `this.attrs.toggle(name, force?)` | переключить атрибут |
|
|
1114
|
+
| `this.attrs.keys()` | массив имён всех атрибутов |
|
|
1115
|
+
| `this.attrs.entries()` | массив пар `[name, value]` |
|
|
1116
|
+
|
|
1117
|
+
```js
|
|
1118
|
+
setup() {
|
|
1119
|
+
// Чтение произвольных атрибутов, заданных на <st-app>
|
|
1120
|
+
let mode = this.attrs.get('data-mode') || 'default';
|
|
1121
|
+
}
|
|
1122
|
+
```
|
|
1123
|
+
|
|
1124
|
+
### `this.template` — геттер базового шаблона
|
|
1125
|
+
|
|
1126
|
+
Возвращает строку базового шаблона, установленного при инициализации:
|
|
1127
|
+
|
|
1128
|
+
```js
|
|
1129
|
+
let baseHtml = this.template;
|
|
1130
|
+
```
|
|
1131
|
+
|
|
1132
|
+
### `this.cycleAttribute(name, value1?, value2?)`
|
|
1133
|
+
|
|
1134
|
+
Переключает атрибут между `value1` и `value2`. Без значений — переключает наличие атрибута:
|
|
1135
|
+
|
|
1136
|
+
```js
|
|
1137
|
+
this.cycleAttribute('data-mode', 'dark', 'light');
|
|
1138
|
+
this.cycleAttribute('hidden');
|
|
1139
|
+
```
|
|
1140
|
+
|
|
1141
|
+
`toggleAttribute(name, force?)` работает по стандарту: `el.toggleAttribute('hidden', false)` снимает атрибут. Вызов со строковыми значениями (`toggleAttribute('data-mode', 'dark', 'light')`) оставлен для совместимости и передаётся в `cycleAttribute`.
|
|
1142
|
+
|
|
1143
|
+
---
|
|
1144
|
+
|
|
1145
|
+
## Подводные камни
|
|
1146
|
+
|
|
1147
|
+
- **Шаблон и CSP.** Выражения компилируются через `new Function` и `with`, поэтому странице нужен `script-src 'unsafe-eval'`. Со строгим CSP `App` не работает.
|
|
1148
|
+
- **Реактивны только поля конфига.** Свойство, которого нет в `App.create()` (`this.loaded = true` в `setup()`), шаблон прочитает, но при изменении не перерисует. При первом чтении такого свойства из шаблона в консоль выводится предупреждение. Объявите поле в конфиге (`loaded: false`). Для вычисляемого состояния используйте геттер или `watch(() => выражение, cb)`.
|
|
1149
|
+
- **Ожидание перерисовки.** После изменения данных DOM ещё старый. Перед проверкой DOM вызовите `await this.nextTick()`.
|
|
1150
|
+
- **Имена переменных шаблона.** Выражения видят свойства компонента, в том числе унаследованные от `HTMLElement`: `id`, `title`, `hidden`, `children`, `dataset`, `remove()`, `append()`. Свойство конфига с таким именем перекрывает родное. А чтение неописанного в конфиге `title` вернёт атрибут элемента, а не `undefined`.
|
|
1151
|
+
- **Сравнение по ссылке.** Вложенные объекты отдаются через `Proxy`. Для одного и того же пути прокси один, поэтому `items.indexOf(item)` внутри шаблона и методов работает. Сравнивать прокси с исходным объектом, переданным в конфиг, бесполезно: это разные ссылки. Исходник даёт `App.toRaw(value)`, копию без прокси — `App.snapshot(value)`.
|
|
1152
|
+
- **Методы в шаблоне.** `{{ shown('rules') }}` перерисовывается, когда меняются реактивные поля, которые метод прочитал (`this.rules`, `this.query`): метод выполняется внутри выражения, и его чтения отслеживаются, как в геттере. Сам вызов из шаблона других перерисовок не порождает. Вызов метода из обработчика события или из кода перерисовывает выражения, которые этот метод вызывают. Состояние, от которого зависит результат, держите в реактивных полях: обычное свойство и `window` не отслеживаются.
|
|
1153
|
+
- **`#if` пересоздаёт ветку.** Набранный текст и фокус внутри скрытой ветки теряются. Чтобы их сохранить, используйте `#show`.
|
|
1154
|
+
- **Поле, которое само выключает свой `#if`.** Если условие ветки зависит от значения, которое правит поле внутри неё (`<textarea #if="!text || editing" #model="text">`), то на первом символе ветка пропадает и поле теряет фокус. Обработчики этого же события (`@input` на поле и на предках внутри ветки) всё равно вызываются, но вернувшаяся ветка — уже новое поле без фокуса. Флаг ставьте раньше, до изменения значения (`@focus="editing = true"` или `@beforeinput`), или используйте `#show`.
|
|
1155
|
+
- **Списки с полями ввода - с `#key`.** Без ключа добавление строки пересоздаёт весь список. Ключ сохраняет строку, пока элемент - тот же объект, даже если строка сместилась. Нет `id` - ключом служит сам элемент: `#key="row"`. Метод, который каждый раз возвращает копии, пересоздаёт строки и с ключом (см. "Ключи: `#key`").
|
|
1156
|
+
- **Имя данных совпало с опцией.** `events`, `helpers`, `template`, `setup`, `app` - опции `App.create()`. Данные с таким именем вызывают `TypeError` при регистрации, переименуйте поле.
|
|
1157
|
+
- **Модули в шаблоне.** Toggle, Mask и другие модули не видят узлы, которые App создал после них. Вызывайте `refresh()` в событии `updated` (см. "Модули внутри шаблона").
|
|
1158
|
+
- **Долгое отключение.** Если `<st-app>` вынули из DOM и вернули в другой задаче, шаблон собирается заново, а подписки `watch()` из `setup()` пропадают. Перенос в той же задаче (`append` в другой контейнер, в `Modal`) безопасен.
|
|
1159
|
+
|
|
1160
|
+
---
|
|
1161
|
+
|
|
1162
|
+
## Комплексные примеры
|
|
1163
|
+
|
|
1164
|
+
### Todo-список
|
|
1165
|
+
|
|
1166
|
+
```js
|
|
1167
|
+
App.create({
|
|
1168
|
+
app: 'todo',
|
|
1169
|
+
todos: [
|
|
1170
|
+
{ id: 1, text: 'Изучить фреймворк', done: true },
|
|
1171
|
+
{ id: 2, text: 'Создать приложение', done: false }
|
|
1172
|
+
],
|
|
1173
|
+
newTodo: '',
|
|
1174
|
+
filter: 'all',
|
|
1175
|
+
|
|
1176
|
+
get filteredTodos() {
|
|
1177
|
+
if (this.filter === 'active') return this.todos.filter(t => !t.done);
|
|
1178
|
+
if (this.filter === 'completed') return this.todos.filter(t => t.done);
|
|
1179
|
+
return this.todos;
|
|
1180
|
+
},
|
|
1181
|
+
|
|
1182
|
+
get stats() {
|
|
1183
|
+
return {
|
|
1184
|
+
total: this.todos.length,
|
|
1185
|
+
active: this.todos.filter(t => !t.done).length,
|
|
1186
|
+
completed: this.todos.filter(t => t.done).length
|
|
1187
|
+
};
|
|
1188
|
+
},
|
|
1189
|
+
|
|
1190
|
+
addTodo() {
|
|
1191
|
+
if (!this.newTodo.trim()) return;
|
|
1192
|
+
this.todos.push({ id: Date.now(), text: this.newTodo.trim(), done: false });
|
|
1193
|
+
this.newTodo = '';
|
|
1194
|
+
},
|
|
1195
|
+
|
|
1196
|
+
removeTodo(id) {
|
|
1197
|
+
let idx = this.todos.findIndex(t => t.id === id);
|
|
1198
|
+
if (idx !== -1) this.todos.splice(idx, 1);
|
|
1199
|
+
},
|
|
1200
|
+
|
|
1201
|
+
clearCompleted() {
|
|
1202
|
+
this.todos = this.todos.filter(t => !t.done);
|
|
1203
|
+
},
|
|
1204
|
+
|
|
1205
|
+
template: `
|
|
1206
|
+
<div>
|
|
1207
|
+
<input #model="newTodo" placeholder="Что сделать?"
|
|
1208
|
+
@keyup="if ($event.key === 'Enter') addTodo()">
|
|
1209
|
+
<button @click="addTodo()">➕ Добавить</button>
|
|
1210
|
+
|
|
1211
|
+
<div style="margin: 10px 0;">
|
|
1212
|
+
<button @click="filter = 'all'">Все ({{ stats.total }})</button>
|
|
1213
|
+
<button @click="filter = 'active'">Активные ({{ stats.active }})</button>
|
|
1214
|
+
<button @click="filter = 'completed'">Завершённые ({{ stats.completed }})</button>
|
|
1215
|
+
</div>
|
|
1216
|
+
|
|
1217
|
+
<ul>
|
|
1218
|
+
<li #for="todo in filteredTodos"
|
|
1219
|
+
style="display:flex;align-items:center;gap:10px;">
|
|
1220
|
+
<input type="checkbox" #model="todo.done">
|
|
1221
|
+
<span style="{{ todo.done ? 'text-decoration:line-through;color:#999' : '' }}">
|
|
1222
|
+
{{ todo.text }}
|
|
1223
|
+
</span>
|
|
1224
|
+
<button @click="removeTodo(todo.id)">🗑️</button>
|
|
1225
|
+
</li>
|
|
1226
|
+
</ul>
|
|
1227
|
+
|
|
1228
|
+
<p #show="filteredTodos.length === 0" style="color:#999;">Задач нет</p>
|
|
1229
|
+
<button #show="stats.completed > 0" @click="clearCompleted()">
|
|
1230
|
+
Очистить завершённые
|
|
1231
|
+
</button>
|
|
1232
|
+
</div>
|
|
1233
|
+
`
|
|
1234
|
+
});
|
|
1235
|
+
```
|
|
1236
|
+
|
|
1237
|
+
### Вложенные реактивные объекты
|
|
1238
|
+
|
|
1239
|
+
```js
|
|
1240
|
+
App.create({
|
|
1241
|
+
app: 'nested',
|
|
1242
|
+
user: {
|
|
1243
|
+
profile: { name: 'Иван', age: 25 },
|
|
1244
|
+
settings: { theme: 'dark', notifications: true }
|
|
1245
|
+
},
|
|
1246
|
+
|
|
1247
|
+
toggleTheme() {
|
|
1248
|
+
this.user.settings.theme =
|
|
1249
|
+
this.user.settings.theme === 'dark' ? 'light' : 'dark';
|
|
1250
|
+
},
|
|
1251
|
+
|
|
1252
|
+
template: `
|
|
1253
|
+
<div>
|
|
1254
|
+
<input #model="user.profile.name">
|
|
1255
|
+
<input type="number" #model="user.profile.age">
|
|
1256
|
+
<input type="checkbox" #model="user.settings.notifications">
|
|
1257
|
+
<button @click="toggleTheme()">Тема: {{ user.settings.theme }}</button>
|
|
1258
|
+
<pre>{{ JSON.stringify(user, null, 2) }}</pre>
|
|
1259
|
+
</div>
|
|
1260
|
+
`
|
|
1261
|
+
});
|
|
1262
|
+
```
|
|
1263
|
+
|
|
1264
|
+
### applyTemplate — многоэкранный интерфейс
|
|
1265
|
+
|
|
1266
|
+
```js
|
|
1267
|
+
const TMPL_LOADING = `<div style="text-align:center;padding:48px;">⏳ Загрузка...</div>`;
|
|
1268
|
+
const TMPL_SETTINGS = `
|
|
1269
|
+
<div>
|
|
1270
|
+
<h3>⚙️ Настройки</h3>
|
|
1271
|
+
<label>Имя: <input #model="name"></label>
|
|
1272
|
+
<select #model="theme">
|
|
1273
|
+
<option value="light">Светлая</option>
|
|
1274
|
+
<option value="dark">Тёмная</option>
|
|
1275
|
+
</select>
|
|
1276
|
+
<button @click="applyTemplate()">← Назад</button>
|
|
1277
|
+
</div>`;
|
|
1278
|
+
|
|
1279
|
+
App.create({
|
|
1280
|
+
app: 'screens',
|
|
1281
|
+
name: 'Пользователь',
|
|
1282
|
+
theme: 'light',
|
|
1283
|
+
counter: 0,
|
|
1284
|
+
|
|
1285
|
+
setup() {
|
|
1286
|
+
this.applyTemplate(TMPL_LOADING);
|
|
1287
|
+
setTimeout(() => this.applyTemplate(), 1500);
|
|
1288
|
+
},
|
|
1289
|
+
|
|
1290
|
+
template: `
|
|
1291
|
+
<div>
|
|
1292
|
+
<h3>🏠 Главный экран</h3>
|
|
1293
|
+
<p>Привет, {{ name }}! Счётчик: {{ counter }}</p>
|
|
1294
|
+
<button @click="counter++">+1</button>
|
|
1295
|
+
<button @click="applyTemplate(TMPL_SETTINGS)">⚙️ Настройки</button>
|
|
1296
|
+
<button @click="applyTemplate(TMPL_LOADING); setTimeout(() => applyTemplate(), 1500)">
|
|
1297
|
+
🔄 Перезагрузить
|
|
1298
|
+
</button>
|
|
1299
|
+
</div>
|
|
1300
|
+
`
|
|
1301
|
+
});
|
|
1302
|
+
```
|
|
1303
|
+
|
|
1304
|
+
---
|
|
1305
|
+
|
|
1306
|
+
## Быстрая шпаргалка
|
|
1307
|
+
|
|
1308
|
+
```html
|
|
1309
|
+
<!-- Монтирование -->
|
|
1310
|
+
<st-app app="myApp"></st-app>
|
|
1311
|
+
<st-app app="myApp" :prop="value" :number="42" :flag="true"></st-app>
|
|
1312
|
+
|
|
1313
|
+
<!-- Интерполяция -->
|
|
1314
|
+
{{ expression }}
|
|
1315
|
+
{{ user.name }} {{ count * 2 }} {{ isOk ? 'да' : 'нет' }}
|
|
1316
|
+
|
|
1317
|
+
<!-- Условия -->
|
|
1318
|
+
<div #if="a">A</div>
|
|
1319
|
+
<div #else-if="b">B</div>
|
|
1320
|
+
<div #else>C</div>
|
|
1321
|
+
|
|
1322
|
+
<!-- Цикл по массиву -->
|
|
1323
|
+
<li #for="item in items">{{ $index }}: {{ item }}</li>
|
|
1324
|
+
|
|
1325
|
+
<!-- Цикл с ключом: строки переиспользуются -->
|
|
1326
|
+
<li #for="row in rows" #key="row.id"><input #model="row.name"></li>
|
|
1327
|
+
<li #for="row in rows" #key="row"><input #model="row.name"></li> <!-- ключ - сам объект -->
|
|
1328
|
+
|
|
1329
|
+
<!-- Цикл по объекту -->
|
|
1330
|
+
<li #for="val in obj">{{ $key }}: {{ val }}</li>
|
|
1331
|
+
|
|
1332
|
+
<!-- Видимость -->
|
|
1333
|
+
<p #show="isVisible">текст</p>
|
|
1334
|
+
|
|
1335
|
+
<!-- Двусторонняя привязка -->
|
|
1336
|
+
<input #model="name">
|
|
1337
|
+
<input type="checkbox" #model="agreed">
|
|
1338
|
+
<input type="number" #model="age">
|
|
1339
|
+
<select #model="country">...</select>
|
|
1340
|
+
<select multiple #model="drivers">...</select> <!-- массив -->
|
|
1341
|
+
<input type="checkbox" value="sms" #model="channels"> <!-- группа: массив -->
|
|
1342
|
+
|
|
1343
|
+
<!-- Атрибуты из выражения (шаблонизатор их не трогает) -->
|
|
1344
|
+
<button #attr="{ disabled: busy, 'aria-selected': on }">…</button>
|
|
1345
|
+
<input type="checkbox" #attr.checked="on">
|
|
1346
|
+
|
|
1347
|
+
<!-- События -->
|
|
1348
|
+
<button @click="count++">+</button>
|
|
1349
|
+
<button @click="doSomething()">действие</button>
|
|
1350
|
+
<input @keyup="if ($event.key === 'Enter') submit()">
|
|
1351
|
+
|
|
1352
|
+
<!-- Реактивный атрибут (с интерполяцией) -->
|
|
1353
|
+
<div class="item-{{ status }}"></div>
|
|
1354
|
+
<button disabled="{{ !isValid }}">Отправить</button>
|
|
1355
|
+
|
|
1356
|
+
<!-- Передача данных дочернему компоненту -->
|
|
1357
|
+
<st-app app="child" :value="{{ parentData }}"></st-app>
|
|
1358
|
+
|
|
1359
|
+
<!-- Сырой HTML (только доверенный) -->
|
|
1360
|
+
<div #html="trustedHtml"></div>
|
|
1361
|
+
|
|
1362
|
+
<!-- Пропустить поддерево -->
|
|
1363
|
+
<pre #pre>{{ не будет обработано }}</pre>
|
|
1364
|
+
```
|
|
1365
|
+
|
|
1366
|
+
```js
|
|
1367
|
+
// Регистрация
|
|
1368
|
+
App.create({ app: 'id', prop: val, method() {}, get computed() {}, template: `...` });
|
|
1369
|
+
App.extend('base', { app: 'derived', ...overrides });
|
|
1370
|
+
|
|
1371
|
+
// В setup() / методах:
|
|
1372
|
+
this.watch('prop', (n, o, unwatch) => { ... }, { immediate: true, deep: false });
|
|
1373
|
+
this.watch('prop.nested', callback);
|
|
1374
|
+
this.watch(() => this.a + this.b, callback);
|
|
1375
|
+
this.watch('method()', (args, result, unwatch) => { ... });
|
|
1376
|
+
|
|
1377
|
+
this.applyTemplate(htmlString); // переключить шаблон
|
|
1378
|
+
this.applyTemplate(); // вернуться к базовому
|
|
1379
|
+
|
|
1380
|
+
this.dispatchEvent('my-event', detail, { bubbles: true });
|
|
1381
|
+
this.clone({ ...overrides });
|
|
1382
|
+
this.unwatch(); // снять все подписки
|
|
1383
|
+
this.hasWatchers(); // число активных наблюдателей
|
|
1384
|
+
this.watched('prop', callback); // заменить подписку (без дублей)
|
|
1385
|
+
this.attrs.get('name');
|
|
1386
|
+
```
|