在 jsdoc 中定义和复用对象类型
· 阅读需 2 分钟
我来介绍几种在 JSDoc 中定义和复用对象类型的方法：
-
使用
@typedef定义类型：/**
* @typedef {Object} User
* @property {string} name - 用户名
* @property {number} age - 年龄
* @property {string} [email] - 可选的邮箱
*/
/**
* 创建新用户
* @param {User} userData - 用户数据
* @returns {User}
*/
function createUser(userData) {
// ...
} -
使用
@typedef定义嵌套对象：/**
* @typedef {Object} Address
* @property {string} street
* @property {string} city
*/
/**
* @typedef {Object} UserWithAddress
* @property {string} name
* @property {Address} address - 用户地址
*/
/**
* @param {UserWithAddress} user
*/
function printUserAddress(user) {
// ...
} -
使用
@callback定义包含函数的对象类型：/**
* @typedef {Object} ConfigOptions
* @property {string} baseUrl
* @property {function(Error): void} onError - 错误处理回调
*/
/**
* @param {ConfigOptions} config
*/
function initialize(config) {
// ...
} -
继承和扩展已有类型：
/**
* @typedef {Object} BaseConfig
* @property {string} env - 环境变量
*/
/**
* @typedef {BaseConfig} ProductConfig
* @property {string} productId - 产品ID
*/
/**
* @param {ProductConfig} config
*/
function setupProduct(config) {
// ...
} -
使用命名空间组织类型：
/**
* @namespace API
*/
/**
* @typedef {Object} API.RequestConfig
* @property {string} url
* @property {string} method
*/
/**
* @typedef {Object} API.Response
* @property {number} status
* @property {*} data
*/
/**
* @param {API.RequestConfig} config
* @returns {Promise<API.Response>}
*/
function request(config) {
// ...
}
这些类型定义可以在整个项目中重复使用。一些实用建议：
- 将常用的类型定义放在单独的文件中，例如
types.js - 为复杂对象添加详细的属性描述
- 使用
@property的可选标记[]来表示可选属性 - 用命名空间避免类型名称冲突
- IDE（如 VSCode）会根据这些类型定义提供代码提示
这样可以让你的代码更容易维护，并提供更好的开发体验。