VueUse 中文网

主题

贡献 ​

¥Contributing

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

¥Thanks for being interested in contributing to this project!

警告：⚠️ 新功能加载速度减慢

¥Warning: ⚠️ Slowing down new functions

随着 VueUse 用户的不断增长，我们收到了大量的功能请求和拉取请求。因此，维护项目变得越来越具有挑战性，并且已经达到了我们能力的极限。因此，在不久的将来，我们可能需要放慢接受新功能的速度，并优先考虑现有功能的稳定性和质量。请注意，目前可能不接受 VueUse 的新功能。如果你有任何新想法，我们建议你首先将其融入你自己的代码库中，并根据你的需求进行迭代，并评估其通用性。如果你坚信你的想法对社区有益，你可以提交拉取请求 (PR) 并附上你的用例，我们很乐意审核并讨论。感谢你的理解。

¥As the VueUse audience continues to grow, we have been inundated with an overwhelming number of feature requests and pull requests. As a result, maintaining the project has become increasingly challenging and has stretched our capacity to its limits. As such, in the near future, we may need to slow down our acceptance of new features and prioritize the stability and quality of existing functions. Please note that new features for VueUse may not be accepted at this time. If you have any new ideas, we suggest that you first incorporate them into your own codebase, iterate on them to suit your needs, and assess their generalizability. If you strongly believe that your ideas are beneficial to the community, you may submit a pull request along with your use cases, and we would be happy to review and discuss them. Thank you for your understanding.

开发 ​

¥Development

设置 ​

¥Setup

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

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

bash
pnpm install

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

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

bash
pnpm dev

测试 ​

¥Testing

bash
pnpm test:unit # to run unit tests

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

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

bash
nlx playwright install --with-deps

然后运行

¥and then run

bash
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

  • 开始工作之前，最好先创建一个问题进行讨论。

    ¥Before you start working, it's better to open an issue to discuss first.

  • 实现应该作为文件夹放在 packages/core 下，并在 index.ts 中公开。

    ¥The implementation should be placed under packages/core as a folder and exposing in index.ts

  • 在 core 软件包中，尽量不要引入第三方依赖，因为该软件包的目标是尽可能轻量级。

    ¥In the core package, try not to introduce 3rd-party dependencies as this package is aimed to be as lightweight as possible.

  • 如果你想引入第三方依赖，请为 @vueuse/integrations 做出贡献或创建新的插件。

    ¥If you'd like to introduce 3rd-party dependencies, please contribute to @vueuse/integrations or create a new add-on.

  • 你可以在 packages/core/_template/ 下找到函数模板，详细信息请参阅 函数文件夹 部分。

    ¥You can find the function template under packages/core/_template/, details explained in the Function Folder section.

  • 在为你的函数编写文档时，<!--FOOTER_STARTS--> 和 <!--FOOTER_ENDS--> 将在构建时自动更新，因此无需更新它们。

    ¥When writing documentation for your function, the <!--FOOTER_STARTS--> and <!--FOOTER_ENDS--> will be automatically updated at build time, so don't feel the need to update them.

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

¥Please note you don't need to update packages' index.ts. They are auto-generated.

新插件 ​

¥New add-ons

非常欢迎新的插件！

¥New add-ons are greatly welcome!

  • 在 packages/ 下创建一个新文件夹，并将其命名为你的插件名称。

    ¥Create a new folder under packages/, name it as your add-on name.

  • 在 scripts/packages.ts 中添加插件详细信息

    ¥Add add-on details in scripts/packages.ts

  • 在该文件夹下创建 README.md。

    ¥Create README.md under that folder.

  • 像添加核心包一样添加函数。

    ¥Add functions as you would do to the core package.

  • 提交并提交为 PR。

    ¥Commit and submit as a 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/ 下找到该模板。

¥You can find the template under packages/core/_template/

bash
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.

ts
// 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.

markdown
# useMyFunction

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

了解更多关于 guidelines 的信息。

¥Read more about the guidelines.

代码风格 ​

¥Code Style

只要安装了开发依赖，就无需担心代码风格。Git hooks 会在提交时为你格式化和修复它们。

¥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.

感谢 ​

¥Thanks

再次感谢你对本项目的关注！你太棒了！

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