Vue3 笔记1.JSDoc 规范的类型注释 JSDoc 规范的类型注释是一种基于注释的代码文档规范，主要用于描述 Ja

1.JSDoc 规范的类型注释

JSDoc 规范的类型注释是一种基于注释的代码文档规范，主要用于描述 JavaScript（及 TypeScript、Vue 等基于 JS 的语言）中变量、函数、类、类型等的结构和类型信息。它通过特定的标签（如 @param、@returns、@typedef 等）来定义类型约束和文档说明，既能生成可读性强的 API 文档，又能帮助 IDE 提供类型提示、自动补全和错误检查。

以注释形式存在，不影响代码运行（纯 JS 环境也可使用）,在微信小程序和 uni-app 中完全可以使用 JSDoc 规范的类型注释

@typedef 是 JSDoc 的标签，用于定义一个自定义类型。
@property 是 JSDoc 标签，用于描述对象类型的属性。

例如：

    /**
     * 表示坐标位置的类型
     * @typedef {Object} Position  
     * @property {number} x - 水平坐标
     * @property {number} y - 垂直坐标
     */

{Object} Position ： {Object} 表示这个自定义类型是一个对象类型。 Position 是自定义类型的名称。

@property {number} x ： {number} 表示该属性的类型是数值型。x 是属性名。

具体例子：

@typedef：定义自定义类型（如对象结构、复杂类型）

/**
* 表示坐标位置的类型
* @typedef {Object} Position
* @property {number} x - 水平坐标
* @property {number} y - 垂直坐标
*/

@returns：描述函数返回值的类型

/**
* 获取元素当前位置
* @returns {Position} 元素的坐标信息
*/
function getElementPosition() {
 return { x: 100, y: 200 };
}

@param：描述函数参数的类型和含义

/**
 * 移动元素到指定位置
 * @param {Position} position - 目标位置
 * @param {boolean} [animate=false] - 是否启用动画（可选参数）
 */
function moveTo(pos, animate) { ... }

标注变量的类型

/** @type {Position} */
let startPos = { x: 0, y: 0 };

@template：定义泛型类型（适用于通用组件 / 函数）

/**
 * 包装数据的容器
 * @template D
 * @param {D} data - 要包装的数据
 * @returns {{ value: D }} 包装后的对象
 */
function wrap(data) {
  return { value: data };
}

js中

/**
 * 用户信息类型
 * @typedef {Object} UserInfo
 * @property {string} id - 用户唯一标识
 * @property {string} name - 用户名
 * @property {number} age - 年龄
 */

/**
 * 获取用户信息
 * @param {string} userId - 用户ID
 * @returns {Promise<UserInfo>} 用户信息对象
 */
function getUserInfo(userId) {
  return new Promise((resolve) => {
    // 模拟接口请求
    resolve({ id: userId, name: '张三', age: 20 });
  });
}

方法中

const handleRestore = (/** @type {SizeData} */ data) => {
    minHeight.value = data.height
}

浏览器原生的 MouseEvent 对象

/**
 * 鼠标移动时更新位置
 * @param {MouseEvent} e - 鼠标事件
 */
 
 const onMouseMove = (e) => {}

2. Vue 3 Composition API

Vue 3 Composition API 按需导入，如：import { defineEmits, ref, onMounted, computed } from 'vue

1.只导入实际需要的 AP，减少最终打包生成的 JS 文件大小，提升页面加载速度。

2.减少不必要的代码加载和解析，降低浏览器的资源消耗，提升应用运行时性能。

3.代码中清晰展示了组件实际依赖的 API，增强了代码的可读性和可维护性，开发者能快速了解组件使用了哪些核心功能。

4.只引入需要的 API，减少了全局作用域中变量 / 函数的数量，降低了命名冲突的风险。

3.props 接受参数

例子：

const props = defineProps({ 
isRun:{
    type: Boolean,
    required: true, 
    default: false, 
    description: '控制运行窗口的显示与隐藏' 
    }
})

Vue 3 提供的defineProps宏函数，用于声明组件接收的外部属性，调用后会返回一个包含所有 props 的对象，赋值给变量props，组件外部传递的属性都可以通过props对象访问（如props.isRunning）。

isRun:{} 定义了一个名为isRun的属性，这是组件对外暴露的接口。

type：指定isRun属性的类型为布尔值（true或false）， Vue 会自动进行类型校验，如果父组件传递非布尔值会在控制台警告。

required：标记该属性为必需项，父组件使用该组件时必须传递此属性，如果未传递，Vue 会在控制台抛出警告。

default：设置属性的默认值，当required: true时，这个默认值实际上不会生效（因为必须传递）

description：对该属性的功能进行描述，主要用于代码文档化，提高可读性。

4.ref

ref是 Vue 3 提供的响应式 API，用于创建一个响应式数据对象。

例子：

const position = ref({ x: 40, y: 10 })

创建了一个响应式的位置信息对象position。
当x或y的值发生变化时，Vue 会自动更新所有使用该数据的视图部分。
可以通过position.value.x和position.value.y访问或修改其值。

5.v-model

用于实现表单元素双向数据绑定的语法。v-model:value 简写 v-model

例子：

<template>
  <textarea v-model:value="textareaValue" />
</template>

    <script setup>
    import { ref } from 'vue'
    // 声明响应式变量
    const textareaValue = ref('初始内容')
    </script>

6.属性传递（父传子）事件监听（子传父）

const executeVal = ref(false)
<runHeader ref="headerRef" :execute="executeVal" @closed-run="handleClose"  />

子组件中接收：

// 接受父组件传值
const props = defineProps({
    execute: {//执行文字
        type: Boolean,
        required: true, // 标记为必需，便于发现传递问题
        default: false,
        description: '控制执行文字提示显示与隐藏'
    }
})

子组件中定义可触发的事件

//声明组件可触发事件的方式,允许子组件通过 emit 方法触发
const emit = defineEmits(['closed-run'])

//表示子组件主动触发 `closed-run` 事件，并传递了一个 `false` 作为参数
emit('closed-run', false)


父组件中:<runHeader @closed-run="handleClose" />

// 父组件会监听到这个事件，并调用自身的 `handleClose` 方法
@closed-run="handleClose"

execute="executeVal" 是一个动态属性绑定，将父组件中的 executeVal 变量传递给子组件的 execute 属性，通常用于控制组件的执行状态

@closed-run="handleClose"：监听子组件触发的 closed-run 事件，触发时调用父组件的 handleClose 方法

Vue3 笔记