Skip to content

设备机制层(宿主参考示例) ​

设备机制(判定 / 容器布线 / 模块装配)是宿主的子系统——skinsuite 不提供它,也不规定实现。其它章节示例里的 @/device 导入(createDeviceModule / pageContainers / HostDeviceInput)指的就是这一层。本页给一份最小参考实现:可以照抄,也可以只借鉴形状。生产实现的完整版见 oauth21 的 src/device/(多了分发器装配与判定接线)。

它住在哪、管什么 ​

src/device/          ← 纯机制层:类型 + 纯工具 + 装配工厂
├── types.ts         契约(HostDeviceInput / DeviceModule)
├── tools.ts         pageContainers(glob → 页面名 → 加载器)
└── runtime.ts       createDeviceModule(清单 → 可消费实例)

src/view/devices.ts  ← 宿主事实:只有设备清单与实例(零主题库 import,见[设备与容器](/guide/devices))
src/utils/           ← 判定纯函数 + 薄 composable(视口 / UA / ?device= 语义)

三层纪律:机制层零宿主事实(不认识 mobile / standard)、清单零机制逻辑(只有事实)、两侧零主题库依赖(主题侧只拿词汇投影)。

参考实现 ​

types.ts —— 契约 ​

ts
import type { Component } from 'vue';

/** 容器加载器:懒加载某页面在某设备上的容器组件 */
export type DeviceContainerLoader = () => Promise<{ default: Component }>;

/** 一台设备的声明(宿主事实的形状) */
export interface HostDeviceInput {
  /** 设备 id = 主题包内目录名([a-z0-9-]) */
  id: string;
  /** 显示名(调试面板 / 日志用) */
  label: string;
  /** URL 参数后缀(?th_<urlKey> / ?th_color_<urlKey>);缺省回落 id;🔴 不能是 color / color_ 开头(配色键固定形态) */
  urlKey?: string;
  /** 页面 → 容器加载器。函数形态 = 惰性构建,模块求值期不扫 glob */
  containers: () => ReadonlyMap<string, DeviceContainerLoader>;
}

/** 装配后的设备模块实例(页面分发器消费的公开面) */
export interface DeviceModule {
  readonly devices: readonly HostDeviceInput[];
  /** 兜底设备 id = 清单末条(数组序 = 优先级) */
  readonly fallbackId: string;
  /** 全部设备 id(按优先级序) */
  ids(): string[];
  /** 某设备某页的容器加载器;未知设备落兜底,兜底也没有则 null */
  resolveContainer(id: string, page: string): DeviceContainerLoader | null;
}

tools.ts —— 容器布线纯工具 ​

ts
import type { DeviceContainerLoader } from './types';

/**
 * glob 结果 → 「页面名 → 容器加载器」表。
 * 页面名 = 路径倒数第二段(view/app/login/index.vue → login);
 * fileRe 按文件名前缀区分共用目录的设备家族(view/web 下 Mini* / Standard*)。
 */
export function pageContainers(
  glob: Record<string, DeviceContainerLoader>,
  fileRe?: RegExp
): ReadonlyMap<string, DeviceContainerLoader> {
  const map = new Map<string, DeviceContainerLoader>();
  for (const [path, loader] of Object.entries(glob)) {
    const parts = path.split('/');
    if (fileRe && !fileRe.test(parts.at(-1) ?? '')) continue;
    const page = parts.at(-2);
    if (page) map.set(page, loader);
  }
  return map;
}

容器摊平会静默丢页面

view/web/StandardLogin.vue(不进 <页面>/ 子目录)的页面名会被算成 web——该设备在这一页等于「没写容器」。import.meta.glob 的 * 不跨 /,一层目录 + 一个文件正好。

runtime.ts —— 装配工厂 ​

ts
import type { DeviceContainerLoader, DeviceModule, HostDeviceInput } from './types';

/**
 * 清单(宿主事实)→ 可消费实例。判定不在这——判定纯函数 + useRenderDevice
 * 是宿主的另一个模块;分发器拿判定结果到本实例查容器。
 */
export function createDeviceModule(options: {
  devices: readonly HostDeviceInput[];
}): DeviceModule {
  const devices = options.devices;
  const fallbackId = devices.at(-1)?.id ?? '';   // 末条 = 兜底,不写死设备名
  const byId = new Map(devices.map(d => [d.id, d]));

  return {
    devices,
    fallbackId,
    ids: () => devices.map(d => d.id),
    resolveContainer(id: string, page: string): DeviceContainerLoader | null {
      const d = byId.get(id) ?? byId.get(fallbackId);
      return d?.containers().get(page) ?? null;
    }
  };
}

与主题侧的边界 ​

关注点设备侧(本层 + 清单 + 判定)主题侧(skinsuite)
设备词汇定义(清单)经词汇投影消费(createThemeState({ devices }))
判定判定纯函数 + useRenderDevice不判定,经 <ThemeView device> 接收结果
容器布线 + 装配 + 分发器选容器不管容器,按收到的 device 渲染版式
URL 参数?device= 语义与锁定?th / ?th_color 族(库内机制)

两侧唯一耦合点 = 主题侧的词汇投影:DEVICES.map(({ id, label, urlKey }) => ({ id, label, urlKey }))。

判定接线(本层的另一半) ​

判定是纯函数 + 薄 composable,与装配解耦:

ts
// src/utils/device-resolve.ts —— 纯函数:事实入参,零 import(口径随产品)
export function resolveRenderDevice(
  query: Record<string, unknown>,
  path: string,
  mobile: boolean
): string | null {
  if (query.device) return query.device as string;  // ?device= 一次性锁定
  if (query.isMobile === 'true') return 'mobile';
  if (mobile) return 'mobile';
  return null;                                      // null = 落兜底设备
}
ts
// src/composables/useRenderDevice.ts —— 薄封装:route + 视口信号喂给纯函数
import { computed } from 'vue';
import { useRoute } from 'vue-router';
import { resolveRenderDevice } from '@/utils/device-resolve';

export function useRenderDevice() {
  const route = useRoute();
  return computed(() => resolveRenderDevice(route.query, route.path, mobileViewport().value));
}

分发器把判定结果与模块实例接起来:

ts
// view/web/login/index.vue(页面分发器)
import { computed, defineAsyncComponent } from 'vue';
import { device } from '@/view/devices';
import { useRenderDevice } from '@/composables/useRenderDevice';

const renderDevice = useRenderDevice();
const deviceComponents = new Map(
  device.ids().map(id => {
    const loader = device.resolveContainer(id, 'login');
    return [id, loader ? defineAsyncComponent(loader) : null];
  })
);
const activeComponent = computed(
  () => deviceComponents.get(renderDevice.value)
    ?? deviceComponents.get(device.fallbackId)!
);

视口是宿主的响应式信号

库不订阅 matchMedia——「什么算变了」也是宿主口径。把视口做成 mobileViewport() 之类的响应式信号,判定纯函数的入参就是它,依赖由 computed 自动收集。

基于 MIT 许可发布