{"id":21296979,"url":"https://github.com/s3xysteak/vfetcher","last_synced_at":"2026-02-14T18:01:35.050Z","repository":{"id":250451857,"uuid":"834531801","full_name":"s3xysteak/vfetcher","owner":"s3xysteak","description":"Vue composables for fetching data, based on unjs/ofetch","archived":false,"fork":false,"pushed_at":"2024-11-22T01:50:34.000Z","size":299,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-12T23:56:04.776Z","etag":null,"topics":["composables","fetch","ofetch","request","utils","vue"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/s3xysteak.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-27T14:54:26.000Z","updated_at":"2024-11-22T01:50:37.000Z","dependencies_parsed_at":"2024-08-02T08:51:49.594Z","dependency_job_id":"9c27df57-7254-4e32-bf10-82f6edb303ef","html_url":"https://github.com/s3xysteak/vfetcher","commit_stats":null,"previous_names":["s3xysteak/vfetcher","s3xysteak/vfetch"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/s3xysteak/vfetcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s3xysteak%2Fvfetcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s3xysteak%2Fvfetcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s3xysteak%2Fvfetcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s3xysteak%2Fvfetcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s3xysteak","download_url":"https://codeload.github.com/s3xysteak/vfetcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s3xysteak%2Fvfetcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29451904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T15:52:44.973Z","status":"ssl_error","status_checked_at":"2026-02-14T15:52:11.208Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composables","fetch","ofetch","request","utils","vue"],"created_at":"2024-11-21T14:31:29.477Z","updated_at":"2026-02-14T18:01:35.036Z","avatar_url":"https://github.com/s3xysteak.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vfetcher\n\n[English](/README.md) | 简体中文\n\n用于数据请求的Vue组合式函数, 基于 [unjs/ofetch](https://github.com/unjs/ofetch)。\n\n```sh\n$ pnpm i vfetcher\n```\n\n## 特性\n\n- 精心设计的API: 刻意模仿 [nuxt/useFetch](https://nuxt.com.cn/docs/api/composables/use-fetch) 的api，以尽可能保持一致性，减少迁移负担。\n- 更多功能: 开箱即用的 节流/防抖/轮询/分页...以及将来更多功能！\n\n## 使用\n\n\u003e 访问 [examples](/examples/src/) 以查看配置示例，访问 [test](/test/) 以查看使用示例。\n\n### 重导出 ofetch\n\n`vfetcher` 重导出了 `ofetch` 的全部导出，以方便直接使用ofetch：\n\n```ts\nimport { $fetch } from 'vfetcher/ofetch'\n```\n\n### 基本示例\n\nuseAsyncData第一个参数为回调函数，第二个参数为其配置项。默认情况下会在初始化时自动调用回调：\n\n```ts\nimport { useAsyncData } from 'vfetcher'\n\nconst { data } = useAsyncData(() =\u003e $fetch('/return-ok'))\nwatchEffect(() =\u003e {\n  console.log(data.value) // Ref\n  // -\u003e null\n  // -\u003e 'ok'\n})\n```\n\n通过 `immediate: false` 选项避免在初始化时自动发出请求：\n\n```ts\nconst { data, execute, refresh } = useAsyncData(() =\u003e $fetch('return-ok'), {\n  immediate: false\n})\n\nwatchEffect(() =\u003e {\n  console.log(data.value)\n})\n\n// -\u003e null\n\n// await refresh() // as alias of execute\nawait execute()\n\n// -\u003e 'ok'\n```\n\n`watch` 选项接受与 Vue 的 `watch` 第一个参数相同的值。在这些响应式变量发生改变时，将会自动发出请求：\n\n```ts\nconst dep = ref('foo')\nuseAsyncData(() =\u003e $fetch('ok'), {\n  watch: [dep]\n})\n// request to =\u003e 'ok'\ndep.value = 'bar'\n// request to =\u003e 'ok'\n```\n\n`ready` 选项接受响应式布尔值，或是返回布尔值的函数。只有在结果为true时发出请求，结果为false时立即结束execute且不发出请求。这在使用依赖请求、又对请求条件有要求时很有用：\n\n```ts\nconst ready = ref(false)\nconst { execute } = useAsyncData(() =\u003e $fetch('ok'), {\n  immediate: false,\n  ready\n})\nawait execute()\n// the promise will be resolved immediately and no request will be send\nready.value = true\nawait execute()\n// request to =\u003e 'ok'\n```\n\nuseAsyncData的返回值 `status` 表示了当前状态，通过对status的监听，你可以实现在不同情况下的回调。status 在最初总是`idle`表示空闲，在请求发出前变为`pending`表示等待响应，请求成功后变为`success`表示成功，或者在失败时变为`error`表示请求失败：\n\n```ts\nconst { status } = useAsyncData(() =\u003e $fetch('ok'))\n\n// Equal to `onSuccess` hook:\nwatch(status, (v) =\u003e {\n  if (v !== 'success')\n    return\n\n  onSuccess()\n})\n```\n\n通过 `transform` 选项对返回值进行预处理:\n\n```ts\nconst { data } = useAsyncData(() =\u003e $fetch('post', {\n  method: 'post',\n  body: {\n    number: {\n      one: 1\n    }\n  }\n}), {\n  transform: (res: { number: { one: 1 } }) =\u003e res.number.one\n})\n\n// request to =\u003e 'post'\n// response `{ number: { one: 1 } }`\ndata.value === 1 // true\n```\n\n通过 `pollingInterval` 选项以进行轮询请求：\n\n```ts\nuseAsyncData(() =\u003e $fetch('ok'), {\n  pollingInterval: 2000 // 2 seconds\n})\n\n// request to =\u003e 'ok'\n// wait 2 seconds...\n// request to =\u003e 'ok'\n\nconst { execute } = useAsyncData(() =\u003e $fetch('ok'), {\n  pollingInterval: 2000, // 2 seconds\n  immediate: false\n})\n\n// ...\n// Will not poll until `execute` is called for the first time.\n\nawait execute() // request to =\u003e 'ok'\n// wait 2 seconds...\n// request to =\u003e 'ok'\n```\n\n通过 `debounceInterval` 选项以进行防抖：\n\n```ts\nconst { execute } = useAsyncData(() =\u003e $fetch('ok'), {\n  debounceInterval: 2000 // 2 seconds\n})\n\nawait execute()\n// request to =\u003e 'ok'\nexecute()\nexecute()\n\n// after about 2 seconds\n// request to =\u003e 'ok'\n```\n\n通过 `throttleInterval` 选项以进行节流：\n\n```ts\nconst { execute } = useAsyncData(() =\u003e $fetch('ok'), {\n  throttleInterval: 2000 // 2 seconds\n})\n\nawait execute()\n// request to =\u003e 'ok'\nexecute()\nexecute()\n\n// after about 2 seconds\nawait execute()\n// request to =\u003e 'ok'\n```\n\n### 自定义默认参数\n\n你可以自定义 `useAsyncData` 以设置你最喜欢的默认选项：\n\n```ts\nimport { useAsyncData as $ } from 'vfetcher'\n\nexport const useAsyncData = $.create({\n  immediate: false\n})\n\nconst { execute } = useAsyncData(() =\u003e $fetch('ok'))\n// ...\nawait execute()\n```\n\n新的 `useAsyncData` 会继承前一个的默认选项：\n\n```ts\nimport { useAsyncData as $1 } from 'vfetcher'\n\nconst $2 = $1.create({\n  debounceInternal: 150\n})\nconst useAsyncData = $2.create({\n  immediate: false\n})\n\nuseAsyncData(() =\u003e $fetch('ok'))\n// Equal to:\n// `useAsyncData(() =\u003e $fetch('ok'), { debounceInternal: 150, immediate: false })`\n```\n\n### 返回值\n\n除了 `execute/refresh` 以外，其他变量都由`ref`包装：\n\n- `data`: 异步请求返回的结果，默认为 `null`，结果为 `ofetch` 返回值。\n- `pending`: 一个布尔值，指示数据是否仍在获取中。\n- `error`: 如果数据获取失败，则为错误对象，否则为 `null`。\n- `status`: 表示数据请求的状态的字符串 `(idle、pending、success、error)`\n- `execute/refresh`: 用于手动调用请求的**函数**。\n\n### 选项\n\n- `immediate`: 一个布尔值，指示是否要在初始化时发出请求。默认为true。\n- `watch`: 监听一组响应式源，与 Vue `watch`方法的第一个参数类型相同。在响应源发生变化时，将会重新发出请求。默认情况下会监听请求URL和请求参数（详见下文），你也可以手动将其设置为false以关闭该功能。\n- `transform`: 一个在解析后可以用来修改 handler 结果的函数。\n- `default`: 一个函数，其返回值作为上文中 `data` 的初始值。\n- `pollingInterval`: 可以是响应式值。传入一个`number`，单位为毫秒，用于指示轮询的间隔时间。默认不进行轮询。\n- `debounceInterval`: 可以是响应式值。传入一个`number`，单位为毫秒，用于指示防抖的延迟时间。默认不进行防抖。\n- `throttleInterval`: 可以是响应式值。传入一个`number`，单位为毫秒，用于指示节流的等待时间。默认不进行节流。\n\n## useFetch\n\nuseFetch几乎是useAsyncData与ofetch的结合：\n\n- 第一个参数与ofetch第一个参数基本相同。\n- 第二个参数同时接受useAsyncData和ofetch的全部配置项。\n- 返回值与useAsyncData相同。\n\n得益于ofetch，数据会被自动转换为合适的类型：\n\n```ts\nconst { data: d1 } = useFetch('/return-ok')\nwatchEffect(() =\u003e {\n  console.log(d1.value)\n  // -\u003e null\n  // -\u003e 'ok'\n})\n\nconst { data: d2 } = useFetch('/return-json')\nwatchEffect(() =\u003e {\n  console.log(d2.value)\n  // -\u003e null\n  // -\u003e { one: 1 }\n})\n```\n\n请求路径、请求头、请求query、请求体等一系列请求参数可以传入响应式值，这会在其改变时自动发出请求：\n\n```ts\nconst url = ref('return-ok')\nconst query = ref({ one: '1' })\nconst { data } = useFetch(url, { query })\nwatchEffect(() =\u003e {\n  console.log(data.value)\n})\n\n// -\u003e null\n// -\u003e 'ok'\n\nurl.value = 'return-query'\n\n// -\u003e { one: '1' }\n\nquery.value = { two: '2' }\n\n// -\u003e { two: '2' }\n```\n\n与useAsyncData相同，你也可以配置你喜欢的默认参数，详见上文：\n\n```js\nimport { useFetch as $ } from 'vfetcher'\n\nexport const useFetch = $.create({\n  // ...\n})\n```\n\nuseFetch拥有与useAsyncData相同的返回值及其全部选项。他还接受ofetch的全部选项，其中默认情况下会监听ofetch的以下参数：\n\n- `URL`: 请求的路径URL。\n- `method`: 请求的方法类型。\n- `query`: 查询参数。\n- `params`: 只是`query`的别名。\n- `body`: 请求体。\n- `headers`: 请求头。\n- `baseURL`: 请求的基础路径。\n\n\u003e ... 其他 `ofetch` 的一般选项，请查阅 [ofetch 官方文档](https://github.com/unjs/ofetch) 。\n\n## 分页\n\n使用 `usePagination` 方法处理分页。\n\n`import { usePagination } from 'vfetcher'`\n\n### 基本使用\n\nusePagination是基于useFetch封装的：\n\n- 第一个参数与usePagination相同。\n- 第二个参数是配置项，拥有useFetch的全部配置。\n- 返回值中，拥有useFetch的全部返回值。\n\n你可以直接使用useFetch的配置项：\n\n```ts\nusePagination('ok', {\n  immediate: false\n})\n```\n\n它自动的将分页参数合并到query内：\n\n```ts\nusePagination('getByPage')\n// request to =\u003e `/getByPage?current=1\u0026pageSize=10`\n```\n\n相比于`useFetch`新增了一些返回值，他们同样是响应式的：\n\n```ts\nconst { pageCurrent } = usePagination('getByPage')\n// request to =\u003e `/getByPage?current=1\u0026pageSize=10`\npageCurrent.value = 2\n// request to =\u003e `/getByPage?current=2\u0026pageSize=10`\n```\n\n通过 `lodash - get` 获取分页大小与数据总数，你也可以手动进行配置：\n\n```ts\nconst { data, total } = usePagination('getByPage', {\n  totalKey: 'res.total'\n})\nwatchEffect(() =\u003e {\n  console.log(data.value)\n\n  if (data.value)\n    console.log(total.value)\n})\n\n// -\u003e null\n// -\u003e { res: { total:10, data:[ /* ... */]} }\n// -\u003e 10\n```\n\n与useFetch相同，你也可以配置你喜欢的默认参数，详见上文：\n\n```js\nimport { usePagination as $ } from 'vfetcher'\n\nexport const usePagination = $.create({\n  // ...\n})\n```\n\n### 新增的返回值与选项\n\nusePagination拥有useFetch的全部选项和返回值，除此以外，还新增了一些其专属的选项与返回值。\n\n所有新增返回值都是响应式变量：\n\n- `pageCurrent`: 表示当前页码的数字 (number)。\n- `pageSize`: 表示单页数量的数字 (number)。\n- `total`: 表示数据总数的只读数字 (read-only number)。\n- `pageTotal`: 表示页码总数的只读数字 (read-only number)。\n\n新增的选项：\n\n- `pageCurrentKey`: 表示当前页码的键名，用于在query中传递。默认为`'current'`。\n- `pageSizeKey`: 表示单页数量的键名，用于在query中传递。默认为`'pageSize'`。\n- `defaultPageSize`: 表示默认单页数量的number，在`immediate: true`时很有用。 默认为`10`。\n- `totalKey`: 获取数据总数的键名，通过`lodash - get`在返回数据中获取。默认为`'total'`。\n- `pageTotalKey`: 获取页码总数的键名，通过`lodash - get`在返回数据中获取。默认为`'totalPage'`。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs3xysteak%2Fvfetcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs3xysteak%2Fvfetcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs3xysteak%2Fvfetcher/lists"}