贡献

🌐 Contributing

感谢你有兴趣为本项目做出贡献！

🌐 Thanks for being interested in contributing to this project!

警告：⚠️ 放慢新功能的开发

随着 VueUse 用户群的不断增长，我们收到了大量的功能请求和拉取请求。因此，维护项目变得越来越具有挑战性，并已将我们的能力推向极限。因此，在不久的将来，我们可能需要放慢新功能的接受速度，并优先保证现有功能的稳定性和质量。请注意，目前可能无法接受 VueUse 的新功能。 如果你有任何新想法，我们建议你先将其融入自己的代码库，进行迭代以满足你的需求，并评估其可推广性。如果你坚信你的想法对社区有益，你可以提交一个带有使用案例的拉取请求，我们将乐意进行审核和讨论。感谢你的理解。

开发

🌐 Development

设置

🌐 Setup

将此代码库克隆到本地计算机并安装依赖。

🌐 Clone this repo to your local machine and install the dependencies.

pnpm install

我们使用 VitePress 进行快速开发和文档编写。你可以通过以下方式在本地启动它

🌐 We use VitePress for rapid development and documenting. You can start it locally by

pnpm dev

测试

🌐 Testing

pnpm test:unit # to run unit tests

如果你想使用实验性浏览器测试，则需要先安装 playwright 依赖。

🌐 If you want to use experimental browser tests, you need to install playwright dependencies first.

npx playwright install --with-deps

然后运行

🌐 and then run

pnpm test:browser

贡献

🌐 Contributing

现有函数

🌐 Existing functions

请随意增强现有功能。请尽量不要引入破坏性更改。

🌐 Feel free to enhance the existing functions. Please try not to introduce breaking changes.

新函数

🌐 New functions

添加新功能时有一些注意事项。

🌐 There are some notes for adding new functions

• 开始工作之前，最好先创建一个问题进行讨论。
• 实现应放在 packages/core 作为文件夹，并在 index.ts 中进行暴露
• 在 core 包中，尽量不要引入第三方依赖，因为该包旨在尽可能轻量化。
• 如果你想引入第三方依赖，请贡献到 @vueuse/integrations 或创建一个新的插件。
• 你可以在 packages/core/_template/ 下找到函数模板，详情请参阅 Function Folder 部分。
• 在为你的函数编写文档时，<!--FOOTER_STARTS--> 和 <!--FOOTER_ENDS--> 会在构建时自动更新，因此不需要手动更新它们。

请注意，你无需更新包的 index.ts。它们是自动生成的。

新插件

🌐 New add-ons

非常欢迎新的插件！

🌐 New add-ons are greatly welcome!

• 在 packages/ 下创建一个新文件夹，并将其命名为你的插件名称。
• 在 scripts/packages.ts 中添加附加详情
• 在该文件夹下创建 README.md。
• 像添加核心包一样添加函数。
• 提交并提交为 PR。

项目结构

🌐 Project Structure

Monorepo

我们使用 monorepo 来管理多个软件包。

🌐 We use monorepo for multiple packages

packages
  shared/         - shared utils across packages
  core/           - the core package
  firebase/       - the Firebase add-on
  [...addons]/    - add-ons named

函数文件夹

🌐 Function Folder

一个函数文件夹通常包含以下 4 个文件：

🌐 A function folder typically contains these 4 files:

你可以在 packages/core/_template/ 下找到模板

index.ts            # function source code itself
demo.vue            # documentation demo
index.test.ts       # vitest unit testing
index.md            # documentation

对于 index.ts，你应该使用命名导出函数。

🌐 for index.ts you should export the function with names.

// DO
export { useMyFunction }

// DON'T
export default useMyFunction

对于 index.md，第一句话将作为函数列表中的简短介绍显示，因此尽量保持简洁明了。

🌐 for index.md the first sentence will be displayed as the short intro in the function list, so try to keep it brief and clear.

# useMyFunction

This will be the intro. The detail descriptions...

阅读有关指南的更多信息。

🌐 Read more about the guidelines.

代码风格

🌐 Code Style

只要安装了开发依赖，就不用担心代码风格。Git 钩子会在提交时帮你格式化和修复代码。

🌐 Don't worry about the code style as long as you install the dev dependencies. Git hooks will format and fix them for you on committing.

@__NO_SIDE_EFFECTS__ 带有函数重载

🌐 @__NO_SIDE_EFFECTS__ with function overloads

对于重载函数，在两个地方添加 @__NO_SIDE_EFFECTS__：

🌐 For overloaded functions, add @__NO_SIDE_EFFECTS__ in two places:

1. 在公共 JSDoc 中，用于 API 文档。
2. 就在实现之前，用于构建工具。

/**
 * ...
 *
 * @__NO_SIDE_EFFECTS__
 */
export function useFoo(value: string): string
export function useFoo(value: number): number
/* @__NO_SIDE_EFFECTS__ */
export function useFoo(value: string | number): string | number {
  // ...
}

TypeScript 在编译时会移除重载签名，所以 JSDoc 注解不会传到打包工具。把一行注解放在实现前就行，不需要重复整个 JSDoc。

🌐 TypeScript removes overload signatures during compilation, so the JSDoc annotation does not reach the bundler. Keep the one-line annotation before the implementation; there is no need to duplicate the full JSDoc.

@__NO_SIDE_EFFECTS__ 与箭头函数

🌐 @__NO_SIDE_EFFECTS__ with arrow functions

对于箭头函数，把紧凑构建注释放在函数表达式前面，这样打包工具才能识别它。

🌐 For arrow functions, place the compact build annotation immediately before the function expression for the bundler to recognize it.

export const useFoo: () => void = /* @__NO_SIDE_EFFECTS__ */ () => {
  // ...
}

不要在 const 声明的前置 JSDoc 中包含魔法 @__NO_SIDE_EFFECTS__ 标签。与重载签名不同，声明及其 JSDoc 会被输出到 JavaScript。这样标签就会出现在变量声明之前，而不是函数表达式之前，可能会触发打包工具的无效注解警告。

🌐 DO NOT include the magic @__NO_SIDE_EFFECTS__ tag in the leading JSDoc of a const declaration. Unlike overload signatures, the declaration and its JSDoc are emitted to JavaScript. The tag would then appear before the variable declaration instead of the function expression and may trigger an invalid-annotation warning from the bundler.

如果你想把信息展示给人类读者，考虑在普通的散文中使用 @NO_SIDE_EFFECTS（不带 __）。它会被打包器忽略，所以不会触发任何警告。

🌐 If you want to present the information to human readers, consider using @NO_SIDE_EFFECTS (without the __) in ordinary prose instead. It will be ignored by the bundler so it won't trigger any warnings.

/**
 * ...
 *
- * @__NO_SIDE_EFFECTS__
+ * @NO_SIDE_EFFECTS
 */
export const useFoo: () => void = /* @__NO_SIDE_EFFECTS__ */ () => {
  // ...
}

感谢

🌐 Thanks

再次感谢你对这个项目的关注！你真棒！

🌐 Thank you again for being interested in this project! You are awesome!