vitepress-theme-element-plus 1.3.2 → 1.4.0

package/client/components/Doc.vue

@@ -4,11 +4,14 @@ import { computed } from 'vue'
 import { useSidebar } from '../hooks/useSidebar'
 import VPDocAside from './DocAside.vue'
 import VPDocFooter from './DocFooter.vue'
+import MobilePreviewFrame from './MobilePreviewFrame.vue'
 
-const { theme } = useData()
+const { theme, frontmatter } = useData()
 
 const route = useRoute()
 const { hasAside, leftAside, hasSidebar } = useSidebar()
+const hasMobilePreview = computed(() => typeof frontmatter.value.mobileDemo === 'string' && frontmatter.value.mobileDemo.trim().length > 0)
+const showAside = computed(() => hasAside.value)
 
 const pageName = computed(() =>
   route.path.replace(/[./]+/g, '_').replace(/_html$/, ''),
@@ -16,10 +19,16 @@ const pageName = computed(() =>
 </script>
 
 <template>
-  <div class="VPDoc" :class="{ 'has-sidebar': hasSidebar, 'has-aside': hasAside }">
+  <div class="VPDoc" :class="{ 'has-sidebar': hasSidebar, 'has-aside': showAside, 'has-mobile-preview': hasMobilePreview }">
     <slot name="doc-top" />
     <div class="container">
-      <div v-if="hasAside" class="aside" :class="{ 'left-aside': leftAside }">
+      <div v-if="hasMobilePreview" class="preview">
+        <div class="preview-container">
+          <MobilePreviewFrame />
+        </div>
+      </div>
+
+      <div v-if="showAside" class="aside" :class="{ 'left-aside': leftAside }">
         <div class="aside-container">
           <div class="aside-content">
             <VPDocAside>
@@ -112,9 +121,17 @@ const pageName = computed(() =>
     justify-content: center;
   }
 
+  .VPDoc.has-mobile-preview .container {
+    gap: 32px;
+  }
+
   .VPDoc .aside {
     display: block;
   }
+
+  .VPDoc.has-aside.has-mobile-preview .aside {
+    display: none;
+  }
 }
 
 @media (min-width: 1440px) {
@@ -132,6 +149,17 @@ const pageName = computed(() =>
   width: 100%;
 }
 
+.preview {
+  margin-bottom: 24px;
+  order: 2;
+}
+
+.preview-container {
+  width: 100%;
+  position: sticky;
+  top: calc(var(--vp-nav-height) + 32px);
+}
+
 .aside {
   position: relative;
   display: none;
@@ -179,6 +207,12 @@ const pageName = computed(() =>
   }
 }
 
+@media (min-width: 1680px) {
+  .VPDoc.has-aside.has-mobile-preview .aside {
+    display: block;
+  }
+}
+
 .content-container {
   margin: 0 auto;
 }

package/client/components/Layout.vue

@@ -8,10 +8,12 @@ import { computed, provide, useSlots, watch } from 'vue'
 import { useCloseSidebarOnEscape } from '../hooks/useSidebar'
 import Content from './Content.vue'
 import LocalNav from './LocalNav.vue'
+import MobilePreviewLayout from './MobilePreviewLayout.vue'
 import Nav from './Nav.vue'
 import Sidebar from './Sidebar.vue'
 
 const { frontmatter } = useData()
+const isStandaloneMobilePreview = computed(() => frontmatter.value.layout === 'mobile-preview')
 
 useCloseSidebarOnEscape()
 const {
@@ -32,7 +34,8 @@ provide(layoutInfoInjectionKey, heroImageSlotExists)
 </script>
 
 <template>
-  <div v-if="frontmatter.layout !== false" class="Layout VMLayout" :class="frontmatter.pageClass">
+  <MobilePreviewLayout v-if="isStandaloneMobilePreview" />
+  <div v-else-if="frontmatter.layout !== false" class="Layout VMLayout" :class="frontmatter.pageClass">
     <slot name="layout-top" />
     <VPSkipLink />
     <VPBackdrop class="backdrop" :show="isSidebarOpen" @click="closeSidebar()" />

package/client/components/MobilePreviewFrame.vue

@@ -0,0 +1,175 @@
+<script setup lang="ts">
+import { useData, useRoute } from 'vitepress'
+import { computed, ref, watch } from 'vue'
+import { resolveMobilePreviewId } from '../mobile-preview'
+
+const { frontmatter, isDark, theme } = useData()
+const route = useRoute()
+const frameRef = ref<HTMLIFrameElement>()
+const previewConfig = computed(() => theme.value.mobilePreview ?? {})
+
+const demoId = computed(() => {
+  const value = frontmatter.value.mobileDemo
+  return typeof value === 'string'
+    ? resolveMobilePreviewId(value, previewConfig.value.demoRoot)
+    : ''
+})
+
+const frameWidth = computed(() => `${previewConfig.value.deviceWidth ?? 390}px`)
+const viewportHeight = computed(() => `${previewConfig.value.deviceHeight ?? 760}px`)
+
+const previewHref = computed(() => {
+  const previewPath = normalizePreviewPath(previewConfig.value.previewPath)
+  const search = new URLSearchParams({
+    demo: demoId.value,
+    theme: isDark.value ? 'dark' : 'light',
+  })
+
+  return `${resolveLocalePreviewPath(route.path, previewPath)}?${search.toString()}`
+})
+
+const frameStyle = computed(() => ({
+  '--vp-mobile-preview-width': frameWidth.value,
+  '--vp-mobile-preview-height': viewportHeight.value,
+}))
+
+function normalizePreviewPath(value: unknown): string {
+  if (typeof value !== 'string' || !value.trim())
+    return 'preview/'
+
+  return value
+    .trim()
+    .replace(/^\/+/, '')
+    .replace(/\/?$/, '/')
+}
+
+function resolveLocalePreviewPath(path: string, previewPath: string): string {
+  const matchedLocale = path.match(/^\/([^/]+)\//)
+  const localePrefix = matchedLocale ? `/${matchedLocale[1]}/` : '/'
+
+  return `${localePrefix}${previewPath}`
+}
+
+function syncTheme(): void {
+  frameRef.value?.contentWindow?.postMessage({
+    type: 'vp-mobile-preview-theme',
+    value: isDark.value ? 'dark' : 'light',
+  }, '*')
+}
+
+watch(isDark, syncTheme)
+</script>
+
+<template>
+  <section v-if="demoId" class="VPMobilePreviewFrame" :style="frameStyle">
+    <div class="preview-actions">
+      <span class="preview-actions__label">Mobile Preview</span>
+      <a class="preview-actions__link" :href="previewHref" target="_blank" rel="noreferrer">
+        Open
+      </a>
+    </div>
+
+    <div class="preview-phone">
+      <div class="preview-phone__camera" />
+      <iframe
+        ref="frameRef"
+        class="preview-phone__viewport"
+        :src="previewHref"
+        title="Mobile demo preview"
+        loading="lazy"
+        @load="syncTheme"
+      />
+    </div>
+
+    <a class="preview-mobile-link" :href="previewHref" target="_blank" rel="noreferrer">
+      Open mobile preview
+    </a>
+  </section>
+</template>
+
+<style scoped lang="scss">
+.preview-actions {
+  display: none;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 12px;
+  padding: 0 4px;
+}
+
+.preview-actions__label {
+  color: var(--vp-c-text-2);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.preview-actions__link,
+.preview-mobile-link {
+  color: var(--vp-c-brand-1);
+  font-size: 13px;
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.preview-phone {
+  display: none;
+  position: relative;
+  width: var(--vp-mobile-preview-width);
+  padding: 14px 10px;
+  background: linear-gradient(180deg, rgba(255, 255, 255, 0.86), rgba(255, 255, 255, 0.64)), rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(15, 23, 42, 0.08);
+  border-radius: 32px;
+  box-shadow:
+    0 24px 80px rgba(15, 23, 42, 0.12),
+    inset 0 1px 0 rgba(255, 255, 255, 0.7);
+  backdrop-filter: blur(20px);
+}
+
+:global(.dark) .preview-phone {
+  background: linear-gradient(180deg, rgba(24, 24, 27, 0.92), rgba(24, 24, 27, 0.8)), rgba(24, 24, 27, 0.86);
+  border-color: rgba(255, 255, 255, 0.12);
+  box-shadow:
+    0 24px 80px rgba(0, 0, 0, 0.45),
+    inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+
+.preview-phone__camera {
+  position: absolute;
+  top: 8px;
+  left: 50%;
+  width: 104px;
+  height: 18px;
+  border-radius: 999px;
+  background: rgba(15, 23, 42, 0.92);
+  transform: translateX(-50%);
+}
+
+.preview-phone__viewport {
+  display: block;
+  width: 100%;
+  height: var(--vp-mobile-preview-height);
+  overflow: hidden;
+  background: var(--vp-c-bg);
+  border: 0;
+  border-radius: 24px;
+}
+
+.preview-mobile-link {
+  display: inline-flex;
+}
+
+@media (min-width: 1440px) {
+  .preview-actions {
+    display: flex;
+  }
+
+  .preview-phone {
+    display: block;
+  }
+
+  .preview-mobile-link {
+    display: none;
+  }
+}
+</style>

package/client/components/MobilePreviewLayout.vue

@@ -0,0 +1,140 @@
+<script setup lang="ts">
+import type { Component } from 'vue'
+import { useData } from 'vitepress'
+import { computed, inject, markRaw, onBeforeUnmount, onMounted, ref, shallowRef } from 'vue'
+import { mobilePreviewRegistryKey, resolveMobilePreviewId } from '../mobile-preview'
+
+const { frontmatter, theme } = useData()
+const registry = inject(mobilePreviewRegistryKey)
+const demoId = ref('')
+const errorMessage = ref('')
+const isLoading = ref(true)
+const demoComponent = shallowRef<Component>()
+const previewConfig = computed(() => theme.value.mobilePreview ?? {})
+
+const statusMessage = computed(() => {
+  if (errorMessage.value)
+    return errorMessage.value
+
+  return isLoading.value ? 'Loading mobile preview...' : 'No preview loaded.'
+})
+
+function applyTheme(theme: string | null): void {
+  if (typeof document === 'undefined')
+    return
+
+  document.documentElement.classList.toggle('dark', theme === 'dark')
+}
+
+async function loadDemo(value: string | null): Promise<void> {
+  demoId.value = resolveMobilePreviewId(value ?? '', previewConfig.value.demoRoot)
+  demoComponent.value = undefined
+  errorMessage.value = ''
+  isLoading.value = true
+
+  if (!demoId.value) {
+    errorMessage.value = 'Missing demo id.'
+    isLoading.value = false
+    return
+  }
+
+  if (!registry) {
+    errorMessage.value = 'No mobile preview registry was provided.'
+    isLoading.value = false
+    return
+  }
+
+  const loader = registry[demoId.value]
+  if (!loader) {
+    errorMessage.value = `Unknown demo: ${demoId.value}`
+    isLoading.value = false
+    return
+  }
+
+  try {
+    const module = await loader()
+    const resolvedComponent = (module as { default?: Component }).default ?? module
+    demoComponent.value = markRaw(resolvedComponent as Component)
+  }
+  catch (error) {
+    errorMessage.value = error instanceof Error
+      ? error.message
+      : 'Failed to load the requested demo.'
+  }
+  finally {
+    isLoading.value = false
+  }
+}
+
+function syncFromLocation(): void {
+  if (typeof window === 'undefined')
+    return
+
+  const search = new URLSearchParams(window.location.search)
+  const fallbackDemo = typeof frontmatter.value.mobileDemo === 'string'
+    ? frontmatter.value.mobileDemo
+    : null
+  applyTheme(search.get('theme'))
+  void loadDemo(search.get('demo') ?? fallbackDemo)
+}
+
+function handleMessage(event: MessageEvent): void {
+  if (event.data?.type !== 'vp-mobile-preview-theme')
+    return
+
+  applyTheme(event.data.value)
+}
+
+onMounted(() => {
+  syncFromLocation()
+  window.addEventListener('message', handleMessage)
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('message', handleMessage)
+})
+</script>
+
+<template>
+  <main class="VPMobilePreviewLayout">
+    <component :is="demoComponent" v-if="demoComponent" />
+    <div v-else class="preview-status">
+      <p class="preview-status__title">
+        Mobile Preview
+      </p>
+      <p class="preview-status__body">
+        {{ statusMessage }}
+      </p>
+    </div>
+  </main>
+</template>
+
+<style scoped lang="scss">
+.VPMobilePreviewLayout {
+  min-height: 100%;
+  height: 100vh;
+  overflow-x: hidden;
+  overflow-y: auto;
+}
+
+.preview-status {
+  display: grid;
+  place-items: center;
+  align-content: center;
+  min-height: 100vh;
+  padding: 24px;
+  color: var(--vp-c-text-2);
+  text-align: center;
+}
+
+.preview-status__title {
+  margin: 0 0 12px;
+  color: var(--vp-c-text-1);
+  font-weight: 600;
+}
+
+.preview-status__body {
+  margin: 0;
+  font-size: 14px;
+}
+</style>

package/client/mobile-preview.ts

@@ -0,0 +1,60 @@
+import type { InjectionKey } from 'vue'
+
+export type MobilePreviewModule = () => Promise<unknown>
+
+export type MobilePreviewRegistry = Record<string, MobilePreviewModule>
+
+export interface EPMobilePreviewConfig {
+  /**
+   * Locale-relative path of the standalone preview page.
+   *
+   * @default '/preview/'
+   */
+  previewPath?: string
+  /**
+   * Outer device frame width used in the doc layout.
+   *
+   * @default 390
+   */
+  deviceWidth?: number
+  /**
+   * Inner viewport height used in the doc layout.
+   *
+   * @default 760
+   */
+  deviceHeight?: number
+  /**
+   * Root directory used to resolve the `mobileDemo` frontmatter field.
+   *
+   * @default 'demo/'
+   */
+  demoRoot?: string
+}
+
+export const mobilePreviewRegistryKey: InjectionKey<MobilePreviewRegistry> = Symbol('vitepress-theme-element-plus.mobile-preview-registry')
+
+export function normalizeMobilePreviewId(value: string): string {
+  return value
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.?\//, '')
+}
+
+export function normalizeMobilePreviewRoot(value: string | undefined): string {
+  if (!value?.trim())
+    return 'demo/'
+
+  return normalizeMobilePreviewId(value)
+    .replace(/\/?$/, '/')
+}
+
+export function resolveMobilePreviewId(value: string | undefined, root: string | undefined): string {
+  const normalizedId = normalizeMobilePreviewId(value ?? '')
+  if (!normalizedId)
+    return ''
+
+  const normalizedRoot = normalizeMobilePreviewRoot(root)
+  return normalizedId.startsWith(normalizedRoot)
+    ? normalizedId
+    : `${normalizedRoot}${normalizedId}`
+}

package/index.ts

@@ -1,4 +1,5 @@
 import type { DefaultTheme, Theme } from 'vitepress'
+import type { EPMobilePreviewConfig, MobilePreviewModule, MobilePreviewRegistry } from './client/mobile-preview'
 import VPTheme from 'vitepress/theme'
 import Layout from './client/components/Layout.vue'
 import 'element-plus/theme-chalk/base.css'
@@ -37,9 +38,20 @@ export interface EPThemeConfig extends DefaultTheme.Config {
    * 文档版本号
    */
   version?: string
+  /**
+   * 移动端预览配置
+   */
+  mobilePreview?: EPMobilePreviewConfig
   footer?: EPThemeFooter
 }
 // #endregion snippet
 
 export { Layout }
+export {
+  mobilePreviewRegistryKey,
+  normalizeMobilePreviewId,
+  normalizeMobilePreviewRoot,
+  resolveMobilePreviewId,
+} from './client/mobile-preview'
+export type { EPMobilePreviewConfig, MobilePreviewModule, MobilePreviewRegistry }
 export default EPTheme

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vitepress-theme-element-plus",
   "type": "module",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "A VitePress theme for Element Plus",
   "author": "Hezhengxu",
   "license": "MIT",