vue-mount-plugin 3.1.0 → 4.0.0-beta.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.
Files changed (15) hide show
  1. package/README.md +297 -19
  2. package/dist/index.cjs +969 -0
  3. package/dist/index.d.ts +266 -21
  4. package/dist/index.es5.js +7767 -0
  5. package/dist/index.es5.min.js +1 -0
  6. package/dist/index.iife.js +1103 -0
  7. package/dist/index.iife.min.js +1 -0
  8. package/dist/index.mjs +896 -90
  9. package/package.json +64 -63
  10. package/dist/index.cjs.js +0 -122
  11. package/dist/index.esm-browser.js +0 -126
  12. package/dist/index.esm-browser.prod.js +0 -7
  13. package/dist/index.esm-bundler.js +0 -120
  14. package/dist/index.global.js +0 -245
  15. package/dist/index.global.prod.js +0 -8
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # vue-mount-plugin
4
4
 
5
- A simple and easy to use vue instance extension plugin that supports vue2.0 and vue3.0
5
+ A simple and easy to use Vue instance extension plugin that supports Vue 2.0 and Vue 3.0
6
6
 
7
7
  [![NPM version][npm-image]][npm-url]
8
8
  [![Codacy Badge][codacy-image]][codacy-url]
@@ -17,10 +17,19 @@ A simple and easy to use vue instance extension plugin that supports vue2.0 and
17
17
 
18
18
  <div style="text-align: center; margin-bottom: 20px;" align="center">
19
19
 
20
- ### **[Documentation](https://www.saqqdy.com/vue-mount-plugin)** • **[Change Log](./CHANGELOG.md)**
20
+ **[Changelog](./CHANGELOG.md)** • **[中文文档](./README_CN.md)**
21
21
 
22
22
  </div>
23
23
 
24
+ ## Quick Try
25
+
26
+ Try it online with StackBlitz:
27
+
28
+ | Framework | Link |
29
+ | --------- | ---- |
30
+ | Vue 3 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/saqqdy/vue-mount-plugin/tree/master/examples/vue3) |
31
+ | Vue 2 | [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/saqqdy/vue-mount-plugin/tree/master/examples/vue2) |
32
+
24
33
  ## Installing
25
34
 
26
35
  ```bash
@@ -82,7 +91,7 @@ export default {
82
91
 
83
92
  ### Use in Vue `<=2.6`
84
93
 
85
- > Add `@vue/composition-api` to the `project.json` dependencies and run install.
94
+ > Add `@vue/composition-api` to the `package.json` dependencies and run install.
86
95
 
87
96
  ```json
