useSend & XRequest 🌳

XRequest is deprecated, recommend using hook-fetch (https://jsonlee12138.github.io/hook-fetch/)

Background Introduction

Based on ant-design-x's XRequest and XStream, we conducted in-depth learning and discussion.

After replicating XStream, for more general scenarios of controlling request data and aborting requests, we refactored ant-design-x's XRequest and split it into Frontend Termination Scenarios and Request Termination Scenarios

These two scenarios correspond to:

• hooks useSend -- Frontend termination scenarios
• utility class XRequest -- Request termination scenarios

🍒 Both can be used separately, and when combined they can implement useXStream. Below are their usage examples

Code Demonstration

You only need to pass a start method to get the corresponding loading state and finish method.

Single control, code doesn't exceed 10 lines

useSend Basic Usage (Standalone)

This example clearly shows that this hook doesn't interact with backend requests, it only controls simple loading state.

send method triggers sendHandler callback finish method ends loading state

<script setup lang="ts">
import { useSend } from 'vue-element-plus-x';

const { send, finish, loading } = useSend({
  sendHandler: startFn
});

async function startFn() {
  // Here you can do an async operation, such as making a request
  console.log('Start simulating request');
}
</script>

<template>
  <div class="container">
    <div class="btn-list">
      <el-button :disabled="loading" type="primary" @click="send">
        {{ loading ? 'Loading...' : 'Simulate Request' }}
      </el-button>

      <el-button :disabled="!loading" @click="finish">
        End Request
      </el-button>
    </div>
  </div>
</template>

With control over the state, we can easily customize loading states for some buttons

useSend Usage Scenarios (Standalone)

sendHandler and abortHandler are two functions, corresponding to the callbacks for start and abort.

The abort method triggers the abortHandler callback.

The abort method will also end the loading state.

<script setup lang="ts">
import {
  Aim,
  Loading,
  Microphone,
  Promotion,
  Refresh,
  VideoCamera,
  VideoPause,
  VideoPlay
} from '@element-plus/icons-vue';
import { useSend } from 'vue-element-plus-x';

const { send, abort, loading } = useSend({
  sendHandler: startFn,
  abortHandler: () => {
    ElMessage.info('Custom voice button, end recording!');
  }
});

const {
  send: send1,
  abort: abort1,
  loading: loading1
} = useSend({
  sendHandler: startFn,
  abortHandler: () => {
    ElMessage.info('Custom send button, end sending!');
  }
});

const {
  send: send2,
  abort: abort2,
  loading: loading2
} = useSend({
  sendHandler: startFn,
  abortHandler: () => {
    ElMessage.info('Custom play button, end playing!');
  }
});

const {
  send: send3,
  abort: abort3,
  loading: loading3
} = useSend({
  sendHandler: startFn,
  abortHandler: () => {
    ElMessage.info('Custom record button, end recording!');
  }
});

const type = ref('voice');

function startFn() {
  if (type.value === 'voice') {
    // Here you can do an async operation, such as making a request
    ElMessage.success('Custom voice button, start recording!');
  }
  else if (type.value === 'sender') {
    ElMessage.success('Custom send button, start sending text!');
  }
  else if (type.value === 'read') {
    ElMessage.success('Custom play button, start playing!');
  }
  else if (type.value === 'record') {
    ElMessage.success('Custom record button, start recording!');
  }
}
</script>

<template>
  <div class="btn-list">
    <!-- Voice button -->
    <el-button
      v-if="!loading"
      color="#9145c8"
      circle
      size="large"
      @click="
        () => {
          type = 'voice';
          send();
        }
      "
    >
      <el-icon><Microphone /></el-icon>
    </el-button>

    <el-button
      v-if="loading"
      color="#9145c8"
      circle
      size="large"
      @click="
        () => {
          type = 'voice';
          abort();
        }
      "
    >
      <el-icon class="is-loading">
        <Loading />
      </el-icon>
    </el-button>

    <!-- Send button -->
    <el-button
      v-if="!loading1"
      color="#c2306a"
      round
      plain
      size="large"
      @click="
        () => {
          type = 'sender';
          send1();
        }
      "
    >
      <el-icon><Promotion /></el-icon>
    </el-button>

    <el-button
      v-if="loading1"
      color="#c2306a"
      round
      plain
      size="large"
      @click="
        () => {
          type = 'sender';
          abort1();
        }
      "
    >
      <el-icon class="is-loading">
        <Refresh />
      </el-icon>
    </el-button>

    <!-- Play button -->
    <el-button
      v-if="!loading2"
      size="large"
      type="success"
      color="#ff7f7f"
      @click="
        () => {
          type = 'read';
          send2();
        }
      "
    >
      <el-icon style="font-size: 20px; color: #fff">
        <VideoPlay />
      </el-icon>
    </el-button>

    <el-button
      v-if="loading2"
      size="large"
      type="success"
      color="#ff7f7f"
      @click="
        () => {
          type = 'read';
          abort2();
        }
      "
    >
      <el-icon style="font-size: 20px; color: #fff" class="is-loading">
        <VideoPause />
      </el-icon>
    </el-button>

    <!-- Record button -->
    <el-button
      v-if="!loading3"
      size="large"
      circle
      color="#fff884"
      @click="
        () => {
          type = 'record';
          send3();
        }
      "
    >
      <el-icon style="color: #104674">
        <VideoCamera />
      </el-icon>
    </el-button>

    <el-button
      v-if="loading3"
      size="large"
      circle
      color="#fff884"
      @click="
        () => {
          type = 'record';
          abort3();
        }
      "
    >
      <el-icon style="color: #104674" class="is-loading">
        <Aim />
      </el-icon>
    </el-button>
  </div>
</template>

After understanding the basic usage of useSend, since there's control over frontend loading state, there must also be request state control. Next, let's introduce the simple usage of the utility class XRequest.

XRequest Basic Usage (Standalone)

This way you can simply use XRequest to control the initiation and aborting of requests and their states. A simple new XRequest() instantiates the object, then .send() starts the request, .abort() stops the request.

You can check the console to see that the streaming request has been terminated.

<script setup lang="ts">
import { XRequest } from 'vue-element-plus-x';

const str = ref('');

const sse = new XRequest({
  baseURL: 'https://node-test.element-plus-x.com',
  onMessage: (msg: { data: string }) => {
    console.log('onMessage:', msg);
    str.value += `\n    ${msg.data}`;
  }
});
</script>

<template>
  <div class="container">
    <div class="btn-list">
      <el-button
        @click="
          () => {
            str = '';
            sse.send('/api/sse');
          }
        "
      >
        Start Request
      </el-button>

      <el-button @click="sse.abort()">
        Abort Request
      </el-button>
    </div>

    <div>{{ str }}</div>
  </div>
</template>

📌 Warning

Here, to make it convenient for everyone to read the documentation and see the requests, we've written a simple node service. In this example, 💩 please don't click frantically. It will make frantic requests to the interface, please be moderate. 💩 We haven't done any security processing 🙉 because we won't

This can also help everyone better understand the usage of the utility class XRequest, which only handles requests.

XRequest All Properties (Standalone)

Pass the corresponding configuration items in new XRequest()

transformer can process and transform the response data, and many configuration callback methods are also provided for developers to use.

You can also check the console to see the printout of the callback methods.

<script setup lang="ts">
import { XRequest } from 'vue-element-plus-x';

const str = ref('');

const sse = new XRequest({
  baseURL: 'https://node-test.element-plus-x.com',
  type: 'fetch',
  transformer: e => {
    console.log('transformer:', e);
    const a = e.trim().split('\n');
    const r = a.pop();
    return r;
  },
  onMessage: msg => {
    console.log('onMessage:', msg);
    str.value += `\n${msg}`;
  },
  onError: (es, e) => {
    console.log('onError:', es, e);
  },
  onOpen: () => {
    console.log('onOpen');
  },
  onAbort: messages => {
    console.log('onAbort', messages);
  },
  onFinish: data => {
    console.log('onFinish:', data);
  }
});
</script>

<template>
  <div class="container">
    <div class="btn-list">
      <el-button
        @click="
          () => {
            str = '';
            sse.send('/api/sse');
          }
        "
      >
        Start Request
      </el-button>

      <el-button @click="sse.abort()">
        Abort Request
      </el-button>
    </div>

    <div>{{ str }}</div>
  </div>
</template>

Below, let's introduce the combined usage of useSend and useSendStream

Use useSend to control frontend state, use useSendStream to control backend state

useSend & XRequest Combined Usage

<script setup lang="ts">
import { Promotion, Refresh } from '@element-plus/icons-vue';
import { useSend, XRequest } from 'vue-element-plus-x';

const str = ref<string>('');
let finish = () => {};

const sse = new XRequest({
  baseURL: 'https://node-test.element-plus-x.com',
  type: 'fetch',
  transformer: e => {
    console.log('transformer:', e);
    const a = e.trim().split('\n');
    const r = a.pop();
    return r;
  },
  onMessage: msg => {
    console.log('onMessage:', msg);
    str.value += `\n${msg}`;
  },
  onError: (es, e) => {
    console.log('onError:', es, e);
  },
  onOpen: () => {
    console.log('onOpen');
  },
  onAbort: messages => {
    console.log('onAbort', messages);
  },
  onFinish: data => {
    console.log('onFinish:', data);
    // When called here, eslint will report an error saying 'finish' was used before it was defined.
    // We only defined an empty finish method above and assign it below.
    // Actually, this just executes the finish method from useSend.
    finish();
  }
});

function startFn() {
  str.value = '';
  sse.send('/api/sse');
}

// The abort and finish methods of useSend are the same.
// To demonstrate that xrequest requests support manual abort and finish callbacks,
// a method named finish is also exposed in useSend.
const {
  send,
  loading,
  abort,
  finish: _finish
} = useSend({
  sendHandler: startFn,
  abortHandler: sse.abort
});

// Assign to top-level variable
finish = _finish;
</script>

<template>
  <div class="btn-list">
    <el-button
      v-if="!loading"
      color="#c2306a"
      round
      plain
      size="large"
      @click="send"
    >
      <el-icon><Promotion /></el-icon>
    </el-button>

    <el-button
      v-if="loading"
      color="#c2306a"
      round
      plain
      size="large"
      @click="abort"
    >
      <el-icon class="is-loading">
        <Refresh />
      </el-icon>
    </el-button>

    <div>{{ str }}</div>
  </div>
</template>

Configuration Parameters and Return Hooks

- useSend

• Parameters

Parameter Name	Description	Type
sendHandler	send method	() => void
abortHandler	abort method	() => void

• Return Value

Property Name	Description	Type
send	Start loading state, supports callback	() => void
abort	Abort loading state, supports callback	() => void
loading	Loading state	boolean
finish	End loading state	() => void

- XRequest

• Parameters

Config Parameter Name	Description	Type
baseURL	Base request URL	string
type	Request type, default SSE	BaseSSEProps<T = string>.type?: SSEType | undefined
transformer	transformer callback, where you can parse and process data	(e: string) => string | undefined
onMessage	Callback during request	(msg: string | undefined) => void
onError	Error callback	(es: EventSource, e: Event) => void
onOpen	SSE Open state	SSEWithSSEProps.onOpen?: (() => void) | undefined
onAbort	Callback when request is aborted	(messages: (string | undefined)[]) => void
onFinish	Callback when request ends	(data: (string | undefined)[]) => void

• Return Value

Property Name	Description	Type
send	Start request interface	XRequest<string | undefined>.send(url: string, options?: EventSourceInit | BaseFetchOptions): Promise<XRequest<string | undefined>>
abort	Abort request	XRequest<string | undefined>.abort(): void

Summary

useSend allows users to more conveniently display and control loading states on the frontend. It's a packaging solution for loading states. It accepts a send callback and an abort callback, provides send, abort loading state, end loading state, and returns loading state.

XRequest is a packaging of requests, providing a more convenient way to make requests. It accepts a request configuration and returns a request response object.