From 49cdab66878e8f3e29af5d3acd5cfba282e5c257 Mon Sep 17 00:00:00 2001 From: Espoir-L <413308430@qq.com> Date: Thu, 17 May 2018 20:57:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=E5=B0=8F=E6=95=85=E4=BA=8B=E7=BB=84?= =?UTF-8?q?=E4=BB=B6=E4=BB=8B=E7=BB=8D=E7=9A=84=E5=88=86=E6=94=AF=E4=BF=AE?= =?UTF-8?q?=E6=94=B91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/mip-story/README.md | 462 ++++++++++++++++++++++++++++------------ 1 file changed, 320 insertions(+), 142 deletions(-) diff --git a/src/mip-story/README.md b/src/mip-story/README.md index f8f3b8b6b..17cf663dc 100644 --- a/src/mip-story/README.md +++ b/src/mip-story/README.md @@ -1,106 +1,325 @@ -# mip-story +## 小故事组件的介绍 -`` 的诞生，使得正在经历消费升级的移动互联网时代，可以引入更好质量和多元化的内容，不但可以提升用户体验，同时也帮助用户寻找到更丰富的资源和交互方式。 +## 组件介绍 -`` 具有三个基本概念：段落（view），层（layer）和元素（element）。 +### 1、小故事的介绍 -![](https://mip-extensions.bj.bcebos.com/mip-story/intro-view-layer-element.jpg) + 小故事是基于[mip](https://www.mipengine.org/)技术的一个产品，小故事的组件也是MIP组件，主要是三个组件一起使用，构成小故事的整体结构，其中故事组件为`mip-story`，段落为`mip-story-view`，层为`mip-story-layer`。 + +| **描述** | 丰富的视觉故事形式。 | +| -------------- | ------------------------------------------------------------ | +| **可用性** | 可用 | +| **必需的脚本** | `` | +| **支持的布局** | 没有 | +| **例子** | 请参阅MIP的小故事实力。从“ [创建视觉MIP故事](https://www.mipengine.org/examples/mip-extensions/mip-story.html)教程”中学习。 | + +展现形式如下： + +![story-demo](http://mipstatic.baidu.com/static/mip-static/mip-story/demo/static/oscar5.gif) + +小故事的组织结构为： + +​ 小故事主要由 [mip-story 组件](/examples/mip-extensions/mip-story.html) 承载，充当小故事中所有段落的容器，按照段落个数自动生成段落导航，返回链接，段落播放完的重播和分享功能。 + +小故事具有三个基本概念：段落（view），层（layer）和元素（element）. - 每个小故事可以包含多个段落（view），每个段落充满屏幕。用户操作翻页后，会看到下一个段落。 - 每个段落又可以包含多个层（layer），单个层可以设置布局模式，如多行布局，左右布局，图片拉伸布局等。 - 元素（element）是资源素材，如背景图，主标题，详细描述等。在 `

`、`

`、`` 等标签中声明。 -| 标题 | 内容 | -| ---- | ---------------------------------------- | -| 类型 | 通用 | -| 支持布局 | responsive,fixed-height,fill,container,fixed | +![intro-view-layer-element (1)](http://mipstatic.baidu.com/static/mip-static/mip-story/demo/static/intro-view-layer-element%20(1).jpg) -所需脚本|https://c.mipcdn.com/static/v1/mip-story/mip-story.js
https://c.mipcdn.com/static/v1/mip-share/mip-share.js
https://c.mipcdn.com/static/v1/mip-stats-baidu/mip-stats-baidu.js
https://c.mipcdn.com/static/v1/mip-scrollbox/mip-scrollbox.js +​ 这里的每一个组件都是一个mip组件，其中故事组件为`mip-story`，段落为`mip-story-view`，层为`mip-story-layer`，元素为资源素材，如背景图，主标题，详细描述等。在 `

`、`

`、`` 等标签中声明。 -## 示例 +![mip-story-tag-hierarchy](http://mipstatic.baidu.com/static/mip-static/mip-story/demo/static/demo-story1.png) + +代码结构： -### 基本用法 ```html - - - + + + + + +