88
97
  {
@@ -116,38 +125,307 @@ export default {
116
125
 
117
126
  ### Import in Browser
118
127
 
119
- Import `vue-mount-plugin` through browser HTML tags directly, and use global variable VueMount.
128
+ Import `vue-mount-plugin` through browser HTML tags directly, and use global variable `VueMount`.
120
129
 
121
130
  ```html
122
131
  <head>
123
132
  <!-- Import vue3 or vue2 -->
124
133
  <script src="//unpkg.com/vue@3"></script>
125
134
  <!-- Import vue-mount-plugin library -->
126
- <script src="//unpkg.com/vue-mount-plugin@3.0.0/dist/index.global.prod.js"></script>
135
+ <script src="//unpkg.com/vue-mount-plugin@4/dist/index.iife.min.js"></script>
127
136
  </head>
128
137
  ```
129
138
 
130
- ```vue
131
- <!-- test.vue -->
139
+ ```html
132
140
  <script>
133
- import { getCurrentInstance } from '@vue/composition-api'
134
- import DemoVue from './demo.vue'
141
+ const instance = new VueMount(DemoVue, { parent: this.$root })
135
142
 
136
- export default {
137
- setup() {
138
- const { proxy } = getCurrentInstance()
139
- const instance = new VueMount(DemoVue, { parent: proxy.$root })
143
+ // mount to the end of document.body
144
+ instance.mount()
140
145
 
141
- // mount to the end of document.body
142
- instance.mount()
146
+ // unmount
147
+ instance.unmount()
148
+ </script>
149
+ ```
143
150
 
144
- // unmount
145
- instance.unmount()
151
+ ### ES5 Support
152
+
153
+ For older browsers (IE11), use the ES5 build:
154
+
155
+ ```html
156
+ <head>
157
+ <!-- Import vue2 (Vue 3 does not support IE11) -->
158
+ <script src="//unpkg.com/vue@2"></script>
159
+ <!-- Import vue-mount-plugin ES5 build -->
160
+ <script src="//unpkg.com/vue-mount-plugin@4/dist/index.es5.min.js"></script>
161
+ </head>
162
+ ```
163
+
164
+ ## API
165
+
166
+ ### Constructor
167
+
168
+ ```typescript
169
+ new Mount(component, options?)
170
+ ```
171
+
172
+ #### Parameters
173
+
174
+ | Parameter | Type | Description |
175
+ |-----------|------|-------------|
176
+ | `component` | `Component` | Vue component to mount (supports async components) |
177
+ | `options` | `Options` | Mount options (optional) |
178
+
179
+ #### Options
180
+
181
+ | Property | Type | Default | Description |
182
+ |----------|------|---------|-------------|
183
+ | `app` | `App` | - | Vue 3 app instance |
184
+ | `children` | `unknown` | - | Children for VNode |
185
+ | `context` | `object` | - | Vue 2 context (router, store, i18n) |
186
+ | `parent` | `unknown` | - | Parent component instance |
187
+ | `props` | `object` | - | Props to pass to component |
188
+ | `target` | `Element \| string` | - | Mount target element or selector |
189
+ | `tagName` | `string` | `'div'` | Tag name for auto-created container |
190
+ | `listeners` | `Listeners` | - | Event listeners object |
191
+ | `on` | `Listeners` | - | Event listeners (alias) |
192
+ | `slots` | `Slots` | - | Slots object |
193
+ | `ref` | `Ref` | - | Ref to get component instance |
194
+ | `keepAlive` | `KeepAliveOptions \| boolean` | - | KeepAlive configuration |
195
+
196
+ #### Lifecycle Hooks
197
+
198
+ | Hook | Description |
199
+ |------|-------------|
200
+ | `onBeforeMount` | Called before component is mounted |
201
+ | `onMounted` | Called after component is mounted |
202
+ | `onBeforeUnmount` | Called before component is unmounted |
203
+ | `onUnmounted` | Called after component is unmounted |
204
+
205
+ ### Instance Methods
206
+
207
+ | Method | Returns | Description |
208
+ |--------|---------|-------------|
209
+ | `mount()` | `this` | Mount the component to DOM |
210
+ | `unmount()` | `void` | Unmount and destroy the component |
211
+ | `destroy()` | `void` | Alias for `unmount()` |
212
+ | `remove()` | `void` | Alias for `unmount()` |
213
+ | `setProps(props)` | `this` | Set props (chainable) |
214
+ | `setListeners(listeners)` | `this` | Set event listeners (chainable) |
215
+ | `on(listeners)` | `this` | Alias for `setListeners()` |
216
+ | `setSlots(slots)` | `this` | Set slots (chainable) |
217
+ | `setTarget(target)` | `this` | Set mount target (chainable) |
218
+ | `setHooks(hooks)` | `this` | Set lifecycle hooks (chainable) |
219
+
220
+ ### Instance Properties
221
+
222
+ | Property | Type | Description |
223
+ |----------|------|-------------|
224
+ | `id` | `number` | Unique instance ID (readonly) |
225
+ | `vNode` | `VNode` | Vue virtual node |
226
+ | `target` | `Element` | Mount target element |
227
+ | `componentInstance` | `ComponentPublicInstance` | Mounted component instance |
228
+
229
+ ### Static Methods
230
+
231
+ | Method | Returns | Description |
232
+ |--------|---------|-------------|
233
+ | `Mount.instances` | `Mount[]` | Get all active instances |
234
+ | `Mount.unmountAll()` | `void` | Unmount all instances |
235
+ | `Mount.destroyAll()` | `void` | Alias for `unmountAll()` |
236
+ | `Mount.getById(id)` | `Mount \| undefined` | Get instance by ID |
237
+
238
+ ## Usage Examples
239
+
240
+ ### Lifecycle Hooks
241
+
242
+ ```typescript
243
+ const instance = new Mount(DemoVue, {
244
+ onBeforeMount: (instance) => {
245
+ console.log('About to mount', instance.id)
246
+ },
247
+ onMounted: (instance) => {
248
+ console.log('Mounted', instance.componentInstance)
249
+ },
250
+ onBeforeUnmount: (instance) => {
251
+ console.log('About to unmount')
252
+ },
253
+ onUnmounted: (instance) => {
254
+ console.log('Unmounted')
146
255
  }
147
- }
148
- </script>
256
+ })
257
+ instance.mount()
258
+ ```
259
+
260
+ ### Event Listeners
261
+
262
+ ```typescript
263
+ const instance = new Mount(DemoVue, {
264
+ listeners: {
265
+ click: (event) => console.log('Clicked!', event),
266
+ close: () => instance.unmount()
267
+ }
268
+ })
269
+ // or use 'on' alias
270
+ const instance2 = new Mount(DemoVue, {
271
+ on: {
272
+ submit: (data) => console.log('Submitted:', data)
273
+ }
274
+ })
275
+ ```
276
+
277
+ ### Slots
278
+
279
+ ```typescript
280
+ import { h } from 'vue'
281
+
282
+ const instance = new Mount(ModalComponent, {
283
+ slots: {
284
+ default: [h('p', 'Modal content')],
285
+ header: [h('h2', 'Title')],
286
+ footer: [h('button', 'Close')]
287
+ }
288
+ })
149
289
  ```
150
290
 
291
+ ### Ref Access
292
+
293
+ ```typescript
294
+ import { ref } from 'vue'
295
+
296
+ const componentRef = ref(null)
297
+ const instance = new Mount(DemoVue, { ref: componentRef })
298
+
299
+ instance.mount()
300
+ // Access the component instance
301
+ console.log(componentRef.value) // ComponentPublicInstance
302
+ ```
303
+
304
+ ### Async Components
305
+
306
+ ```typescript
307
+ // Async component with dynamic import
308
+ const instance = new Mount(
309
+ () => import('./HeavyComponent.vue'),
310
+ { parent: proxy.$root }
311
+ )
312
+ instance.mount()
313
+ ```
314
+
315
+ ### Chained API
316
+
317
+ ```typescript
318
+ const instance = new Mount(DemoVue)
319
+ .setProps({ title: 'Hello' })
320
+ .setListeners({ click: handleClick })
321
+ .setTarget('#modal-container')
322
+ .setHooks({ onMounted: () => console.log('Ready!') })
323
+ .mount()
324
+ ```
325
+
326
+ ### Instance Management
327
+
328
+ ```typescript
329
+ // Get all active instances
330
+ const allInstances = Mount.instances
331
+ console.log(`Active instances: ${allInstances.length}`)
332
+
333
+ // Get specific instance by ID
334
+ const instance = Mount.getById(1)
335
+
336
+ // Unmount all instances at once
337
+ Mount.unmountAll()
338
+ ```
339
+
340
+ ## Migration from v3.x to v4.0
341
+
342
+ ### Breaking Changes
343
+
344
+ #### 1. Build Output File Names
345
+
346
+ If you reference the build files directly, update the paths:
347
+
348
+ | v3.x | v4.0 |
349
+ |------|------|
350
+ | `dist/index.esm-browser.js` | `dist/index.iife.js` |
351
+ | `dist/index.esm-browser.prod.js` | `dist/index.iife.min.js` |
352
+ | `dist/index.esm-bundler.js` | `dist/index.mjs` |
353
+ | `dist/index.cjs.js` | `dist/index.cjs` |
354
+ | `dist/index.global.js` | removed |
355
+ | `dist/index.global.prod.js` | removed |
356
+
357
+ #### 2. Node.js Version
358
+
359
+ Minimum Node.js version increased from `>=12.20` to `>=14.14.0`.
360
+
361
+ #### 3. CDN Links
362
+
363
+ Update your CDN links:
364
+
365
+ ```html
366
+ <!-- v3.x -->
367
+ <script src="//unpkg.com/vue-mount-plugin@3/dist/index.esm-browser.prod.js"></script>
368
+
369
+ <!-- v4.0 -->
370
+ <script src="//unpkg.com/vue-mount-plugin@4/dist/index.iife.min.js"></script>
371
+ ```
372
+
373
+ ### New Features (Optional Adoption)
374
+
375
+ v4.0 introduces many new features that are backward compatible:
376
+
377
+ ```typescript
378
+ // Lifecycle hooks
379
+ const instance = new Mount(Component, {
380
+ onBeforeMount: (instance) => console.log('before mount'),
381
+ onMounted: (instance) => console.log('mounted'),
382
+ })
383
+
384
+ // Event listeners
385
+ const instance = new Mount(Component, {
386
+ listeners: { click: handleClick },
387
+ // or
388
+ on: { click: handleClick },
389
+ })
390
+
391
+ // Ref support
392
+ const ref = { value: null }
393
+ new Mount(Component, { ref })
394
+
395
+ // Chained API
396
+ new Mount(Component)
397
+ .setProps({ title: 'Hello' })
398
+ .setTarget('#container')
399
+ .mount()
400
+
401
+ // Instance management
402
+ const allInstances = Mount.instances
403
+ Mount.unmountAll()
404
+ const instance = Mount.getById(1)
405
+ ```
406
+
407
+ ### No Code Changes Required
408
+
409
+ If you only use the basic API, no code changes are needed:
410
+
411
+ ```typescript
412
+ // This still works in v4.0
413
+ const instance = new Mount(Component, { parent: this.$root })
414
+ instance.mount()
415
+ instance.unmount()
416
+ ```
417
+
418
+ ## Build Outputs
419
+
420
+ | File | Format | Description |
421
+ |------|--------|-------------|
422
+ | `index.mjs` | ESM | ES Module for bundlers |
423
+ | `index.cjs` | CJS | CommonJS for Node.js |
424
+ | `index.iife.js` | IIFE | Browser build |
425
+ | `index.iife.min.js` | IIFE | Browser build (minified) |
426
+ | `index.es5.js` | UMD | ES5 compatible build |
427
+ | `index.es5.min.js` | UMD | ES5 compatible build (minified) |
428
+
151
429
  ## Support & Issues
152
430
 
153
431
  Please open an issue [here](https://github.com/saqqdy/vue-mount-plugin/issues).