Skip to content

Commit eeac8c0

Browse files
yinxulaiyinxulai
committed
WIP
1 parent 491d60f commit eeac8c0

File tree

6 files changed

+150
-4
lines changed

6 files changed

+150
-4
lines changed

‎js-sdk.code-workspace

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
"exif",
2121
"iife",
2222
"Mogr",
23+
"navs",
2324
"umijs",
2425
"Uphost"
2526
],

‎packages/doc-site/.umirc.ts

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,17 @@
1-
import { defineConfig } from 'dumi';
1+
import { defineConfig } from 'dumi'
22

3+
// more config: https://d.umijs.org/config
34
export default defineConfig({
4-
title: 'Qiniu JS SDK',
5+
title: 'qiniu JS SDK',
56
favicon: '/favicon.ico',
67
logo: '/logo.png',
78
outputPath: 'dist',
89
mode: 'site',
9-
// more config: https://d.umijs.org/config
10-
});
10+
navs: [
11+
null, // A null value means to retain the conventionally generated navigation and only do incremental configuration
12+
{
13+
title: 'GitHub',
14+
path: 'https://github.com/qiniu/js-sdk',
15+
}
16+
]
17+
})

‎packages/doc-site/docs/guide/basic-usage.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: 基础使用
3+
order: 3
4+
toc: menu
5+
---
6+
7+
# 基础使用
8+
9+
通过这章节，你可以了解 SDK 基本的使用方式，在阅读当前章节之前推荐先阅读 [介绍](/guide/introduction)。
10+
11+
## 基本的上传
12+
13+
```jsx | preview
14+
import React from 'react';
15+
16+
export default ()=> {
17+
const [token,setToken] = React.useState('')
18+
return (
19+
<>
20+
<input pla value={token} onChange={(e)=>setToken(e.target.value)} />
21+
<input type="file" />
22+
</>
23+
)
24+
}
25+
```