Hello, mip-story!

+ + + + + + + +

The End!

+ + + + + + + + + + + + +``` + +以上的详细内容您可以查看[开发小故事前期准备](https://github.com/mipengine/www.mipengine.org/blob/master/source/doc/story/index.md)和[小故事的组织结构]()了解基础信息； + +### 2、各个组件的介绍 + +#### 2.1 `mip-story`组件 + +##### 属性： + +| 属性 | 是否必须 | 取值范围 | 描述 | +| ------------------ | -------- | ------------------ | ---------------------------------------------- | +| `background-audio` | 否 | string（音频地址） | 全局播放的音频地址 | +| `audio-reload` | 否 | 存在/不存在 | 拥有音频的段落在切换后返回，音频会重新从头播放 | +| `audio-hide` | 否 | 存在/不存在 | 音频按钮是否显示 | +| 数据配置 | 否 | json | 用来配置小故事分享页面的内容 | + +- 以下是每个属性的详细使用方法 + + - background-audio：用于配置全局播放的音频地址，需要使用 HTTPS 协议。 + + 示例 + + ```html + + ... + + ``` + + - audio-reload：如果包含该属性，拥有音频的段落在切换后返回，音频会重新从头播放。 + + 示例 + + ```html + + ... + + ``` + + - audio-hide：如果包含该属性，音频按钮会默认隐藏。 + + 示例 + + ```html + + ... + + ``` + + - 数据配置 + + ​ 为提供给用户更多信息和传播渠道，在 `` 段落最后提供了专门用于展示分享及小故事更多相关信息的页面。当用户在最后一个段落继续向后点击时候，即会出现。其中该页面内容需要通过开发者进行配置，具体配置参数如下： + + - share: share 字段下包含的是分享相关的数据。 + - share.thumbnail: 预览小故事的缩略图地址。 + - share.background: 结尾页背景图片地址。 + - share.title: 小故事标题。 + - share.from: 资源的来源信息。 + - recommend: 小故事推荐相关的信息。 + - recommend.items: 推荐小故事列表，它是一个数组，包含了所有推荐的小故事数据。 + - cover: 推荐的小故事背景图片。 + - url: 推荐的小故事跳转地址。 + - title: 推荐的小故事标题。 + - from: 推荐的小故事来源信息。 + - fromUrl: 推荐的小故事来源跳转地址。 + + ```html + + - - - - - -

小故事是什么？

-

快用 MIP 小故事开发很多丰富的交互效果吧！

- 普通跳转链接 - - + } + + + + + + + ``` + + 实际页面效果如下： + + ![share](http://mipstatic.baidu.com/static/mip-static/mip-story/demo/static/share.jpeg) + + 目前，我们支持分享到朋友圈、微信好友、QQ空间、新浪微博； + +#### 2.2 `mip-story-view` + +##### 属性： + +| 属性 | 是否必须 | 取值范围 | 描述 | +| ------------------ | -------- | ------------------ | ---------------------- | +| `id` | 是 | 该段落特有的ID | 用于对当前段落进行定位 | +| `background-audio` | 否 | string（音频地址） | 每个段落播放的音频地址 | + +- 以下是每个属性的详细使用方法 + + - background-audio：用于配置在每个段落播放的音频地址，切换段落后，前一个段落的音频会终止。需要使用 HTTPS 协议。如果同时配置了全局和局部音频，则只会播放全局音频。 + + 示例 + + ```html + + + ... + + + ``` + +#### 2.3 `mip-story-layer` + +​ 该元素表示“层”的概念，在每一个 `` 元素里面可以有多个 layer 作为段落内容，如视频、图片、文字等。 + +##### 属性： + +| 属性 | 是否必须 | 取值范围 | 描述 | +| ---------- | -------- | ------------------------------------------ | ---------------- | +| `template` | 否 | `fill`、`vertical`、`horizontal`、`thirds` | layer 的布局方式 | + +- template：表示一个 layer 的布局方式。 + + 示例 + + ```html + - - - - -

用 MIP 来讲述你的故事！

