Skip to content

Commit

Permalink
chore: udpate English Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@Zippowxk
Zippowxk committed Jul 27, 2022
1 parent dcce6a6 commit 60aec73
Show file tree
Hide file tree
Showing 2 changed files with 143 additions and 45 deletions.
82 changes: 37 additions & 45 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,66 +1,67 @@
# Stack-Keep-Alive
`Stack-Keep-Alive` 是`Vue.js`(Vue 3.x)项目中页面缓存自动管理工具。

[Vue2.x 版本](https://github.com/Zippowxk/vue-router-keep-alive-helper)
## Introdaction

[在线Demo](http://xinkai.wang/stack-keep-alive-sample/dist/), 打开Vue-devtools查看页面缓存
English | [中文](./README_CN.md)

`Stack-Keep-Alive` is an automatic management tool for page cache in `Vue.js` (Vue 3.x) project.

[Vue2.x Version](https://github.com/Zippowxk/vue-router-keep-alive-helper)

[Online Demo](http://xinkai.wang/stack-keep-alive-sample/dist/), Check the Vue-devtools Panel


![img](./assets/stack.gif)

### 为什么需要本插件：
在使用```Vue.js```搭配```vue-router```开发单页面应用时，经常使用[keep-alive](https://v3.cn.vuejs.org/api/built-in-components.html#keep-alive)组件缓存浏览过的页面来提升用户体验，目前提供了如下配置方式来动态管理缓存
```
include - 只有名称匹配的组件会被缓存。
exclude - 任何名称匹配的组件都不会被缓存。
max - 最多可以缓存多少组件实例。
```
但是这只能处理简单状况，无法应对复杂状况，比如：
### Why do you need this plugin

The built-in `keep-alive` component is very useful in development, but it is not intelligent enough, it is difficult to clean up the page cache later, you need to use `exclude` and `include` API to save memory, and it cannot be accurately destroyed for different pages created by the same component.

If you have experienced mobile native development, you will not be troubled by this problem, because the model similar to NavigationController to manage each page is a stack structure, and the top page of the stack is destroyed when returning back.(The API is `push` and `pop` )

1. 如何在返回上一页面时，销毁当前页面缓存
2. 如何缓存多个使用相同组件的页面，并且有针对性的销毁

### 功能

1. 自动侦测前进或后退
2. 后退时自动销毁当前页面缓存
3. 前进时自动创建新的缓存实例，不管该组件是否被缓存过
4. 刷新页面后，仍能够准确识别前进或后退
5. `replaceStay`白名单帮助在tab切换时缓存页面
### Features

### 使用方式
1. Automatically detect forward or backward
2. Automatically destroy the current page cache when routing back
3. Automatically create a new cache instance when routing forward, regardless of whether the component is cached or not
4. After refreshing the page, it is still able to accurately identify forward or backward
5. `replaceStay` whitelist helps cache pages when tab switching
6. `singleton` allows you to set a globally unique page instance
7. `sk-transition` allows you to use two animations to simulate [the native stacking effect](http://xinkai.wang/stack-keep-alive-sample/dist/)

1. ```npm i -s stack-keep-alive```
2. 使用``stack-keep-alive``替换``keep-alive``组件 (无需引入，已注册全局组件)
### Usage

1. ```npm i -s stack-keep-alive``` | ```yarn add stack-keep-alive```
2. Replace the ``keep-alive`` component with ``stack-keep-alive`` (no need to import, registered global component)
```vue
<!-- 注意绑定key -->
<router-view v-slot="{ Component }">
<stack-keep-alive v-slot='{ key }'>
<component :is="Component" :key='key'/>
</stack-keep-alive>
</router-view>
```
3. 在app初始化时，使用StackKeepAlive插件
3. When the app is initialized, use the StackKeepAlive plugin
```javascript
import StackKeepAlive from 'stack-keep-alive'
const app = Vue.createApp({})
app.use(StackKeepAlive)
...
```

### 配置
### Configuration

1. replace白名单
#### 1. replace whitelist

在tab栏切换时，需要留存某些tab页面，可以在replaceStay中配置这些路径
When the tab bar is switched, some tab pages need to be retained, and these paths can be configured in replaceStay
```vue
<stack-keep-alive v-slot='{ key }' :replaceStay='["/foo"]'>
<component :is="Component" :key='key'/>
</stack-keep-alive>
```
2. 配合transition使用，需要使用内置sk-transition组件替换transition组件.
使用`name`和 `back_name` 实现两种不同动画效果

#### 2. transition
For use with transition, you need to replace the transition component with the built-in sk-transition component.Use `name` and `back_name` to achieve two different animation effects. [Sameple Code here](https://github.com/Zippowxk/stack-keep-alive-sample/blob/main/src/App4.vue)
```vue
<router-view v-slot="{ Component }">
<sk-transition name='slide-left' back_name='slide-right'>
Expand All @@ -70,32 +71,23 @@ app.use(StackKeepAlive)
</sk-transition>
</router-view>
```
3. 单例组件
有时期望一个组件在整个应用生命周期只创建一次，比如常见的购物车页面，此时使用 `singleton`配置单例组件
#### 3. singleton route
Sometimes it is expected that a component is only created once in the entire application life cycle, such as the common shopping cart page, in this case, use `singleton` to configure singleton route

```vue
<stack-keep-alive v-slot='{ key }' :singleton='["/foo"]'>
<component :is="Component" :key='key'/>
</stack-keep-alive>
```


### 更新日志

#### v1.0.0
1. 修复配合transition组件无效的问题

#### v1.0.0-beta.0
1. 支持Vue3
2. 单元测试
### Sample code

1. [静态文件引入](./examples/)
2. [工程化+完整动画](https://github.com/Zippowxk/stack-keep-alive-sample)
[Sample code](https://github.com/Zippowxk/stack-keep-alive-sample)

[Online demo](http://xinkai.wang/stack-keep-alive-sample/dist/)

![动画](https://github.com/Zippowxk/stack-keep-alive-sample/blob/main/imgs/sample.gif)
![Animation](https://github.com/Zippowxk/stack-keep-alive-sample/blob/main/imgs/sample.gif)

欢迎添加微信 **OmniBug **探讨交流，Email: [email protected]

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
Expand Down
106 changes: 106 additions & 0 deletions README_CN.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# Stack-Keep-Alive
`Stack-Keep-Alive` 是`Vue.js`(Vue 3.x)项目中页面缓存自动管理工具。

[Vue2.x 版本](https://github.com/Zippowxk/vue-router-keep-alive-helper)

[在线Demo](http://xinkai.wang/stack-keep-alive-sample/dist/), 打开Vue-devtools查看页面缓存


![img](./assets/stack.gif)

### 为什么需要本插件：
在使用```Vue.js```搭配```vue-router```开发单页面应用时，经常使用[keep-alive](https://v3.cn.vuejs.org/api/built-in-components.html#keep-alive)组件缓存浏览过的页面来提升用户体验，目前提供了如下配置方式来动态管理缓存
```
include - 只有名称匹配的组件会被缓存。
exclude - 任何名称匹配的组件都不会被缓存。
max - 最多可以缓存多少组件实例。
```
但是这只能处理简单状况，无法应对复杂状况，比如：

1. 如何在返回上一页面时，销毁当前页面缓存
2. 如何缓存多个使用相同组件的页面，并且有针对性的销毁

### 功能

1. 自动侦测前进或后退
2. 后退时自动销毁当前页面缓存
3. 前进时自动创建新的缓存实例，不管该组件是否被缓存过
4. 刷新页面后，仍能够准确识别前进或后退
5. `replaceStay`白名单帮助在tab切换时缓存页面

### 使用方式

1. ```npm i -s stack-keep-alive```
2. 使用``stack-keep-alive``替换``keep-alive``组件 (无需引入，已注册全局组件)
```vue
<!-- 注意绑定key -->
<router-view v-slot="{ Component }">
<stack-keep-alive v-slot='{ key }'>
<component :is="Component" :key='key'/>
</stack-keep-alive>
</router-view>
```
3. 在app初始化时，使用StackKeepAlive插件
```javascript
import StackKeepAlive from 'stack-keep-alive'
const app = Vue.createApp({})
app.use(StackKeepAlive)
...
```

### 配置

1. replace白名单

在tab栏切换时，需要留存某些tab页面，可以在replaceStay中配置这些路径
```vue
<stack-keep-alive v-slot='{ key }' :replaceStay='["/foo"]'>
<component :is="Component" :key='key'/>
</stack-keep-alive>
```
2. 配合transition使用，需要使用内置sk-transition组件替换transition组件.
使用`name`和 `back_name` 实现两种不同动画效果

```vue
<router-view v-slot="{ Component }">
<sk-transition name='slide-left' back_name='slide-right'>
<stack-keep-alive v-slot="{ key }">
<component :is="Component" :key='key'/>
</stack-keep-alive>
</sk-transition>
</router-view>
```
3. 单例组件
有时期望一个组件在整个应用生命周期只创建一次，比如常见的购物车页面，此时使用 `singleton`配置单例组件

```vue
<stack-keep-alive v-slot='{ key }' :singleton='["/foo"]'>
<component :is="Component" :key='key'/>
</stack-keep-alive>
```


### 更新日志

#### v1.0.0
1. 修复配合transition组件无效的问题

#### v1.0.0-beta.0
1. 支持Vue3
2. 单元测试
### Sample code

1. [静态文件引入](./examples/)
2. [工程化+完整动画](https://github.com/Zippowxk/stack-keep-alive-sample)

![动画](https://github.com/Zippowxk/stack-keep-alive-sample/blob/main/imgs/sample.gif)

欢迎添加微信 **OmniBug **探讨交流，Email: [email protected]

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

0 comments on commit 60aec73

Please sign in to comment.