cineview 0.0.1-beta → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +74 -56
- package/README.zh-CN.md +74 -56
- package/dist/cineview-drag.umd.js +1 -1
- package/dist/cineview-scroll.umd.js +1 -1
- package/dist/cineview.es.mjs +1 -1
- package/dist/cineview.umd.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,45 +1,64 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://cineview.pages.dev">
|
|
3
|
+
<img src="./site/public/favicon.svg" width="64" height="64" alt="Cineview" />
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h1 align="center">Cineview</h1>
|
|
8
|
+
|
|
9
|
+
<p align="center">A React animation framework built around timelines, with drag and scroll modes.</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="https://www.npmjs.com/package/cineview"><img src="https://img.shields.io/npm/v/cineview?style=flat-square&color=8A5B43&logo=npm" alt="npm version" /></a>
|
|
17
|
+
<a href="https://www.npmjs.com/package/cineview"><img src="https://img.shields.io/npm/dm/cineview?style=flat-square&color=8A5B43" alt="npm monthly downloads" /></a>
|
|
18
|
+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-555?style=flat-square" alt="MIT license" /></a>
|
|
19
|
+
<br />
|
|
20
|
+
<a href="https://react.dev/"><img src="https://img.shields.io/badge/React-19-287EA3?style=flat-square&logo=react&logoColor=white" alt="React 19" /></a>
|
|
21
|
+
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
|
|
22
|
+
<a href="https://cineview.pages.dev/coverage.json"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fcineview.pages.dev%2Fcoverage.json&style=flat-square" alt="Framework line coverage" /></a>
|
|
23
|
+
</p>
|
|
24
|
+
|
|
25
|
+
<p align="center">
|
|
26
|
+
<a href="https://cineview.pages.dev">Try scrolling</a> ·
|
|
27
|
+
<a href="https://cineview.pages.dev/drag">Try dragging</a> ·
|
|
28
|
+
<a href="https://cineview.pages.dev/docs">Documentation</a> ·
|
|
29
|
+
<a href="#ai-read-this">AI, read this</a>
|
|
30
|
+
</p>
|
|
31
|
+
|
|
32
|
+
I want landing pages to be easier to maintain and AI assistants to spend less effort repeating the same work. Scene transitions, animation sequencing, and responsive layout can be reused across projects. Cineview organizes these features around scenes and timelines, so common page sections can become React components used on more than one page.
|
|
33
|
+
|
|
34
|
+
For a new page, combine existing scenes, assets, and animations. For an update, find the relevant component and adjust its content or timeline. The AI guides follow the same approach: read the index, then load the guides and code needed for the change. Reusing components and reading by task can reduce the tokens spent regenerating code and reconstructing how an entire page works, leaving more context for the actual request.
|
|
35
|
+
|
|
36
|
+
## Features
|
|
37
|
+
|
|
38
|
+
| Capability | How to use it |
|
|
39
|
+
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
40
|
+
| Reusable scenes and components | Divide content into Scenes and package common sections as React components for product pages, campaigns, or interactive presentations. |
|
|
41
|
+
| Timeline sequencing | Declare durations, delays, and dependencies. Dependent animations adjust when a predecessor's entrance duration changes. |
|
|
42
|
+
| Drag and scroll modes | Drag between full-screen scenes or scroll through a page. Connect animations to scroll progress where content needs to unfold gradually. |
|
|
43
|
+
| [Animation presets](https://cineview.pages.dev/docs/08-presets) | Start with fades, slides, zooms, rotations, flips, bounces, blurs, and other built-in effects. |
|
|
44
|
+
| [Composition and custom animations](https://cineview.pages.dev/docs/05-custom-animation) | Combine presets and custom properties on one element, define finer changes with keyframes, and use timelines to sequence separate elements. |
|
|
45
|
+
| Entrances, loops, and stagger | Configure entrance, loop, and exit effects where needed. Reveal children at intervals to sequence headings, cards, or lists. |
|
|
46
|
+
| [Video control](https://cineview.pages.dev/docs/11-video-timeline) | Use AnimateVideo to advance video frames through dragging or scrolling, select a video interval, and coordinate it with text animations. |
|
|
47
|
+
| [Custom drawing and extensions](https://cineview.pages.dev/docs/09-use-animate-timeline) | Read animation progress with useAnimateTimeline and connect Canvas, SVG, WebGL, or your own components to the existing progress controls. |
|
|
48
|
+
| [Responsive layout](https://cineview.pages.dev/docs/05-responsive) | Scale dimensions from a design width, position and size content with Position and Container, and adapt layouts with CSS. |
|
|
49
|
+
| [Resource preloading](https://cineview.pages.dev/docs/02-preload) | Prepare scene images in advance and handle initial loading, progress, and failures to reduce waiting for assets during scene changes. |
|
|
50
|
+
|
|
51
|
+
## Try it
|
|
52
|
+
|
|
53
|
+
In a React 19 project, install Cineview and its peer dependencies:
|
|
20
54
|
|
|
21
55
|
```bash
|
|
22
|
-
npm install cineview@
|
|
56
|
+
npm install cineview@1.0.1 react@19 react-dom@19 framer-motion@13
|
|
23
57
|
```
|
|
24
58
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
## Run the local example
|
|
28
|
-
|
|
29
|
-
To change the source and try it in the included example:
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
pnpm install --frozen-lockfile
|
|
33
|
-
pnpm --dir examples/minimal install --frozen-lockfile
|
|
34
|
-
pnpm build
|
|
35
|
-
pnpm --dir examples/minimal dev
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
The current package requires React `^19.0.0`, React DOM `^19.0.0`, and Framer Motion `^13.0.0`. See the [Changelog](./CHANGELOG.md) for migration notes.
|
|
39
|
-
|
|
40
|
-
## Build a drag page
|
|
59
|
+
This example uses the `Cineview` API in 1.0.1. Version 1.0.0 uses the earlier `CineView` API; update imports and configuration when upgrading.
|
|
41
60
|
|
|
42
|
-
|
|
61
|
+
Replace `App.tsx` with the component below and set `body { margin: 0; }` in your global stylesheet. No media files are needed.
|
|
43
62
|
|
|
44
63
|
```tsx
|
|
45
64
|
import { Animate, Cineview, Scene } from 'cineview';
|
|
@@ -67,35 +86,34 @@ export default function App() {
|
|
|
67
86
|
}
|
|
68
87
|
```
|
|
69
88
|
|
|
70
|
-
|
|
89
|
+
Drag upward to reveal the second scene: the title appears, then the description follows. Try changing the text and animation durations to make it your own. For scroll mode, start with the [interactive quick start](https://cineview.pages.dev/docs/03-quickstart).
|
|
71
90
|
|
|
72
|
-
|
|
91
|
+
## AI, read this
|
|
73
92
|
|
|
74
|
-
|
|
93
|
+
If you are an AI coding assistant working with Cineview, **read [llms.txt](./llms.txt) first**, then follow its links for the task at hand:
|
|
75
94
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
| Independent entrance | `timeline={{ driver: 'clock' }}` | Plays over time once its start conditions are met, even when scrolling stops |
|
|
95
|
+
- [Quick start](./docs/ai/quickstart.md): install the package and build a complete page.
|
|
96
|
+
- [Timelines](./docs/ai/timeline.md): arrange animation order, durations, and delays.
|
|
97
|
+
- [Modes](./docs/ai/modes.md): choose drag or scroll and check their constraints.
|
|
98
|
+
- [Recipes](./docs/ai/recipes.md): add a scroll narrative or video.
|
|
81
99
|
|
|
82
|
-
|
|
100
|
+
These guides target the Cineview 1.0.1 API. Check the version in the index before writing code, and use the linked types and detailed references when a property is unclear. Read only what the task needs: loading selected guides uses fewer input tokens than loading the entire documentation, leaving more context for the page being built.
|
|
83
101
|
|
|
84
|
-
##
|
|
102
|
+
## Docs and examples
|
|
85
103
|
|
|
86
|
-
|
|
87
|
-
- [Video control](https://cineview.pages.dev/docs/11-video-timeline): use drag and scroll progress to seek video frames.
|
|
88
|
-
- [Custom drawing](https://cineview.pages.dev/docs/09-use-animate-timeline): drive Canvas, SVG, or WebGL from MotionValues.
|
|
89
|
-
- [Responsive layout](https://cineview.pages.dev/docs/05-responsive): use `designWidth`, Position, and Container.
|
|
90
|
-
- [Preloading](https://cineview.pages.dev/docs/02-preload): prepare scene resources and handle first-screen waiting.
|
|
104
|
+
See the [documentation](https://cineview.pages.dev/docs) for component APIs and more examples:
|
|
91
105
|
|
|
92
|
-
|
|
106
|
+
- [Animation order](https://cineview.pages.dev/docs/04-orchestration)
|
|
107
|
+
- [Video control](https://cineview.pages.dev/docs/11-video-timeline)
|
|
108
|
+
- [Canvas, SVG, and WebGL](https://cineview.pages.dev/docs/09-use-animate-timeline)
|
|
109
|
+
- [Responsive layout](https://cineview.pages.dev/docs/05-responsive)
|
|
110
|
+
- [Resource preloading](https://cineview.pages.dev/docs/02-preload)
|
|
93
111
|
|
|
94
|
-
|
|
112
|
+
Prefer to run the source locally? The [minimal example](./examples/minimal/README.md) includes startup commands and both modes.
|
|
95
113
|
|
|
96
|
-
|
|
114
|
+
## Contributing
|
|
97
115
|
|
|
98
|
-
|
|
116
|
+
Bug reports, examples, and improvements are welcome. Start with [Contributing](./CONTRIBUTING.md) for local setup and checks. See the [Changelog](./CHANGELOG.md) for version changes and [Releases](./RELEASING.md) for publishing instructions.
|
|
99
117
|
|
|
100
118
|
## License
|
|
101
119
|
|
package/README.zh-CN.md
CHANGED
|
@@ -1,45 +1,64 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://cineview.pages.dev">
|
|
3
|
+
<img src="./site/public/favicon.svg" width="64" height="64" alt="Cineview" />
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h1 align="center">Cineview</h1>
|
|
8
|
+
|
|
9
|
+
<p align="center">以时间线为核心，支持拖拽与滚动双模式的 React 动画框架。</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="https://www.npmjs.com/package/cineview"><img src="https://img.shields.io/npm/v/cineview?style=flat-square&color=8A5B43&logo=npm" alt="npm version" /></a>
|
|
17
|
+
<a href="https://www.npmjs.com/package/cineview"><img src="https://img.shields.io/npm/dm/cineview?style=flat-square&color=8A5B43" alt="npm monthly downloads" /></a>
|
|
18
|
+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-555?style=flat-square" alt="MIT license" /></a>
|
|
19
|
+
<br />
|
|
20
|
+
<a href="https://react.dev/"><img src="https://img.shields.io/badge/React-19-287EA3?style=flat-square&logo=react&logoColor=white" alt="React 19" /></a>
|
|
21
|
+
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
|
|
22
|
+
<a href="https://cineview.pages.dev/coverage.json"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fcineview.pages.dev%2Fcoverage.json&style=flat-square" alt="Framework line coverage" /></a>
|
|
23
|
+
</p>
|
|
24
|
+
|
|
25
|
+
<p align="center">
|
|
26
|
+
<a href="https://cineview.pages.dev">试试滚动</a> ·
|
|
27
|
+
<a href="https://cineview.pages.dev/drag">试试拖拽</a> ·
|
|
28
|
+
<a href="https://cineview.pages.dev/docs">查看文档</a> ·
|
|
29
|
+
<a href="#ai-看这里">AI 看这里</a>
|
|
30
|
+
</p>
|
|
31
|
+
|
|
32
|
+
我想让落地页更容易维护，也让 AI 少做重复的工作。场景切换、动画编排和响应式布局，没必要每个项目都重新开发一遍。Cineview 把这些通用能力放进同一套场景和时间线结构，常用的展示片段可以封装成 React 组件，在不同页面中复用。
|
|
33
|
+
|
|
34
|
+
做新页面时，组合已有的场景、素材和动画；后续修改时，找到对应组件，调整内容和时间线配置。配合按任务拆分的 AI 文档，让 AI 先读索引，再读取本次改动涉及的指南和代码，减少重复生成代码和反复梳理整页实现所用的 token，把更多上下文留给具体需求。
|
|
35
|
+
|
|
36
|
+
## 可以做什么
|
|
37
|
+
|
|
38
|
+
| 能力 | 用法 |
|
|
39
|
+
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
40
|
+
| 场景与组件复用 | 用 Scene 拆分内容，把常用片段封装成 React 组件，复用到产品介绍、活动页或交互展示中。 |
|
|
41
|
+
| 时间线编排 | 声明动画时长、延迟和先后关系；前一个动画的入场时长变化后，依赖它的动画会随之调整。 |
|
|
42
|
+
| 拖拽与滚动双模式 | 拖拽切换整屏场景，或让页面连续滚动；需要逐步展开内容时，让动画跟随滚动进度。 |
|
|
43
|
+
| [动画预设](https://cineview.pages.dev/docs/08-presets) | 使用淡入淡出、位移、缩放、旋转、翻转、弹跳、模糊等预设，快速搭出基础效果。 |
|
|
44
|
+
| [组合与自定义动画](https://cineview.pages.dev/docs/05-custom-animation) | 在一个元素上组合预设和自定义属性，用关键帧定义更细的变化，再用时间线安排不同元素的出场顺序。 |
|
|
45
|
+
| 入场、循环与交错效果 | 按需配置入场、循环和退场；让一组子元素依次出现，处理标题、卡片和列表的展示节奏。 |
|
|
46
|
+
| [视频控制](https://cineview.pages.dev/docs/11-video-timeline) | 用 AnimateVideo 让视频画面跟随拖拽或滚动，选择需要控制的片段，并与文字动画配合。 |
|
|
47
|
+
| [扩展自定义绘制](https://cineview.pages.dev/docs/09-use-animate-timeline) | 通过 useAnimateTimeline 读取动画进度，连接 Canvas、SVG、WebGL 或自己的组件，无需另写一套进度控制。 |
|
|
48
|
+
| [响应式布局](https://cineview.pages.dev/docs/05-responsive) | 根据设计稿宽度换算尺寸，用 Position 和 Container 配置位置与大小，并结合 CSS 调整布局。 |
|
|
49
|
+
| [资源预加载](https://cineview.pages.dev/docs/02-preload) | 提前准备场景图片，处理首屏加载、加载进度和资源失败，减少切换场景时等待素材的情况。 |
|
|
50
|
+
|
|
51
|
+
## 试试看
|
|
52
|
+
|
|
53
|
+
在 React 19 项目中，安装 Cineview 及其依赖：
|
|
20
54
|
|
|
21
55
|
```bash
|
|
22
|
-
npm install cineview@
|
|
56
|
+
npm install cineview@1.0.1 react@19 react-dom@19 framer-motion@13
|
|
23
57
|
```
|
|
24
58
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
## 运行本地示例
|
|
28
|
-
|
|
29
|
-
修改源码并在附带的示例中验证：
|
|
30
|
-
|
|
31
|
-
```bash
|
|
32
|
-
pnpm install --frozen-lockfile
|
|
33
|
-
pnpm --dir examples/minimal install --frozen-lockfile
|
|
34
|
-
pnpm build
|
|
35
|
-
pnpm --dir examples/minimal dev
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
当前包需要 React `^19.0.0`、React DOM `^19.0.0` 和 Framer Motion `^13.0.0`。迁移说明见 [Changelog](./CHANGELOG.md)。
|
|
39
|
-
|
|
40
|
-
## 第一个拖拽页面
|
|
59
|
+
示例使用 1.0.1 的 `Cineview` API。1.0.0 使用早期的 `CineView` API，升级时需要更新导入名称和配置。
|
|
41
60
|
|
|
42
|
-
|
|
61
|
+
把以下内容放进 `App.tsx`，在全局样式中设置 `body { margin: 0; }`。无需准备媒体素材。
|
|
43
62
|
|
|
44
63
|
```tsx
|
|
45
64
|
import { Animate, Cineview, Scene } from 'cineview';
|
|
@@ -67,35 +86,34 @@ export default function App() {
|
|
|
67
86
|
}
|
|
68
87
|
```
|
|
69
88
|
|
|
70
|
-
|
|
89
|
+
向上拖动进入第二幕，标题先出现，说明随后跟上。试着改改文案和动画时长，做成自己的页面。想用滚动模式，可以接着试试[快速上手中的交互案例](https://cineview.pages.dev/docs/03-quickstart)。
|
|
71
90
|
|
|
72
|
-
|
|
91
|
+
## AI 看这里
|
|
73
92
|
|
|
74
|
-
|
|
93
|
+
如果你是正在使用 Cineview 的 AI 编程助手，**请先阅读 [llms.txt](./llms.txt)**，再按当前任务打开其中的指南：
|
|
75
94
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
| 独立入场 | `timeline={{ driver: 'clock' }}` | 满足启动条件后按时间播放，不因停止滚动而暂停 |
|
|
95
|
+
- [快速开始](./docs/ai/quickstart.md)：安装框架，完成第一个页面。
|
|
96
|
+
- [时间线](./docs/ai/timeline.md)：安排动画顺序、时长和延迟。
|
|
97
|
+
- [模式选择](./docs/ai/modes.md)：选择拖拽或滚动，确认各自的限制。
|
|
98
|
+
- [完整案例](./docs/ai/recipes.md)：实现滚动叙事或加入视频。
|
|
81
99
|
|
|
82
|
-
|
|
100
|
+
这套指南对应 Cineview 1.0.1 API。写代码前先确认索引中的版本，遇到不确定的参数，再沿链接查阅类型定义和详细文档。只读取当前任务需要的内容，比一次加载整套文档更省输入 token，也能为页面代码和需求留出更多上下文。
|
|
83
101
|
|
|
84
|
-
##
|
|
102
|
+
## 文档与案例
|
|
85
103
|
|
|
86
|
-
|
|
87
|
-
- [视频控制](https://cineview.pages.dev/docs/11-video-timeline)：将拖拽和滚动进度用于视频帧。
|
|
88
|
-
- [自定义绘制](https://cineview.pages.dev/docs/09-use-animate-timeline)：用 MotionValue 驱动 Canvas、SVG 或 WebGL。
|
|
89
|
-
- [布局换算](https://cineview.pages.dev/docs/05-responsive)：使用 `designWidth`、Position 和 Container。
|
|
90
|
-
- [资源预加载](https://cineview.pages.dev/docs/02-preload)：准备场景资源与处理首屏等待。
|
|
104
|
+
组件 API 和更多示例都在[文档](https://cineview.pages.dev/docs)中，可以按需要继续阅读：
|
|
91
105
|
|
|
92
|
-
|
|
106
|
+
- [动画顺序](https://cineview.pages.dev/docs/04-orchestration)
|
|
107
|
+
- [视频控制](https://cineview.pages.dev/docs/11-video-timeline)
|
|
108
|
+
- [Canvas、SVG 与 WebGL](https://cineview.pages.dev/docs/09-use-animate-timeline)
|
|
109
|
+
- [响应式布局](https://cineview.pages.dev/docs/05-responsive)
|
|
110
|
+
- [资源预加载](https://cineview.pages.dev/docs/02-preload)
|
|
93
111
|
|
|
94
|
-
|
|
112
|
+
想在本地运行源码，可以从[最小示例](./examples/minimal/README.md)开始，其中包含启动步骤和两种模式。
|
|
95
113
|
|
|
96
|
-
|
|
114
|
+
## 参与开发
|
|
97
115
|
|
|
98
|
-
|
|
116
|
+
欢迎反馈问题、分享案例或一起改进框架。本地环境和检查步骤见 [Contributing](./CONTRIBUTING.md)，版本变化见 [Changelog](./CHANGELOG.md)，发布流程见[发布说明](./RELEASING.md)。
|
|
99
117
|
|
|
100
118
|
## 许可证
|
|
101
119
|
|