- + + ... + - + + ``` + +可以分为以下几种布局方式： + +- `template="fill"`：填充布局，该布局方式会将当前 `` 中的第一个元素进行填充布局，其他元素均隐藏。适合于将图片、视频作为背景展示的场景。如图： + +```html + + + ``` -## 数据配置 -为提供给用户更多信息和传播渠道，在 `` 段落最后提供了专门用于展示分享及小故事更多相关信息的页面。当用户在最后一个段落继续向后点击时候，即会出现。其中该页面内容需要通过开发者进行配置，具体配置参数如下： +![layer-fill](http://mipstatic.baidu.com/static/mip-static/mip-story/demo/static/cover-2.png) -- share: share 字段下包含的是分享相关的数据。 -- share.thumbnail: 预览小故事的缩略图地址。 -- share.background: 结尾页背景图片地址。 -- share.title: 小故事标题。 -- share.from: 资源的来源信息。 -- recommend: 小故事推荐相关的信息。 -- recommend.items: 推荐小故事列表，它是一个数组，包含了所有推荐的小故事数据。 - - cover: 推荐的小故事背景图片。 - - url: 推荐的小故事跳转地址。 - - title: 推荐的小故事标题。 - - from: 推荐的小故事来源信息。 - - fromUrl: 推荐的小故事来源跳转地址。 +- `template="vertical"`：`` 中的元素沿 `y` 轴排列，`x` 轴方向填充布局。 -## 为元素添加动画 +```html + +

element 1

+

element 2

+

element 3

+ +``` -在小故事中，我们提供了一些内置的动画，小故事页面元素在进场的时候变得更生动有趣； +![layer-vertical](http://mipstatic.baidu.com/static/mip-static/mip-story/demo/static/cover-3.png) -### 基本用法 +- `template="horizontal"`：`` 中的元素沿 `x` 轴排列，`y` 轴方向填充。 + +```html + +

element 1

+

element 2

+

element 3

+ +``` + +![layer-horizontal](http://mipstatic.baidu.com/static/mip-static/mip-story/demo/static/cover-4.png) + +- `template="thirds"`：支持上中下三列布局，在使用该布局时，内部的元素需要同时加入对应的属性，包括： + - `flex-area='upper-third'`: 元素位于三等分布局的上部； + - `flex-area='middle-third'`: 元素位于三等分布局的中部； + - `flex-area='lower-third'`: 元素位于三等分布局的下部； + + +```html + +

element 1

+

+

element 2

+ +``` + +![layer-thirds](http://mipstatic.baidu.com/static/mip-static/mip-story/demo/static/cover-5.png) + +- **注意：** + +**使用 thirds 布局时，内部的第一次子元素必须使用 `flex-area` 进行声明，并且每个类型的 `flex-area` 只能使用一次，否则会导致元素不能正常展示。** + +**页面中使用视频时，请注意两点：一、视频不建议作为背景填充，因为在 Android 中视频播放器优先级较高会遮住页面内容，导致用户操作不能正常进行。二、视频作为每个段落内容时，不建议设置自动播放，即添加 `autoplay` 属性，因为 iOS 下的部分浏览器会直接弹出系统的视频播放器，影响用户体验。如果需要播放视频，可以暂时使用 GIF + `background-audio` 进行设置。** + +默认情况下会按照正常布局进行展示。 + +#### 内置动画 + +​ 在小故事的层（layer）中可以添加 HTML 元素来完成页面展示，在 HTML 元素中添加 `animate-in` 属性来完成指定的动画效果，例如：可以让标题从左侧滑入、文字淡入出现等。 + +**属性：** + +| 属性 | 是否必须 | 取值范围 | 描述 | +| --------------------- | -------- | ----------------------------------------- | ------------------------------------ | +| `animate-in` | 否 | `fade-in`、`fly-in-top`、`fly-in-bottom`… | 内置动画的类型 | +| `animate-in-duration` | 否 | ms | 元素动画的持续事件 | +| `animate-in-delay` | 否 | ms | 元素动画开始前的延迟时间 | +| `animate-in-after` | 否 | ms | 指定动画在另一个元素动画结束之后触发 | + +​ 基本用法： ```html