‎packages/doc-site/docs/guide/install.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: 安装
3+
order: 2
4+
toc: menu
5+
---
6+
7+
# 安装
8+
9+
qiniu-js 设计的初衷就是可以通过简单的代码在您的项目中快速使用七牛的对象存储相关的能力。
10+
11+
将 qiniu-js 添加到项目中主要有四种方式：
12+
13+
1. 在页面上以 [CDN 包](#cdn)的形式导入。
14+
2. 下载 JavaScript 文件并[自行托管](#下载并自托管)。
15+
3. 使用 [npm](#npm) 安装它。(推荐)
16+
17+
## 发布版本说明
18+
19+
最新版本：![npm](https://img.shields.io/npm/v/qiniu-js)
20+
21+
每个版本的详细发布说明都可以在 [GitHub](https://github.com/qiniu/js-sdk/releases) 上找到。
22+
23+
## CDN
24+
25+
直接通过 `script` 标签引入，通过这种方式将会在全局生成名为 `qiniu` 的对象，下面是常见的 CDN 分发地址，你可以根据实际情况选择其中的某一个，不要忘记替换其中的 `<version>` 为你想要的版本号，大多数时候我们推荐你填入最新版本 ![npm](https://img.shields.io/npm/v/qiniu-js)
26+
27+
```html
28+
<script src="https://cdnjs.cloudflare.com/ajax/libs/qiniu-js/<version>/qiniu.min.js"></script>
29+
<script src="https://cdn.staticfile.org/qiniu-js/<version>/qiniu.min.js"></script>
30+
<script src="https://unpkg.com/browse/qiniu-js@<version>/dist/qiniu.min.js"></script>
31+
<script src="https://cdn.jsdelivr.net/npm/qiniu-js@<version>/dist/qiniu.min.js"></script>
32+
```
33+
34+
## 下载并自托管
35+
36+
如果你想避免使用构建工具，但又无法在生产环境使用 CDN，那么你可以下载相关 `.js` 文件并自行托管在你的服务器上。然后你可以通过 `<script>` 标签引入，与使用 CDN 的方法类似。
37+
38+
这些文件可以在 [unpkg](https://unpkg.com/browse/qiniu-js@latest/dist/) 或者 [jsDelivr](https://cdn.jsdelivr.net/npm/qiniu-js@latest/dist/) 这些 CDN 上浏览和下载。各种不同文件将在[以后解释](#对不同构建版本的解释)，但你通常需要同时下载开发环境构建版本以及生产环境构建版本。
39+
40+
## npm
41+
42+
在用大型应用时推荐使用 npm 安装<sup>[[1]](#footnote-1)</sup> 。npm 能很好地和诸如 [webpack](https://webpack.js.org/) 或 [Rollup](https://rollupjs.org/) 模块打包器配合使用，同时，这种方式可以享受 ts 带来的类型提示，及时发现类型错误。
43+
44+
```bash
45+
# 最新稳定版
46+
$ npm install qiniu-js@latest
47+
```
48+
49+
## 对不同构建版本的解释
50+
51+
在 [npm 包的目录](https://cdn.jsdelivr.net/npm/qiniu-js@latest/)你将会找到很多不同的 qiniu-js 构建版本。下面是一个概述，根据不同的使用情况，应该使用哪个文件：
52+
53+
```bash
54+
.
55+
├── dist 使用的是 iife 的模块化封装方案
56+
├── esm 使用的是 esm 的模块化封装方案
57+
└── lib 使用的是 umd 的模块化封装方案
58+
59+
```
60+
61+
### 使用 CDN 或没有构建工具
62+
63+
#### `dist/qiniu.min.js`：
64+
65+
- 若通过浏览器中的 `<script src="...">` 直接使用，则会暴露 qiniu 为全局变量。
66+
- 内联所有 qiniu-js 的全部代码：它是一个单独的文件，不依赖于其他文件。
67+
- 该文件是预先压缩过的，可以有效的减少网络请求压力。
68+
69+
#### `esm/index.js`：
70+
71+
- 用于通过原生 ES 模块导入使用 (在浏览器中通过 `<script type="module">` 来使用)。
72+
- 内联所有 qiniu-js 的全部代码：它是一个单独的文件，不依赖于其他文件。
73+
74+
### 使用构建工具（如 webpack、rollup）
75+
76+
使用构建工具时，构建工具会跟你你的项目自动选择合适的文件作为你的实际使用的依赖，

‎packages/doc-site/docs/guide/introduction.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: 介绍
3+
order: 1
4+
toc: menu
5+
---
6+
7+
# 介绍
8+
9+
本章节会简单概述 SDK 的设计理念，理解这些会帮助你理解 SDK 接口为何如此设计的原因。
10+
11+
## 设计理念
12+
13+
上传文件是一个典型的异步操作，同时它在结束之前会有持续的输出（上传的进度），根据这些特征，我们参考了 RxJS，采用了 `Observable` 作为我们的设计基本接口形式，这包涵了以下几个基本的概念：
14+
15+
- `Observable` (可观察对象): 表示一个概念，这个概念是一个可调用的未来值或事件的集合。
16+
- `Observer` (观察者): 一个回调函数的集合，它知道如何去监听由 `Observable` 提供的值。
17+
- `Subscription` (订阅): 表示 `Observable` 的执行，主要用于取消 `Observable` 的执行。
18+
19+
对于上传任务，当你调用 `upload` 方法时，该方法就会返回一个 `Observable` 对象，但是此时任务并没有真正的开始，只有当你通过调用 `Observable.subscribe` 方法并传入 `Observer` 时，任务才会真正的开始，并通过 `Observer` 实时的告知当前上传的进度信息。如果你希望停止当前的上传任务，通过调用 `Observable.subscribe` 返回的 `Subscription` 对象的 `unsubscribe` 方法取消订阅即可，总结就是：
20+
21+
- `upload` 创建上传任务，并返回 `Observable` 对象
22+
- 通过 `Observable` 订阅上传进度信息时开始上传任务
23+
- 通过 `Subscription` 取消订阅来停止任务

‎packages/doc-site/docs/token.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: token
3+
order: 4
4+
sidemenu: false
5+
---
6+
7+
```jsx | preview
8+
/**
9+
* inline: true
10+
*/
11+
import React from 'react';
12+
import { Home } from "../src/index.ts";
13+
export default ()=> (<Home />)
14+
```

0 commit comments

Comments
 (0)