uni-use

When running in mini-program or mobile app environments, be aware of the following constraints:

• Missing Globals: Certain global variables like window or navigator are unavailable.
• API Dependency: Functionality is limited to what the uni-app APIs can implement (e.g., interceptors, storage). If uni-app doesn't support a feature (like intercepting synchronous APIs or clipboard changes triggered externally), uni-use cannot support it either.
• Top-level Await: Use of top-level await is not supported.

Recommendation: For web-only development, use standard vue and vueuse directly to avoid environment-specific checks and to benefit from the full ecosystem.

When developing for Mini Programs or mobile applications, be aware of the following constraints:

• Missing Globals: Variables like window and navigator are unavailable.
• API Dependency: Functionality is strictly limited to what the uni-app APIs provide (e.g., interceptors, storage). If uni-app does not support a feature (like intercepting synchronous APIs or listening to clipboard changes), @uni-helper/uni-use cannot support it either.
• No Top-level Await: You cannot use top-level await in these environments.

Recommendation: For web-only development, use standard vue instead of uni-app to avoid environment checks and to gain full support for the vueuse ecosystem.

When using @uni-helper/uni-use in a vite + vue3 project, you must set the build target to es6 because the library transpiles non-uni API parts to ES2017. Ensure the @dcloudio/vite-plugin-uni plugin is included in your plugins array.

import uni from '@dcloudio/vite-plugin-uni';
import { defineConfig } from 'vite';

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    target: 'es6',
    cssTarget: 'chrome61', // https://cn.vitejs.dev/config/build-options.html#build-csstarget
  },
  optimizeDeps: {
    exclude: ['vue-demi'],
  },
  plugins: [
    // ...,
    uni(),
    // ...,
  ],
});

The useRequest hook is a wrapper around uni.request designed to align with the API patterns of @vueuse/core (specifically v10.7.1). It provides a reactive way to handle network requests within a UniApp environment.

For detailed implementation patterns and advanced usage, refer to the @vueuse/core useAxios documentation, as useRequest follows a similar mental model.

Note: The return value includes a task object, which allows you to manually control the request (e.g., for aborting the request).

// Note: Implementation details follow @vueuse/core useAxios patterns.
// The return value includes a 'task' object for manual request control.
const { data, error, loading, task } = useRequest(options);

The useSocket hook provides a wrapper around uni-app socket APIs, following the same pattern and API design as @vueuse/core's useWebSocket. It allows you to manage WebSocket connections within a uni-app environment.

Because this is a wrapper for uni-app, you should refer to the VueUse useWebSocket documentation for detailed usage patterns, options, and lifecycle management.

Note: The return value includes a task object which can be used to perform manual socket operations.

// Refer to VueUse documentation for specific implementation details:
// https://vueuse.org/core/useWebSocket/

For vite + vue3 projects, you must set the build target to es6. Additionally, exclude vue-demi from optimizeDeps to ensure compatibility. The @uni-helper/uni-use library uses unbuild to transpile non-uni API parts to ES2017 (ES8), while uni APIs are handled by the official uni-app plugin.

import uni from '@dcloudio/vite-plugin-uni';
import { defineConfig } from 'vite';

// https://vitejs.dev/config/
export default defineConfig({
  build: {
    target: 'es6',
    cssTarget: 'chrome61', // https://cn.vitejs.dev/config/build-options.html#build-csstarget
  },
  optimizeDeps: {
    exclude: ['vue-demi'],
  },
  plugins: [
    // ...,
    uni(),
    // ...,
  ],
});

To pass objects through page navigation, stringify the object and append it to the URL. useQuery will automatically detect and parse these JSON strings back into objects.

Recommended Pattern: Use encodeURIComponent(JSON.stringify(data)) when navigating to ensure special characters are handled correctly.

Example Navigation:

const data = { id: 123, type: 'coal' };
uni.navigateTo({
  url: '/pages/detail?resData=' + encodeURIComponent(JSON.stringify(data))
});

Example Retrieval:

const { value: resData } = useQuery('resData');
// resData.value = { id: 123, type: 'coal' }

// Recommended way to navigate with objects
const data = { id: 123, name: 'test', details: { amount: 50 } };
uni.navigateTo({
  url: `/pages/detail?resData=${encodeURIComponent(JSON.stringify(data))}`
});

Import functions directly from @uni-helper/uni-use. For example, you can use tryOnLoad to safely execute logic during the onLoad lifecycle event in a uni-app environment.

import { tryOnLoad } from '@uni-helper/uni-use';

tryOnLoad(() => {
  console.log('onLoad');
});

Since the library targets environments like mini-programs, you may need to manually add polyfills in your src/main.ts or src/main.js. You can use core-js or es-shims.

Example using core-js:

// You can add additional polyfills as needed
// import 'core-js/actual/object/values'
import { createSSRApp } from 'vue';
import App from './App.vue';
import 'core-js/actual/array/iterator';
import 'core-js/actual/promise';
import 'core-js/actual/object/assign';
import 'core-js/actual/promise/finally';

export function createApp() {
  const app = createSSRApp(App);
  return {
    app,
  };
}

Install @uni-helper/uni-use along with @vueuse/core@9. Note that node >= 18 is required.

If you intend to use @vueuse/core v10 or higher, you must provide your own polyfills or use vite-plugin-uni-polyfill due to compatibility requirements with uni-app.

Package Manager Specifics:

• Yarn (v2+): Set nodeLinker to node_modules in your configuration.
• pnpm: Set shamefully-hoist to true in your .npmrc.

npm install @uni-helper/uni-use @vueuse/core@9