@lytjs/component 6.5.0 → 6.7.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 CHANGED
@@ -1,520 +1,520 @@
1
- # @lytjs/component
2
-
3
- > LytJS 组件系统,提供组件实例管理、Props/Emits/Slots、生命周期钩子、错误边界和内置组件
4
-
5
- ## 安装
6
-
7
- ```bash
8
- npm install @lytjs/component
9
- ```
10
-
11
- ## 核心 API
12
-
13
- ### defineComponent
14
-
15
- 定义组件选项对象
16
-
17
- ```typescript
18
- import { defineComponent } from '@lytjs/component';
19
-
20
- const MyComponent = defineComponent({
21
- name: 'MyComponent',
22
- props: {
23
- title: String,
24
- count: { type: Number, default: 0 },
25
- },
26
- emits: ['update:count'],
27
- setup(props, { emit, slots }) {
28
- return () => h('div', props.title);
29
- },
30
- });
31
- ```
32
-
33
- ### defineFunctionalComponent
34
-
35
- 定义函数式组件
36
-
37
- ```typescript
38
- import { defineFunctionalComponent } from '@lytjs/component';
39
-
40
- const FunctionalButton = defineFunctionalComponent((props, ctx) => {
41
- return h('button', props.text);
42
- });
43
- ```
44
-
45
- ### createComponentInstance / setupComponent
46
-
47
- 创建和初始化组件实例
48
-
49
- ```typescript
50
- import { createComponentInstance, setupComponent } from '@lytjs/component';
51
-
52
- const instance = createComponentInstance(vnode, parent);
53
- setupComponent(instance);
54
- ```
55
-
56
- ### provide / inject
57
-
58
- 依赖注入
59
-
60
- ```typescript
61
- import { provide, inject } from '@lytjs/component';
62
-
63
- // 父组件提供
64
- provide('theme', 'dark');
65
-
66
- // 子组件注入
67
- const theme = inject('theme', 'light'); // 默认值 'light'
68
- ```
69
-
70
- ## 生命周期钩子
71
-
72
- ### 注册钩子
73
-
74
- ```typescript
75
- import {
76
- onBeforeMount,
77
- onMounted,
78
- onBeforeUpdate,
79
- onUpdated,
80
- onBeforeUnmount,
81
- onUnmounted,
82
- onErrorCaptured,
83
- onActivated,
84
- onDeactivated,
85
- onRenderTracked,
86
- onRenderTriggered,
87
- } from '@lytjs/component';
88
-
89
- export default defineComponent({
90
- setup() {
91
- onBeforeMount(() => {
92
- console.log('Before mount');
93
- });
94
-
95
- onMounted(() => {
96
- console.log('Mounted');
97
- });
98
-
99
- onBeforeUpdate(() => {
100
- console.log('Before update');
101
- });
102
-
103
- onUpdated(() => {
104
- console.log('Updated');
105
- });
106
-
107
- onBeforeUnmount(() => {
108
- console.log('Before unmount');
109
- });
110
-
111
- onUnmounted(() => {
112
- console.log('Unmounted');
113
- });
114
-
115
- onErrorCaptured((err, instance, info) => {
116
- console.error('Error captured:', err);
117
- return false; // 阻止错误继续传播
118
- });
119
-
120
- // KeepAlive 激活/停用
121
- onActivated(() => {
122
- console.log('Activated');
123
- });
124
-
125
- onDeactivated(() => {
126
- console.log('Deactivated');
127
- });
128
-
129
- // 调试钩子
130
- onRenderTracked((e) => {
131
- console.log('Render tracked:', e);
132
- });
133
-
134
- onRenderTriggered((e) => {
135
- console.log('Render triggered:', e);
136
- });
137
- },
138
- });
139
- ```
140
-
141
- ### 内部钩子调用
142
-
143
- ```typescript
144
- import {
145
- callLifecycleHook,
146
- callCreatedHook,
147
- callMountedHook,
148
- callUpdatedHook,
149
- callUnmountedHook,
150
- handleError,
151
- } from '@lytjs/component';
152
-
153
- // 手动调用生命周期钩子(内部使用)
154
- callMountedHook(instance);
155
-
156
- // 错误处理
157
- handleError(err, instance, 'hook');
158
- ```
159
-
160
- ## 错误边界
161
-
162
- ErrorBoundary 组件用于捕获子组件的渲染错误
163
-
164
- ### 基本用法
165
-
166
- ```typescript
167
- import { ErrorBoundary } from '@lytjs/component';
168
-
169
- const App = defineComponent({
170
- components: { ErrorBoundary },
171
- template: `
172
- <ErrorBoundary
173
- :on-error="handleError"
174
- :fallback="FallbackComponent"
175
- >
176
- <MyComponent />
177
- </ErrorBoundary>
178
- `,
179
- methods: {
180
- handleError(err: Error, info: string) {
181
- console.error('Error:', err, 'Info:', info);
182
- },
183
- },
184
- });
185
- ```
186
-
187
- ### Props
188
-
189
- ```typescript
190
- interface ErrorBoundaryProps {
191
- /** 错误回调 */
192
- onError?: (error: Error, info: string) => void;
193
- /** 回退组件 */
194
- fallback?: ComponentOptions;
195
- /** 是否捕获异步 Promise 错误 */
196
- capturePromiseRejections?: boolean;
197
- }
198
- ```
199
-
200
- ### 插槽用法
201
-
202
- ```typescript
203
- <ErrorBoundary>
204
- <template #default>
205
- <MyComponent />
206
- </template>
207
- <template #fallback="{ error }">
208
- <div>Something went wrong: {{ error?.message }}</div>
209
- </template>
210
- </ErrorBoundary>
211
- ```
212
-
213
- ### 异步错误捕获
214
-
215
- ```typescript
216
- <ErrorBoundary :capture-promise-rejections="true">
217
- <AsyncComponent />
218
- </ErrorBoundary>
219
- ```
220
-
221
- ## KeepAlive
222
-
223
- 内置缓存组件,用于缓存非活动组件实例
224
-
225
- ```typescript
226
- import { KeepAlive } from '@lytjs/component';
227
-
228
- // 基本用法
229
- <KeepAlive>
230
- <component :is="currentComponent" />
231
- </KeepAlive>
232
-
233
- // 带 include/exclude
234
- <KeepAlive include="ComponentA,ComponentB">
235
- <component :is="currentComponent" />
236
- </KeepAlive>
237
-
238
- <KeepAlive :exclude="/^Admin/">
239
- <component :is="currentComponent" />
240
- </KeepAlive>
241
-
242
- // 最大缓存数
243
- <KeepAlive :max="10">
244
- <component :is="currentComponent" />
245
- </KeepAlive>
246
- ```
247
-
248
- ### KeepAlive API
249
-
250
- ```typescript
251
- import {
252
- KeepAlive,
253
- createKeepAliveInstance,
254
- matchesPattern,
255
- getCacheKey,
256
- cacheInstance,
257
- getCachedInstance,
258
- removeCachedInstance,
259
- activateInstance,
260
- deactivateInstance,
261
- } from '@lytjs/component';
262
-
263
- // 手动管理缓存
264
- const key = getCacheKey(vnode);
265
- cacheInstance(key, instance);
266
- const cached = getCachedInstance(key);
267
- removeCachedInstance(key);
268
-
269
- // 激活/停用
270
- activateInstance(instance);
271
- deactivateInstance(instance);
272
- ```
273
-
274
- ## Suspense
275
-
276
- 异步组件边界,用于处理异步依赖
277
-
278
- ```typescript
279
- import { Suspense } from '@lytjs/component';
280
-
281
- <Suspense>
282
- <template #default>
283
- <AsyncComponent />
284
- </template>
285
- <template #fallback>
286
- <div>Loading...</div>
287
- </template>
288
- </Suspense>
289
- ```
290
-
291
- ### Suspense API
292
-
293
- ```typescript
294
- import {
295
- Suspense,
296
- createSuspenseInstance,
297
- createSuspenseBoundary,
298
- registerAsyncChild,
299
- isSuspensePending,
300
- getSuspenseError,
301
- resolveSuspense,
302
- abortSuspense,
303
- linkSuspenseBoundary,
304
- } from '@lytjs/component';
305
-
306
- // 手动管理 Suspense
307
- const suspense = createSuspenseBoundary();
308
- registerAsyncChild(suspense, asyncComponent);
309
-
310
- if (isSuspensePending(suspense)) {
311
- // 等待中
312
- }
313
-
314
- resolveSuspense(suspense);
315
- abortSuspense(suspense);
316
- ```
317
-
318
- ## Transition / TransitionGroup
319
-
320
- 过渡动画组件
321
-
322
- ```typescript
323
- import { Transition, TransitionGroup } from '@lytjs/component';
324
-
325
- // 单元素过渡
326
- <Transition name="fade" mode="out-in">
327
- <div :key="current">Content</div>
328
- </Transition>
329
-
330
- // 列表过渡
331
- <TransitionGroup name="list" tag="ul">
332
- <li v-for="item in items" :key="item.id">{{ item.text }}</li>
333
- </TransitionGroup>
334
- ```
335
-
336
- ## Teleport
337
-
338
- 传送门组件,将内容渲染到指定位置
339
-
340
- ```typescript
341
- import { Teleport } from '@lytjs/component';
342
-
343
- <Teleport to="body">
344
- <div class="modal">Modal content</div>
345
- </Teleport>
346
-
347
- <Teleport to="#modals" :disabled="isMobile">
348
- <div>Conditional teleport</div>
349
- </Teleport>
350
- ```
351
-
352
- ## 异步组件
353
-
354
- ### defineAsyncComponent
355
-
356
- 定义异步加载的组件
357
-
358
- ```typescript
359
- import { defineAsyncComponent } from '@lytjs/component';
360
-
361
- const AsyncComponent = defineAsyncComponent({
362
- loader: () => import('./HeavyComponent.vue'),
363
- loadingComponent: LoadingSpinner,
364
- errorComponent: ErrorDisplay,
365
- delay: 200,
366
- timeout: 10000,
367
- onError(error, retry, fail) {
368
- if (error.name === 'ChunkError') {
369
- retry();
370
- } else {
371
- fail();
372
- }
373
- },
374
- });
375
- ```
376
-
377
- ### 预加载
378
-
379
- ```typescript
380
- import {
381
- preloadComponents,
382
- preloadComponent,
383
- isComponentPreloaded,
384
- clearPreloadCache,
385
- } from '@lytjs/component';
386
-
387
- // 预加载单个组件
388
- await preloadComponent(AsyncComponent);
389
-
390
- // 预加载多个组件
391
- await preloadComponents([ComponentA, ComponentB]);
392
-
393
- // 检查是否已预加载
394
- if (isComponentPreloaded(AsyncComponent)) {
395
- // 已预加载
396
- }
397
-
398
- // 清除预加载缓存
399
- clearPreloadCache();
400
- ```
401
-
402
- ## Props / Emits / Slots
403
-
404
- ### Props
405
-
406
- ```typescript
407
- import { normalizePropsOptions, resolvePropValue, validateType } from '@lytjs/component';
408
-
409
- // 规范化 props 选项
410
- const normalized = normalizePropsOptions(componentOptions.props);
411
-
412
- // 解析 prop 值
413
- const value = resolvePropValue(propOptions, rawValue);
414
-
415
- // 类型验证
416
- if (validateType(String, value)) {
417
- // 类型正确
418
- }
419
- ```
420
-
421
- ### Emits
422
-
423
- ```typescript
424
- import { emit, normalizeEmitsOptions, isEmitValid } from '@lytjs/component';
425
-
426
- // 发射事件
427
- emit(instance, 'update:modelValue', newValue);
428
-
429
- // 规范化 emits 选项
430
- const normalized = normalizeEmitsOptions(componentOptions.emits);
431
-
432
- // 检查事件是否有效
433
- if (isEmitValid(instance, 'click')) {
434
- // 事件有效
435
- }
436
- ```
437
-
438
- ### Slots
439
-
440
- ```typescript
441
- import { initSlots, normalizeSlotValue } from '@lytjs/component';
442
-
443
- // 初始化插槽
444
- initSlots(instance, children);
445
-
446
- // 规范化插槽值
447
- const normalized = normalizeSlotValue(slotValue);
448
- ```
449
-
450
- ## Signal State 适配器
451
-
452
- 使 Signal 可以与组件协作
453
-
454
- ```typescript
455
- import { createSignalState, createComputedState } from '@lytjs/component';
456
-
457
- // 创建 Signal 状态
458
- const state = createSignalState(signal(0));
459
-
460
- // 创建计算状态
461
- const computed = createComputedState(() => props.count * 2);
462
- ```
463
-
464
- ## 递归深度限制
465
-
466
- 组件系统内置递归深度限制,防止无限递归导致的栈溢出:
467
-
468
- - 组件渲染递归深度限制
469
- - KeepAlive 缓存递归深度限制
470
- - Suspense 边界嵌套深度限制
471
-
472
- 当超过限制时,会输出警告并停止递归。
473
-
474
- ## 类型定义
475
-
476
- ```typescript
477
- import type {
478
- ComponentOptions,
479
- ComponentInternalInstance,
480
- ComponentPublicInstance,
481
- ComponentIdentity,
482
- ComponentLifecycleState,
483
- ComponentRenderState,
484
- ComponentContextState,
485
- ComponentParentState,
486
- SetupContext,
487
- InternalSlots,
488
- AppContext,
489
- PropOptions,
490
- RenderFunction,
491
- SlotFunction,
492
- KeepAliveProps,
493
- SuspenseProps,
494
- SuspenseAsyncState,
495
- TeleportProps,
496
- ErrorBoundaryProps,
497
- TransitionComponentProps,
498
- TransitionGroupComponentProps,
499
- AsyncComponentLoader,
500
- AsyncComponentOptions,
501
- AsyncComponentState,
502
- } from '@lytjs/component';
503
- ```
504
-
505
- ## 相关包
506
-
507
- - [@lytjs/core](../core) - 框架核心入口,整合所有子包
508
- - [@lytjs/reactivity](../reactivity) - 响应式系统,组件状态管理的基础
509
- - [@lytjs/vdom](../vdom) - 虚拟 DOM,组件渲染的基础
510
-
511
- ## 依赖版本
512
-
513
- - [@lytjs/shared-types](https://www.npmjs.com/package/@lytjs/shared-types): ^6.4.0
514
- - [@lytjs/reactivity](https://www.npmjs.com/package/@lytjs/reactivity): ^6.4.0
515
- - [@lytjs/vdom](https://www.npmjs.com/package/@lytjs/vdom): ^6.4.0
516
- - [@lytjs/common-vnode](https://www.npmjs.com/package/@lytjs/common-vnode): ^6.4.0
517
- - [@lytjs/common-is](https://www.npmjs.com/package/@lytjs/common-is): ^6.4.0
518
- - [@lytjs/common-scheduler](https://www.npmjs.com/package/@lytjs/common-scheduler): ^6.4.0
519
- - [@lytjs/common-error](https://www.npmjs.com/package/@lytjs/common-error): ^6.4.0
520
- - [@lytjs/common-string](https://www.npmjs.com/package/@lytjs/common-string): ^6.4.0
1
+ # @lytjs/component
2
+
3
+ > LytJS 组件系统,提供组件实例管理、Props/Emits/Slots、生命周期钩子、错误边界和内置组件
4
+
5
+ ## 安装
6
+
7
+ ```bash
8
+ npm install @lytjs/component
9
+ ```
10
+
11
+ ## 核心 API
12
+
13
+ ### defineComponent
14
+
15
+ 定义组件选项对象
16
+
17
+ ```typescript
18
+ import { defineComponent } from '@lytjs/component';
19
+
20
+ const MyComponent = defineComponent({
21
+ name: 'MyComponent',
22
+ props: {
23
+ title: String,
24
+ count: { type: Number, default: 0 },
25
+ },
26
+ emits: ['update:count'],
27
+ setup(props, { emit, slots }) {
28
+ return () => h('div', props.title);
29
+ },
30
+ });
31
+ ```
32
+
33
+ ### defineFunctionalComponent
34
+
35
+ 定义函数式组件
36
+
37
+ ```typescript
38
+ import { defineFunctionalComponent } from '@lytjs/component';
39
+
40
+ const FunctionalButton = defineFunctionalComponent((props, ctx) => {
41
+ return h('button', props.text);
42
+ });
43
+ ```
44
+
45
+ ### createComponentInstance / setupComponent
46
+
47
+ 创建和初始化组件实例
48
+
49
+ ```typescript
50
+ import { createComponentInstance, setupComponent } from '@lytjs/component';
51
+
52
+ const instance = createComponentInstance(vnode, parent);
53
+ setupComponent(instance);
54
+ ```
55
+
56
+ ### provide / inject
57
+
58
+ 依赖注入
59
+
60
+ ```typescript
61
+ import { provide, inject } from '@lytjs/component';
62
+
63
+ // 父组件提供
64
+ provide('theme', 'dark');
65
+
66
+ // 子组件注入
67
+ const theme = inject('theme', 'light'); // 默认值 'light'
68
+ ```
69
+
70
+ ## 生命周期钩子
71
+
72
+ ### 注册钩子
73
+
74
+ ```typescript
75
+ import {
76
+ onBeforeMount,
77
+ onMounted,
78
+ onBeforeUpdate,
79
+ onUpdated,
80
+ onBeforeUnmount,
81
+ onUnmounted,
82
+ onErrorCaptured,
83
+ onActivated,
84
+ onDeactivated,
85
+ onRenderTracked,
86
+ onRenderTriggered,
87
+ } from '@lytjs/component';
88
+
89
+ export default defineComponent({
90
+ setup() {
91
+ onBeforeMount(() => {
92
+ console.log('Before mount');
93
+ });
94
+
95
+ onMounted(() => {
96
+ console.log('Mounted');
97
+ });
98
+
99
+ onBeforeUpdate(() => {
100
+ console.log('Before update');
101
+ });
102
+
103
+ onUpdated(() => {
104
+ console.log('Updated');
105
+ });
106
+
107
+ onBeforeUnmount(() => {
108
+ console.log('Before unmount');
109
+ });
110
+
111
+ onUnmounted(() => {
112
+ console.log('Unmounted');
113
+ });
114
+
115
+ onErrorCaptured((err, instance, info) => {
116
+ console.error('Error captured:', err);
117
+ return false; // 阻止错误继续传播
118
+ });
119
+
120
+ // KeepAlive 激活/停用
121
+ onActivated(() => {
122
+ console.log('Activated');
123
+ });
124
+
125
+ onDeactivated(() => {
126
+ console.log('Deactivated');
127
+ });
128
+
129
+ // 调试钩子
130
+ onRenderTracked((e) => {
131
+ console.log('Render tracked:', e);
132
+ });
133
+
134
+ onRenderTriggered((e) => {
135
+ console.log('Render triggered:', e);
136
+ });
137
+ },
138
+ });
139
+ ```
140
+
141
+ ### 内部钩子调用
142
+
143
+ ```typescript
144
+ import {
145
+ callLifecycleHook,
146
+ callCreatedHook,
147
+ callMountedHook,
148
+ callUpdatedHook,
149
+ callUnmountedHook,
150
+ handleError,
151
+ } from '@lytjs/component';
152
+
153
+ // 手动调用生命周期钩子(内部使用)
154
+ callMountedHook(instance);
155
+
156
+ // 错误处理
157
+ handleError(err, instance, 'hook');
158
+ ```
159
+
160
+ ## 错误边界
161
+
162
+ ErrorBoundary 组件用于捕获子组件的渲染错误
163
+
164
+ ### 基本用法
165
+
166
+ ```typescript
167
+ import { ErrorBoundary } from '@lytjs/component';
168
+
169
+ const App = defineComponent({
170
+ components: { ErrorBoundary },
171
+ template: `
172
+ <ErrorBoundary
173
+ :on-error="handleError"
174
+ :fallback="FallbackComponent"
175
+ >
176
+ <MyComponent />
177
+ </ErrorBoundary>
178
+ `,
179
+ methods: {
180
+ handleError(err: Error, info: string) {
181
+ console.error('Error:', err, 'Info:', info);
182
+ },
183
+ },
184
+ });
185
+ ```
186
+
187
+ ### Props
188
+
189
+ ```typescript
190
+ interface ErrorBoundaryProps {
191
+ /** 错误回调 */
192
+ onError?: (error: Error, info: string) => void;
193
+ /** 回退组件 */
194
+ fallback?: ComponentOptions;
195
+ /** 是否捕获异步 Promise 错误 */
196
+ capturePromiseRejections?: boolean;
197
+ }
198
+ ```
199
+
200
+ ### 插槽用法
201
+
202
+ ```typescript
203
+ <ErrorBoundary>
204
+ <template #default>
205
+ <MyComponent />
206
+ </template>
207
+ <template #fallback="{ error }">
208
+ <div>Something went wrong: {{ error?.message }}</div>
209
+ </template>
210
+ </ErrorBoundary>
211
+ ```
212
+
213
+ ### 异步错误捕获
214
+
215
+ ```typescript
216
+ <ErrorBoundary :capture-promise-rejections="true">
217
+ <AsyncComponent />
218
+ </ErrorBoundary>
219
+ ```
220
+
221
+ ## KeepAlive
222
+
223
+ 内置缓存组件,用于缓存非活动组件实例
224
+
225
+ ```typescript
226
+ import { KeepAlive } from '@lytjs/component';
227
+
228
+ // 基本用法
229
+ <KeepAlive>
230
+ <component :is="currentComponent" />
231
+ </KeepAlive>
232
+
233
+ // 带 include/exclude
234
+ <KeepAlive include="ComponentA,ComponentB">
235
+ <component :is="currentComponent" />
236
+ </KeepAlive>
237
+
238
+ <KeepAlive :exclude="/^Admin/">
239
+ <component :is="currentComponent" />
240
+ </KeepAlive>
241
+
242
+ // 最大缓存数
243
+ <KeepAlive :max="10">
244
+ <component :is="currentComponent" />
245
+ </KeepAlive>
246
+ ```
247
+
248
+ ### KeepAlive API
249
+
250
+ ```typescript
251
+ import {
252
+ KeepAlive,
253
+ createKeepAliveInstance,
254
+ matchesPattern,
255
+ getCacheKey,
256
+ cacheInstance,
257
+ getCachedInstance,
258
+ removeCachedInstance,
259
+ activateInstance,
260
+ deactivateInstance,
261
+ } from '@lytjs/component';
262
+
263
+ // 手动管理缓存
264
+ const key = getCacheKey(vnode);
265
+ cacheInstance(key, instance);
266
+ const cached = getCachedInstance(key);
267
+ removeCachedInstance(key);
268
+
269
+ // 激活/停用
270
+ activateInstance(instance);
271
+ deactivateInstance(instance);
272
+ ```
273
+
274
+ ## Suspense
275
+
276
+ 异步组件边界,用于处理异步依赖
277
+
278
+ ```typescript
279
+ import { Suspense } from '@lytjs/component';
280
+
281
+ <Suspense>
282
+ <template #default>
283
+ <AsyncComponent />
284
+ </template>
285
+ <template #fallback>
286
+ <div>Loading...</div>
287
+ </template>
288
+ </Suspense>
289
+ ```
290
+
291
+ ### Suspense API
292
+
293
+ ```typescript
294
+ import {
295
+ Suspense,
296
+ createSuspenseInstance,
297
+ createSuspenseBoundary,
298
+ registerAsyncChild,
299
+ isSuspensePending,
300
+ getSuspenseError,
301
+ resolveSuspense,
302
+ abortSuspense,
303
+ linkSuspenseBoundary,
304
+ } from '@lytjs/component';
305
+
306
+ // 手动管理 Suspense
307
+ const suspense = createSuspenseBoundary();
308
+ registerAsyncChild(suspense, asyncComponent);
309
+
310
+ if (isSuspensePending(suspense)) {
311
+ // 等待中
312
+ }
313
+
314
+ resolveSuspense(suspense);
315
+ abortSuspense(suspense);
316
+ ```
317
+
318
+ ## Transition / TransitionGroup
319
+
320
+ 过渡动画组件
321
+
322
+ ```typescript
323
+ import { Transition, TransitionGroup } from '@lytjs/component';
324
+
325
+ // 单元素过渡
326
+ <Transition name="fade" mode="out-in">
327
+ <div :key="current">Content</div>
328
+ </Transition>
329
+
330
+ // 列表过渡
331
+ <TransitionGroup name="list" tag="ul">
332
+ <li v-for="item in items" :key="item.id">{{ item.text }}</li>
333
+ </TransitionGroup>
334
+ ```
335
+
336
+ ## Teleport
337
+
338
+ 传送门组件,将内容渲染到指定位置
339
+
340
+ ```typescript
341
+ import { Teleport } from '@lytjs/component';
342
+
343
+ <Teleport to="body">
344
+ <div class="modal">Modal content</div>
345
+ </Teleport>
346
+
347
+ <Teleport to="#modals" :disabled="isMobile">
348
+ <div>Conditional teleport</div>
349
+ </Teleport>
350
+ ```
351
+
352
+ ## 异步组件
353
+
354
+ ### defineAsyncComponent
355
+
356
+ 定义异步加载的组件
357
+
358
+ ```typescript
359
+ import { defineAsyncComponent } from '@lytjs/component';
360
+
361
+ const AsyncComponent = defineAsyncComponent({
362
+ loader: () => import('./HeavyComponent.vue'),
363
+ loadingComponent: LoadingSpinner,
364
+ errorComponent: ErrorDisplay,
365
+ delay: 200,
366
+ timeout: 10000,
367
+ onError(error, retry, fail) {
368
+ if (error.name === 'ChunkError') {
369
+ retry();
370
+ } else {
371
+ fail();
372
+ }
373
+ },
374
+ });
375
+ ```
376
+
377
+ ### 预加载
378
+
379
+ ```typescript
380
+ import {
381
+ preloadComponents,
382
+ preloadComponent,
383
+ isComponentPreloaded,
384
+ clearPreloadCache,
385
+ } from '@lytjs/component';
386
+
387
+ // 预加载单个组件
388
+ await preloadComponent(AsyncComponent);
389
+
390
+ // 预加载多个组件
391
+ await preloadComponents([ComponentA, ComponentB]);
392
+
393
+ // 检查是否已预加载
394
+ if (isComponentPreloaded(AsyncComponent)) {
395
+ // 已预加载
396
+ }
397
+
398
+ // 清除预加载缓存
399
+ clearPreloadCache();
400
+ ```
401
+
402
+ ## Props / Emits / Slots
403
+
404
+ ### Props
405
+
406
+ ```typescript
407
+ import { normalizePropsOptions, resolvePropValue, validateType } from '@lytjs/component';
408
+
409
+ // 规范化 props 选项
410
+ const normalized = normalizePropsOptions(componentOptions.props);
411
+
412
+ // 解析 prop 值
413
+ const value = resolvePropValue(propOptions, rawValue);
414
+
415
+ // 类型验证
416
+ if (validateType(String, value)) {
417
+ // 类型正确
418
+ }
419
+ ```
420
+
421
+ ### Emits
422
+
423
+ ```typescript
424
+ import { emit, normalizeEmitsOptions, isEmitValid } from '@lytjs/component';
425
+
426
+ // 发射事件
427
+ emit(instance, 'update:modelValue', newValue);
428
+
429
+ // 规范化 emits 选项
430
+ const normalized = normalizeEmitsOptions(componentOptions.emits);
431
+
432
+ // 检查事件是否有效
433
+ if (isEmitValid(instance, 'click')) {
434
+ // 事件有效
435
+ }
436
+ ```
437
+
438
+ ### Slots
439
+
440
+ ```typescript
441
+ import { initSlots, normalizeSlotValue } from '@lytjs/component';
442
+
443
+ // 初始化插槽
444
+ initSlots(instance, children);
445
+
446
+ // 规范化插槽值
447
+ const normalized = normalizeSlotValue(slotValue);
448
+ ```
449
+
450
+ ## Signal State 适配器
451
+
452
+ 使 Signal 可以与组件协作
453
+
454
+ ```typescript
455
+ import { createSignalState, createComputedState } from '@lytjs/component';
456
+
457
+ // 创建 Signal 状态
458
+ const state = createSignalState(signal(0));
459
+
460
+ // 创建计算状态
461
+ const computed = createComputedState(() => props.count * 2);
462
+ ```
463
+
464
+ ## 递归深度限制
465
+
466
+ 组件系统内置递归深度限制,防止无限递归导致的栈溢出:
467
+
468
+ - 组件渲染递归深度限制
469
+ - KeepAlive 缓存递归深度限制
470
+ - Suspense 边界嵌套深度限制
471
+
472
+ 当超过限制时,会输出警告并停止递归。
473
+
474
+ ## 类型定义
475
+
476
+ ```typescript
477
+ import type {
478
+ ComponentOptions,
479
+ ComponentInternalInstance,
480
+ ComponentPublicInstance,
481
+ ComponentIdentity,
482
+ ComponentLifecycleState,
483
+ ComponentRenderState,
484
+ ComponentContextState,
485
+ ComponentParentState,
486
+ SetupContext,
487
+ InternalSlots,
488
+ AppContext,
489
+ PropOptions,
490
+ RenderFunction,
491
+ SlotFunction,
492
+ KeepAliveProps,
493
+ SuspenseProps,
494
+ SuspenseAsyncState,
495
+ TeleportProps,
496
+ ErrorBoundaryProps,
497
+ TransitionComponentProps,
498
+ TransitionGroupComponentProps,
499
+ AsyncComponentLoader,
500
+ AsyncComponentOptions,
501
+ AsyncComponentState,
502
+ } from '@lytjs/component';
503
+ ```
504
+
505
+ ## 相关包
506
+
507
+ - [@lytjs/core](../core) - 框架核心入口,整合所有子包
508
+ - [@lytjs/reactivity](../reactivity) - 响应式系统,组件状态管理的基础
509
+ - [@lytjs/vdom](../vdom) - 虚拟 DOM,组件渲染的基础
510
+
511
+ ## 依赖版本
512
+
513
+ - [@lytjs/shared-types](https://www.npmjs.com/package/@lytjs/shared-types): ^6.4.0
514
+ - [@lytjs/reactivity](https://www.npmjs.com/package/@lytjs/reactivity): ^6.4.0
515
+ - [@lytjs/vdom](https://www.npmjs.com/package/@lytjs/vdom): ^6.4.0
516
+ - [@lytjs/common-vnode](https://www.npmjs.com/package/@lytjs/common-vnode): ^6.4.0
517
+ - [@lytjs/common-is](https://www.npmjs.com/package/@lytjs/common-is): ^6.4.0
518
+ - [@lytjs/common-scheduler](https://www.npmjs.com/package/@lytjs/common-scheduler): ^6.4.0
519
+ - [@lytjs/common-error](https://www.npmjs.com/package/@lytjs/common-error): ^6.4.0
520
+ - [@lytjs/common-string](https://www.npmjs.com/package/@lytjs/common-string): ^6.4.0