npm - @zhencai/vue-focus-scope - Versions diffs - 1.0.6 → 1.0.7 - Mend

@zhencai/vue-focus-scope 1.0.6 → 1.0.7

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 (5) hide show

package/LICENSE ADDED Viewed

	@@ -0,0 +1 @@
1	+ MIT

package/{readme.md → README.md} RENAMED Viewed

@@ -19,9 +19,14 @@
   - **`loop` (默认)**：强循环模式。焦点被严格限制在组件内部，无法通过 Tab 键移出
   - **`soft-loop`**：软循环模式。在首尾之间提供缓冲，允许特定的交互逻辑（防止单元素死循环）
+- **自动聚焦**
+  - 通过 `autofocus` 属性控制组件挂载时是否自动聚焦第一个可聚焦元素
+  - 支持动态切换，可在组件挂载后通过改变属性值触发聚焦
+  - 适用于多作用域场景，避免后挂载的组件抢占焦点
 - **无障碍友好**：原生支持键盘导航，无需额外配置
-## 安装与使用
+## 安装
 ```vue
 npm install @zhencai/vue-focus-scope
@@ -63,13 +68,53 @@ import FocusScope from "@zhencai/vue-focus-scope";
 </template>
 ```
+### 自动聚焦控制
+通过 `autofocus` 属性控制焦点行为：
+```vue
+<template>
+  <div>
+    <!-- 场景1：默认不自动聚焦 -->
+    <FocusScope :autofocus="false">
+      <input type="text" placeholder="不会自动聚焦" />
+    </FocusScope>
+    <!-- 场景2：挂载时自动聚焦 -->
+    <FocusScope :autofocus="true">
+      <input type="text" placeholder="会自动聚焦到这里" />
+    </FocusScope>
+    <!-- 场景3：动态控制聚焦（多作用域场景） -->
+    <button @click="showDialog = true">打开对话框</button>
+    <FocusScope v-if="showDialog" :autofocus="true">
+      <input type="text" placeholder="对话框打开时自动聚焦" />
+      <button @click="showDialog = false">关闭</button>
+    </FocusScope>
+  </div>
+</template>
+<script setup lang="ts">
+import { ref } from "vue";
+const showDialog = ref(false);
+</script>
+```
+**多作用域场景说明**：
+- 当页面有多个 `FocusScope` 组件时，为了避免后挂载的组件抢占焦点
+- 可以先将所有组件的 `autofocus` 设为 `false`
+- 在需要聚焦时（如对话框显示、标签页切换），动态将对应组件的 `autofocus` 设为 `true`
 ## API 文档
 ### Props
-| 属性名    | 类型                    | 默认值   | 说明                                                                                                            |
-| :-------- | :---------------------- | :------- | :-------------------------------------------------------------------------------------------------------------- |
-| `tabMode` | `'loop' \| 'soft-loop'` | `'loop'` | 循环模式：<br>- `loop`: 严格限制焦点在插槽内<br>- `soft-loop`: 允许一定程度的外部交互，主要用于防止单元素死循环 |
+| 属性名      | 类型                    | 默认值   | 说明                                                                                                                  |
+| :---------- | :---------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------- |
+| `tabMode`   | `'loop' \| 'soft-loop'` | `'loop'` | 循环模式：<br>- `loop`: 严格限制焦点在插槽内<br>- `soft-loop`: 允许一定程度的外部交互，主要用于防止单元素死循环       |
+| `autofocus` | `boolean`               | `false`  | 是否自动聚焦第一个可聚焦元素：<br>- `true`: 组件挂载时或属性变为 true 时自动聚焦<br>- `false`: 不自动聚焦，需手动控制 |
 ### Slots

package/index.d.ts CHANGED Viewed

@@ -2,6 +2,7 @@ import { DefineComponent } from 'vue';
 declare const FocusScope: DefineComponent<{
     tabMode?: 'loop' | 'soft-loop';
+    autofocus?: boolean;
 }>;
 export { FocusScope };

package/index.js CHANGED Viewed

