vue-use-forward-ref 0.0.0 → 0.0.2

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 (3) hide show
  1. package/README.md +61 -45
  2. package/README.zh-CN.md +120 -0
  3. package/package.json +17 -17
package/README.md CHANGED
@@ -1,104 +1,120 @@
1
- # vue-forwardref
1
+ # vue-use-forward-ref
2
2
 
3
- [![npm](https://img.shields.io/npm/v/vue-forwardref.svg?colorA=42b883&colorB=35495e)](https://npmjs.com/package/vue-forwardref) [![Unit Test](https://img.shields.io/github/actions/workflow/status/refinist/vue-forwardref/unit-test.yml?colorA=42b883&colorB=35495e&label=Unit%20Test)](https://github.com/refinist/vue-forwardref/actions/workflows/unit-test.yml) [![codecov](https://img.shields.io/codecov/c/github/refinist/vue-forwardref?colorA=42b883&colorB=35495e)](https://codecov.io/github/refinist/vue-forwardref) [![size](https://img.badgesize.io/https://unpkg.com/vue-forwardref?compression=gzip&labelColor=42b883&color=35495e)](https://unpkg.com/vue-forwardref)
3
+ [![npm](https://img.shields.io/npm/v/vue-use-forward-ref.svg?colorA=42b883&colorB=35495e)](https://npmjs.com/package/vue-use-forward-ref) [![Unit Test](https://img.shields.io/github/actions/workflow/status/refinist/vue-use-forward-ref/unit-test.yml?colorA=42b883&colorB=35495e&label=Unit%20Test)](https://github.com/refinist/vue-use-forward-ref/actions/workflows/unit-test.yml) [![codecov](https://img.shields.io/codecov/c/github/refinist/vue-use-forward-ref?colorA=42b883&colorB=35495e)](https://codecov.io/github/refinist/vue-use-forward-ref) [![size](https://img.badgesize.io/https://unpkg.com/vue-use-forward-ref?compression=gzip&labelColor=42b883&color=35495e)](https://unpkg.com/vue-use-forward-ref)
4
+
5
+ English | [中文](README.zh-CN.md)
4
6
 
5
7
  A lightweight Vue 3 composable to forward component ref and merge the child's exposed API onto the parent instance. Parent's ref then exposes both the child's `expose()` and optional extra fields in one place.
6
8
 
7
- ## ✨ Features
9
+ ## Features
8
10
 
9
11
  - **Lightweight** – Zero dependencies, minimal footprint
10
12
  - **Type Safe** – Full TypeScript support
11
13
  - **Simple API** – `useForwardRef(ext?)` returns `{ forwardRef }`, pass it to child's `ref`
12
14
  - **Merge with ext** – Optionally merge extra fields onto the parent's exposed object
13
15
 
14
- ## 📦 Installation
16
+ ## Installation
15
17
 
16
18
  ```bash
17
19
  # npm
18
- npm install vue-forwardref
20
+ npm install vue-use-forward-ref
19
21
 
20
22
  # yarn
21
- yarn add vue-forwardref
23
+ yarn add vue-use-forward-ref
22
24
 
23
25
  # pnpm
24
- pnpm add vue-forwardref
26
+ pnpm add vue-use-forward-ref
25
27
 
26
28
  # bun
27
- bun add vue-forwardref
29
+ bun add vue-use-forward-ref
28
30
  ```
29
31
 
30
- ## 🚀 Basic Usage
32
+ ## Basic Usage
31
33
 
32
34
  ### Forward child ref to parent
33
35
 
34
36
  Use `forwardRef` as the child's `ref`. The parent's ref (e.g. from a grandparent) will then receive the child's exposed API.
35
37
 
36
38
  ```vue
37
- <template>
38
- <Child ref="forwardRef" />
39
- </template>
40
-
39
+ <!-- Wrapper.vue -->
41
40
  <script setup lang="ts">
42
41
  import { ref } from 'vue';
43
- import { useForwardRef } from 'vue-forwardref';
42
+ import { useForwardRef } from 'vue-use-forward-ref';
44
43
  import Child from './Child.vue';
45
44
 
46
45
  const { forwardRef } = useForwardRef();
47
46
  </script>
48
- ```
49
47
 
50
- When a parent mounts this component with `<Wrapper ref="parentRef" />`, `parentRef` will expose the same API as `Child` (whatever `Child` passed to `expose()`).
48
+ <template>
49
+ <Child :ref="forwardRef" />
50
+ </template>
51
+ ```
51
52
 
52
- ### Merge extra fields with `useForwardRef(ext)`
53
+ ```vue
54
+ <!-- App.vue -->
55
+ <script setup lang="ts">
56
+ import type Child from './Child.vue';
53
57
 
54
- You can merge additional fields onto the exposed object so the parent ref sees both the child's API and your extra data.
58
+ const wrapperRef = useTemplateRef<InstanceType<typeof Child>>('wrapperRef');
59
+ </script>
55
60
 
56
- ```vue
57
61
  <template>
58
- <Child ref="forwardRef" />
62
+ <Wrapper ref="wrapperRef" />
59
63
  </template>
64
+ ```
65
+
66
+ ### Merge extra fields
67
+
68
+ You can merge additional fields onto the exposed object so the parent ref sees both the child's API and your extra data.
69
+
70
+ ```ts
71
+ // types.ts
72
+ import type { Ref } from 'vue';
73
+ import type Child from './Child.vue';
74
+
75
+ export type WrapperExpose = {
76
+ count: Ref<number>;
77
+ reset: () => void;
78
+ };
79
+ export type WrapperInstance = InstanceType<typeof Child> & WrapperExpose;
80
+ ```
60
81
 
82
+ ```vue
83
+ <!-- Wrapper.vue -->
61
84
  <script setup lang="ts">
62
85
  import { ref } from 'vue';
63
- import { useForwardRef } from 'vue-forwardref';
86
+ import { useForwardRef } from 'vue-use-forward-ref';
64
87
  import Child from './Child.vue';
88
+ import type { WrapperExpose } from './types';
65
89
 
66
90
  const count = ref(0);
67
- const { forwardRef } = useForwardRef({
91
+ const { forwardRef } = useForwardRef<WrapperExpose>({
68
92
  count,
69
93
  reset: () => {
70
94
  count.value = 0;
71
95
  }
72
96
  });
73
97
  </script>
74
- ```
75
-
76
- The parent's ref will then have both `Child`'s exposed API and `count` / `reset`.
77
-
78
- ## 📚 API
79
-
80
- ### `useForwardRef<E>(ext?: E)`
81
98
 
82
- Must be called in a component's `setup()` (uses `getCurrentInstance()`).
83
-
84
- **Parameters:**
85
-
86
- - `ext` (optional) – Object to merge onto the current component's `exposed` / `exposeProxy`. When the ref callback runs (child mounted), both the child instance (or element) and `ext` are assigned onto the current instance's exposed object.
87
-
88
- **Returns:**
89
-
90
- ```ts
91
- { forwardRef: (originRef: OriginRef) => void }
99
+ <template>
100
+ <Child :ref="forwardRef" />
101
+ </template>
92
102
  ```
93
103
 
94
- - `forwardRef` – Ref callback. Use it as the child's `ref` (e.g. `ref="forwardRef"` or `:ref="forwardRef"`). When the child is mounted, `originRef` is the child instance or DOM element; when unmounted, it is `null`. The current component's exposed object is updated so that the parent's ref sees the merged API.
95
-
96
- **Types:**
104
+ ```vue
105
+ <!-- App.vue -->
106
+ <script setup lang="ts">
107
+ import type { WrapperInstance } from './types';
108
+ const wrapperRef = useTemplateRef<WrapperInstance>('wrapperRef');
109
+ </script>
97
110
 
98
- - `OriginRef = Element | ComponentPublicInstance | null`
111
+ <template>
112
+ <Wrapper ref="wrapperRef" />
113
+ </template>
114
+ ```
99
115
 
100
- ## 📄 License
116
+ ## License
101
117
 
102
118
  [MIT](./LICENSE)
103
119
 
104
- Copyright (c) 2025-present REFINIST
120
+ Copyright (c) 2026-present REFINIST
package/README.zh-CN.md ADDED
@@ -0,0 +1,120 @@
1
+ # vue-use-forward-ref
2
+
3
+ [![npm](https://img.shields.io/npm/v/vue-use-forward-ref.svg?colorA=42b883&colorB=35495e)](https://npmjs.com/package/vue-use-forward-ref) [![Unit Test](https://img.shields.io/github/actions/workflow/status/refinist/vue-use-forward-ref/unit-test.yml?colorA=42b883&colorB=35495e&label=Unit%20Test)](https://github.com/refinist/vue-use-forward-ref/actions/workflows/unit-test.yml) [![codecov](https://img.shields.io/codecov/c/github/refinist/vue-use-forward-ref?colorA=42b883&colorB=35495e)](https://codecov.io/github/refinist/vue-use-forward-ref) [![size](https://img.badgesize.io/https://unpkg.com/vue-use-forward-ref?compression=gzip&labelColor=42b883&color=35495e)](https://unpkg.com/vue-use-forward-ref)
4
+
5
+ [English](README.md) | 中文
6
+
7
+ 轻量级 Vue 3 组合式 API，用于转发组件 ref，并将子组件的暴露 API 合并到父实例上。父级 ref 会同时暴露子组件的 `expose()` 以及可选的额外字段，统一在一处访问。
8
+
9
+ ## 特性
10
+
11
+ - **轻量** – 零依赖，体积小
12
+ - **类型安全** – 完整 TypeScript 支持
13
+ - **简单 API** – `useForwardRef(ext?)` 返回 `{ forwardRef }`，传给子组件的 `ref` 即可
14
+ - **与 ext 合并** – 可选地将额外字段合并到父级暴露对象上
15
+
16
+ ## 安装
17
+
18
+ ```bash
19
+ # npm
20
+ npm install vue-use-forward-ref
21
+
22
+ # yarn
23
+ yarn add vue-use-forward-ref
24
+
25
+ # pnpm
26
+ pnpm add vue-use-forward-ref
27
+
28
+ # bun
29
+ bun add vue-use-forward-ref
30
+ ```
31
+
32
+ ## 基本用法
33
+
34
+ ### 将子组件 ref 转发给父级
35
+
36
+ 将 `forwardRef` 作为子组件的 `ref` 使用。父级（例如祖父组件）的 ref 会收到子组件的暴露 API。
37
+
38
+ ```vue
39
+ <!-- Wrapper.vue -->
40
+ <script setup lang="ts">
41
+ import { ref } from 'vue';
42
+ import { useForwardRef } from 'vue-use-forward-ref';
43
+ import Child from './Child.vue';
44
+
45
+ const { forwardRef } = useForwardRef();
46
+ </script>
47
+
48
+ <template>
49
+ <Child :ref="forwardRef" />
50
+ </template>
51
+ ```
52
+
53
+ ```vue
54
+ <!-- App.vue -->
55
+ <script setup lang="ts">
56
+ import type Child from './Child.vue';
57
+
58
+ const wrapperRef = useTemplateRef<InstanceType<typeof Child>>('wrapperRef');
59
+ </script>
60
+
61
+ <template>
62
+ <Wrapper ref="wrapperRef" />
63
+ </template>
64
+ ```
65
+
66
+ ### 合并额外字段
67
+
68
+ 可以将额外字段合并到暴露对象上，使父级 ref 既能访问子组件的 API，也能访问你传入的额外数据。
69
+
70
+ ```ts
71
+ // types.ts
72
+ import type { Ref } from 'vue';
73
+ import type Child from './Child.vue';
74
+
75
+ export type WrapperExpose = {
76
+ count: Ref<number>;
77
+ reset: () => void;
78
+ };
79
+ export type WrapperInstance = InstanceType<typeof Child> & WrapperExpose;
80
+ ```
81
+
82
+ ```vue
83
+ <!-- Wrapper.vue -->
84
+ <script setup lang="ts">
85
+ import { ref } from 'vue';
86
+ import { useForwardRef } from 'vue-use-forward-ref';
87
+ import Child from './Child.vue';
88
+ import type { WrapperExpose } from './types';
89
+
90
+ const count = ref(0);
91
+ const { forwardRef } = useForwardRef<WrapperExpose>({
92
+ count,
93
+ reset: () => {
94
+ count.value = 0;
95
+ }
96
+ });
97
+ </script>
98
+
99
+ <template>
100
+ <Child :ref="forwardRef" />
101
+ </template>
102
+ ```
103
+
104
+ ```vue
105
+ <!-- App.vue -->
106
+ <script setup lang="ts">
107
+ import type { WrapperInstance } from './types';
108
+ const wrapperRef = useTemplateRef<WrapperInstance>('wrapperRef');
109
+ </script>
110
+
111
+ <template>
112
+ <Wrapper ref="wrapperRef" />
113
+ </template>
114
+ ```
115
+
116
+ ## 许可证
117
+
118
+ [MIT](./LICENSE)
119
+
120
+ Copyright (c) 2026-present REFINIST
package/package.json CHANGED
@@ -1,15 +1,14 @@
1
1
  {
2
2
  "name": "vue-use-forward-ref",
3
3
  "type": "module",
4
- "version": "0.0.0",
5
- "packageManager": "pnpm@10.30.3",
4
+ "version": "0.0.2",
6
5
  "description": "A lightweight Vue 3 composable to forward component ref and merge child exposed API onto parent instance",
7
6
  "author": "REFINIST",
8
7
  "license": "MIT",
9
- "homepage": "https://github.com/refinist/vue-forwardref#readme",
8
+ "homepage": "https://github.com/refinist/vue-use-forward-ref#readme",
10
9
  "repository": {
11
10
  "type": "git",
12
- "url": "git+https://github.com/refinist/vue-forwardref.git"
11
+ "url": "git+https://github.com/refinist/vue-use-forward-ref.git"
13
12
  },
14
13
  "bugs": {
15
14
  "url": "https://github.com/refinist/vue-forwardref/issues"
@@ -36,18 +35,6 @@
36
35
  "engines": {
37
36
  "node": ">=20.19.0"
38
37
  },
39
- "scripts": {
40
- "build": "tsdown",
41
- "lint": "eslint --cache .",
42
- "lint:fix": "pnpm run lint --fix",
43
- "format": "prettier --cache --write .",
44
- "prepublishOnly": "pnpm run build",
45
- "release": "bumpp && pnpm publish",
46
- "test": "vitest run",
47
- "test:coverage": "vitest run --coverage",
48
- "test:watch": "vitest",
49
- "typecheck": "tsgo --noEmit"
50
- },
51
38
  "peerDependencies": {
52
39
  "vue": ">=3"
53
40
  },
@@ -65,6 +52,7 @@
65
52
  "prettier": "^3.8.1",
66
53
  "tsdown": "^0.20.3",
67
54
  "typescript": "^5.9.3",
55
+ "vite": "^7.3.1",
68
56
  "vitest": "^4.0.18",
69
57
  "vue": "^3.5.21"
70
58
  },
@@ -72,5 +60,17 @@
72
60
  "publishConfig": {
73
61
  "access": "public",
74
62
  "registry": "https://registry.npmjs.org/"
63
+ },
64
+ "scripts": {
65
+ "build": "tsdown",
66
+ "play": "vite",
67
+ "lint": "eslint --cache .",
68
+ "lint:fix": "pnpm run lint --fix",
69
+ "format": "prettier --cache --write .",
70
+ "release": "bumpp",
71
+ "test": "vitest run",
72
+ "test:coverage": "vitest run --coverage",
73
+ "test:watch": "vitest",
74
+ "typecheck": "tsgo --noEmit"
75
75
  }
76
- }
76
+ }