feat(useScreenOrientation): new function (#1526)

Co-authored-by: okxiaoliang4 <353742991@qq.com>

packages/core/index.ts

@@ -82,6 +82,7 @@ export * from './usePreferredLanguages'
 export * from './useRafFn'
 export * from './useRefHistory'
 export * from './useResizeObserver'
+export * from './useScreenOrientation'
 export * from './useScreenSafeArea'
 export * from './useScriptTag'
 export * from './useScroll'

packages/core/useScreenOrientation/demo.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+import { useScreenOrientation } from '.'
+
+const { isSupported, orientation, angle } = useScreenOrientation()
+</script>
+
+<template>
+  <note class="mb-2">
+    For best results, please use a mobile or tablet device (or use your browser's native inspector to simulate an
+    orienatation change)
+  </note>
+  <div>
+    isSupported: <boolean-display :value="isSupported">
+      {{ isSupported }}
+    </boolean-display>
+  </div>
+  <div>Orientation Type: <b>{{ orientation }}</b></div>
+  <div>Orientation Angle: <b>{{ angle }}</b></div>
+</template>

packages/core/useScreenOrientation/index.md

@@ -0,0 +1,47 @@
+---
+category: Browser
+---
+
+# useScreenOrientation
+
+Reactive [Screen Orientation API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Orientation_API). It provides web developers with information about the user's current screen orientation.
+
+## Usage
+
+```ts
+import { useScreenOrientation } from '.'
+
+const {
+  isSupported,
+  orientation,
+  angle,
+  lockOrientation,
+  unlockOrientation,
+} = useScreenOrientation()
+```
+
+To lock the orientation, you can pass an [OrientationLockType](https://developer.mozilla.org/en-US/docs/Web/API/ScreenOrientation/type) to the lockOrientation function:
+
+```ts
+import { useScreenOrientation } from '.'
+
+const {
+  isSupported,
+  orientation,
+  angle,
+  lockOrientation,
+  unlockOrientation,
+} = useScreenOrientation()
+
+lockOrientation('primary-portrait')
+```
+
+and then unlock again, with the following:
+
+```ts
+unlockOrientation()
+```
+
+Accepted orientation types are one of `"landscape-primary"`, `"landscape-secondary"`, `"portrait-primary"`, `"portrait-secondary"`, `"any"`, `"landscape"`, `"natural"` and `"portrait"`.
+
+[Screen Orientation API MDN](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Orientation_API)

packages/core/useScreenOrientation/index.test.ts

@@ -0,0 +1,7 @@
+import { useScreenOrientation } from '.'
+
+describe('useScreenOrientation', () => {
+  it('should be defined', () => {
+    expect(useScreenOrientation).toBeDefined()
+  })
+})

packages/core/useScreenOrientation/index.ts

@@ -0,0 +1,52 @@
+import { ref } from 'vue-demi'
+import { useEventListener } from '../useEventListener'
+import type { ConfigurableWindow } from '../_configurable'
+import { defaultWindow } from '../_configurable'
+
+/**
+ *
+ * Reactive screen orientation
+ *
+ * @see https://vueuse.org/useScreenOrientation
+ */
+export const useScreenOrientation = (options: ConfigurableWindow = {}) => {
+  const {
+    window = defaultWindow,
+  } = options
+
+  const isSupported = !!(window && 'screen' in window && 'orientation' in window.screen)
+
+  const screenOrientation = isSupported ? window.screen.orientation : {} as ScreenOrientation
+
+  const orientation = ref<OrientationType | undefined>(screenOrientation.type)
+  const angle = ref(screenOrientation.angle || 0)
+
+  if (isSupported) {
+    useEventListener(window, 'orientationchange', () => {
+      orientation.value = screenOrientation.type
+      angle.value = screenOrientation.angle
+    })
+  }
+
+  const lockOrientation = (type: OrientationLockType) => {
+    if (!isSupported)
+      return Promise.reject(new Error('Not supported'))
+
+    return screenOrientation.lock(type)
+  }
+
+  const unlockOrientation = () => {
+    if (isSupported)
+      screenOrientation.unlock()
+  }
+
+  return {
+    isSupported,
+    orientation,
+    angle,
+    lockOrientation,
+    unlockOrientation,
+  }
+}
+
+export type UseScreenOrientationReturn = ReturnType<typeof useScreenOrientation>