@@ -1,71 +1,163 @@
-import { createCommentVNode as e, createElementBlock as t, createElementVNode as n, defineComponent as r, openBlock as i, renderSlot as a, useTemplateRef as o } from "vue";
+/* My Library v1.0.0 */
+import { createCommentVNode, createElementBlock, createElementVNode, defineComponent, openBlock, renderSlot, useTemplateRef, watch } from "vue";
 //#region src/components/FocusScope.vue?vue&type=script&setup=true&lang.ts
-var s = {
+var _hoisted_1 = {
 	key: 0,
 	tabindex: "0"
-}, c = /* @__PURE__ */ r({
+};
+//#endregion
+//#region src/components/FocusScope.vue
+var FocusScope_default = /* @__PURE__ */ defineComponent({
 	__name: "FocusScope",
-	props: { tabMode: { default: "loop" } },
-	setup(r) {
-		let c = o("wrapper");
-		function l(e) {
-			return e ? Array.from(e.querySelectorAll("a[href]:not([tabindex=\"-1\"]):not(.sentinel-start):not(.sentinel-end),       button:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       input:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       select:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       textarea:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       [tabindex]:not([tabindex=\"-1\"]):not(.sentinel-start):not(.sentinel-end)")).filter((e) => {
-				let t = e.parentElement;
-				for (; t;) {
-					if (t.tagName === "FIELDSET" && t.disabled) return !1;
-					t = t.parentElement;
+	props: {
+		tabMode: { default: "loop" },
+		autofocus: {
+			type: Boolean,
+			default: true
+		}
+	},
+	setup(__props) {
+		const props = __props;
+		/**
+		* wrapper 容器引用
+		* 用于限定焦点作用域（Focus Scope）
+		*/
+		const wrapper = useTemplateRef("wrapper");
+		/**
+		* 获取当前作用域内所有“可聚焦元素”
+		*
+		* 规则：
+		* 1. 排除 tabindex = -1（不可通过 Tab 聚焦）
+		* 2. 排除 disabled 元素
+		* 3. 排除哨兵节点（sentinel-start / sentinel-end）
+		* 4. 排除被 disabled 的 fieldset 包裹的元素
+		*/
+		function getAllTabObjects(scope) {
+			if (!scope) return [];
+			return Array.from(scope.querySelectorAll("a[href]:not([tabindex=\"-1\"]):not(.sentinel-start):not(.sentinel-end),       button:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       input:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       select:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       textarea:not([tabindex=\"-1\"]):not([disabled]):not(.sentinel-start):not(.sentinel-end),       [tabindex]:not([tabindex=\"-1\"]):not(.sentinel-start):not(.sentinel-end)")).filter((el) => {
+				/**
+				* 向上查找父级
+				* 如果在 disabled 的 fieldset 内，则不可聚焦
+				*/
+				let parent = el.parentElement;
+				while (parent) {
+					if (parent.tagName === "FIELDSET") {
+						if (parent.disabled) return false;
+					}
+					parent = parent.parentElement;
 				}
-				return !0;
-			}) : [];
+				return true;
+			});
 		}
-		function u() {
+		/**
+		* 聚焦第一个可聚焦元素
+		*/
+		function focusFirst() {
 			try {
-				if (c.value) {
-					let e = l(c.value);
-					if (e.length === 0) return;
-					e[0].focus();
+				if (wrapper.value) {
+					const objects = getAllTabObjects(wrapper.value);
+					if (objects.length === 0) return;
+					objects[0].focus();
 				}
-			} catch (e) {
-				console.error("focusFirst error:", e);
+			} catch (error) {
+				console.error("focusFirst error:", error);
 			}
 		}
-		function d() {
-			if (c.value) {
-				let e = l(c.value);
-				if (e.length === 0) return;
-				e[e.length - 1].focus();
+		/**
+		* 聚焦最后一个可聚焦元素
+		*/
+		function focusLast() {
+			if (wrapper.value) {
+				const objects = getAllTabObjects(wrapper.value);
+				if (objects.length === 0) return;
+				objects[objects.length - 1].focus();
 			}
 		}
-		function f(e) {
-			if (!c.value) return;
-			let t = e.relatedTarget;
-			if (!(t instanceof Node)) {
-				u();
+		/**
+		* 当焦点进入“起始哨兵”时触发
+		*
+		* 关键逻辑：
+		* 1. 判断焦点来源（relatedTarget）
+		* 2. 区分是：
+		*    - 从外部进入
+		*    - 从内部 Shift+Tab 回退
+		*/
+		function onFocusStart(e) {
+			if (!wrapper.value) return;
+			const from = e.relatedTarget;
+			/**
+			* 情况1：没有来源（例如浏览器初始化 / JS focus）
+			* → 默认聚焦第一个
+			*/
+			if (!(from instanceof Node)) {
+				focusFirst();
 				return;
 			}
-			c.value.contains(t) ? d() : u();
+			/**
+			* 情况2：从作用域外进入
+			* → 正常进入，聚焦第一个
+			*/
+			if (!wrapper.value.contains(from)) focusFirst();
+			else
+ /**
+			* 情况3：从作用域内部 Shift+Tab 回来
+			* → 说明用户想“往前”，应跳到最后一个（循环）
+			*/
+			focusLast();
 		}
-		function p() {
-			u();
+		/**
+		* 当焦点进入“结束哨兵”时触发
+		*
+		* 场景：
+		* 用户在最后一个元素按 Tab
+		*
+		* 行为：
+		* → 跳回第一个（形成循环）
+		*/
+		function onFocusEnd() {
+			focusFirst();
 		}
-		return (o, l) => (i(), t("div", {
-			ref_key: "wrapper",
-			ref: c
-		}, [
-			n("div", {
-				tabindex: "0",
-				class: "sentinel-start",
-				onFocus: f
-			}, null, 32),
-			a(o.$slots, "default"),
-			r.tabMode === "soft-loop" ? (i(), t("div", s)) : e("", !0),
-			n("div", {
-				tabindex: "0",
-				class: "sentinel-end",
-				onFocus: p
-			}, null, 32)
-		], 512));
+		/**
+		* 监听 autofocus 属性的变化
+		*
+		* 作用：
+		* 1. 当 autofocus 从 false 变为 true 时，自动聚焦第一个可聚焦元素
+		* 2. 支持动态控制自动聚焦行为（例如在模态框打开时启用）
+		* 3. 该监听的主要作用是，当一个页面有多个作用域时，为了不让后挂载的元素抢占焦点，可以先把autofocus设置为false，在挂载后有自动聚焦需求，再设置为true。比如挂载后的第二作用域可以显示或隐藏。若不是该需求，挂载自动聚焦就足够了
+		*
+		* immediate: true 的意义：
+		* - 组件创建时立即执行一次
+		* - 如果初始 autofocus 为 true，会在挂载后立即聚焦第一个元素
+		* - 避免需要手动调用 focusFirst()
+		*
+		* 使用场景：
+		* - 模态框/对话框打开时自动聚焦第一个输入框
+		* - 表单显示时自动聚焦第一个字段
+		* - 动态切换焦点作用域时重新聚焦
+		*/
+		watch(() => props.autofocus, (newValue) => {
+			if (newValue === true) focusFirst();
+		}, { immediate: true });
+		return (_ctx, _cache) => {
+			return openBlock(), createElementBlock("div", {
+				ref_key: "wrapper",
+				ref: wrapper
+			}, [
+				createElementVNode("div", {
+					tabindex: "0",
+					class: "sentinel-start",
+					onFocus: onFocusStart
+				}, null, 32),
+				renderSlot(_ctx.$slots, "default"),
+				__props.tabMode === "soft-loop" ? (openBlock(), createElementBlock("div", _hoisted_1)) : createCommentVNode("", true),
+				createElementVNode("div", {
+					tabindex: "0",
+					class: "sentinel-end",
+					onFocus: onFocusEnd
+				}, null, 32)
+			], 512);
+		};
 	}
 });
 //#endregion
-export { c as FocusScope, c as default };
+export { FocusScope_default as FocusScope, FocusScope_default as default };

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
     "name": "@zhencai/vue-focus-scope",
     "main": "index.js",
-    "version": "1.0.6",
+    "version": "1.0.7",
     "module": "index.js",
     "peerDependencies": {
         "vue": "^3.0.0"