# 使用说明一套 `core`（路径数学、样式、`createOrbit` 动画驱动）+ React / Vue 两套薄封装。 **不是**三个独立产品，而是：**一个库、两种框架、安装或复制二选一**。 | | React | Vue | |--|--------|-----| | **npm** | [`@fxshelf/card-orbit`](https://www.npmjs.com/package/@fxshelf/card-orbit) | `@fxshelf/card-orbit/vue` | | **CDN ` ``` --- ## CDN / ` ``` 说明： - 全局 `CardOrbit` 上有 `CardOrbit`、`CardOrbitMobile` 及 core 工具（`createOrbit` / `samplePath` 等），与 npm 主入口一致；props 与下文完全相同。 - 样式引 `dist/index.css` 或 `dist/card-orbit.iife.css`（内容相同）。 - CDN 也可用 jsDelivr：`https://cdn.jsdelivr.net/npm/@fxshelf/card-orbit/dist/card-orbit.iife.js`，或短地址 `https://cdn.jsdelivr.net/npm/@fxshelf/card-orbit`（`package.json` 的 `jsdelivr` / `unpkg` 字段已指向该产物）。 - 可锁定版本：`@fxshelf/card-orbit@0.1.6/...`（推荐生产环境）。 - 顺序要求：React 必须在 card-orbit 之前加载；顺序不对时产物会抛出明确报错。 - **不要**用 jsDelivr 的 `gh/.../dist` 直链：`dist/` 不进 Git，会 404。 - 完整可打开示例：[CDN示例.html](./CDN示例.html)（默认走 unpkg；本地已 build 时可改成相对路径 `../dist/...`）。 **Vue 暂无 script 直引产物**：Vue 入口以 `.vue` SFC 源码发布，需要使用方环境能编译 SFC。Vue 场景请用 [npm 安装](#npm-安装) 或 [复制源码](#复制进项目不经过-npm)。 > 旧无 scope 包名 `card-orbit` 已迁移至 `@fxshelf/card-orbit`，请改用新包名。 --- ## 复制进项目（不经过 npm）从本仓库拷贝： ``` src/core/ # 必拷 src/react/ # 仅 React 项目 src/vue/ # 仅 Vue 项目 ``` 建议放到例如 `components/card-orbit/`： ``` components/card-orbit/ core/ react/ 或 vue/ ``` 1. 组件内相对路径已是 `../core/...`，保持 `core` 与 `react`/`vue` 同级即可。 2. 引入一次样式：`import './core/styles.css'`。 3. 当本地组件使用。 ### React ```tsx import { CardOrbit, CardOrbitMobile } from './components/card-orbit/react' import './components/card-orbit/core/styles.css' ``` ### Vue ```ts import { CardOrbit, CardOrbitMobile } from './components/card-orbit/vue' import './components/card-orbit/core/styles.css' ``` --- ## 组件与 props | 组件 | 作用 | |------|------| | `CardOrbit` | 桌面 3D 轨迹（默认仅 `lg+` / 1024px 显示） | | `CardOrbitMobile` | 窄屏横向跑马灯（默认 `lg+` 隐藏） | React / Vue **props 名称一致**。图片 URL 由调用方提供，包内不捆绑资源。 ### `CardOrbit` | Prop | 默认 | 说明 | |------|------|------| | `images` | — | 图片 URL 数组（必填） | | `alts` | — | 与图片一一对应的 alt | | `className` / `style` | — | 根节点；Vue 也可用同名 props | | `stageClassName` / `cardClassName` / `imageClassName` | — | 子节点 class | | `autoSpeed` | `45e-6` | 未拖动时自动推进 | | `dragSensitivity` | `8e-4` | 指针拖动灵敏度 | | `activeWindow` | `0.72` | 可见相位窗口 `(0, 1)` | | `perspective` | `3400` | CSS perspective（px） | | `ariaLabel` | `'Card orbit carousel'` | 无障碍标签 | | `desktopOnly` | `true` | 是否仅大屏显示 | ### `CardOrbitMobile` | Prop | 默认 | 说明 | |------|------|------| | `images` / `alts` | — | 同桌面 | | `className` / `style` | — | 根节点 | | `trackClassName` / `cardClassName` / `imageClassName` | — | 子节点 class | | `hideOnDesktop` | `true` | `lg+` 是否隐藏 | | `durationSec` | `28` | 跑马灯一周时长（秒） | 典型搭配：窄屏用 `CardOrbitMobile`，宽屏用 `CardOrbit`，二者同时挂载、靠内置 CSS 互斥显示。 --- ## 目录与构建说明 ``` src/core/ # 无框架：path.ts、styles.css、createOrbit.ts src/react/ # React 适配 → npm 主入口打包进 dist/ src/vue/ # Vue 适配 → 以源码形式随包发布（@fxshelf/card-orbit/vue） src/browser/ # 浏览器直引构建的全局 shim（react / jsx-runtime，不随包发布） dist/ # 产物：index.js/.cjs/.d.ts（React 入口）、card-orbit.iife.js（浏览器直引）、CSS ``` - 在 monorepo 根执行 `npm run build`，或在本包目录执行 `npm run build`，只打包 **React** 到 `dist/`；其中 `card-orbit.iife.js` 通过 `src/browser/` 的 shim 把 `react` / `react/jsx-runtime` 指到全局 `React`，因此产物自包含。 - Vue 走 `package.json` 的 `exports["./vue"]`，指向 `src/vue`。 - 复制使用时不必跑本仓库的 build。 - 文档站在仓库 `apps/site`（fxshelf 总览）。