NativeScript NA Slideshow 插件

注意！目前不支持 Android。

安装

$ tns plugin add nativescript-na-slideshow

用法

XML

幻灯片可以手动添加到下面的 XML 中

<AbsoluteLayout id="slideShow" loaded="load_slideShow">
  <GridLayout backgroundColor="#ffffff">
    <Label text="Slide 1" horizontalAlignment="center" />
  </GridLayout>
  <GridLayout backgroundColor="#f2f2f2">
    <Label text="Slide 2" horizontalAlignment="center" />
  </GridLayout>
  <GridLayout backgroundColor="#ffffff">
    <Label text="Slide 3" horizontalAlignment="center" />
  </GridLayout>
</AbsoluteLayout>

非常重要，幻灯片容器必须是 AbsoluteLayout，否则将出现问题。幻灯片也可以使用 ObservableArray 创建，而不是像上面那样静态。为此，容器必须保持为空 - 如下所示

<AbsoluteLayout id="slideShow" loaded="load_slideShow" />

… 或者通过 Repeater 初始化项模板

<AbsoluteLayout id="slideShow" loaded="load_slideShow">
  <Repeater items="{{ slides }}">
    <Repeater.itemTemplate>
      <GridLayout>
        <Label text="{{ text }}" />
      </GridLayout>
    </Repeater.itemTemplate>
  </Repeater>
</AbsoluteLayout>

请注意，以这种方式操作时，如果设置了 Repeater.itemsLayout 标签，则会被忽略。所以不需要使用它。

在开始 JavaScript 部分之前，请确保 loaded 属性设置如下示例所示： loaded="load_slideShow"。这是为了让 JavaScript 代码将容器转换为幻灯片。

JS

一旦设置了 XML，插件现在可以将容器转换为幻灯片。要这样做，请参阅以下内容

var NASlideShow = require("nativescript-na-slideshow");

exports.load_slideShow = function(args) {
  var view = args.object;
  var slideShow = new NASlideShow();
  
  slideShow.init(view);
};

完成以上步骤后，幻灯片现在正在运行！

实例属性

在上面的 JS 示例中，init() 函数使用了默认属性。以下是一个所有属性及其默认值的列表

{
  items: false, // An ObservableArray instance.
  itemTemplate: "<GridLayout />", // The view template for each slide (has to be written as an XML string). See the Repeater documentation for further information.
  enableBounce: false, // Scroll bouncing disabled by default.
  fallbackWidth: [screen width], // In case the inherited width doesn't load in time.
  fallbackHeight: [screen height], // In case the inherited height doesn't load in time.
  clipToBounds: true, // Similar to "overflow" in CSS
  indicators: {
    size: 10, // The indicators' size.
    color: "#808080", // The indicators' color.
    activeColor: false, // The active indicator's color.
    borderWidth: 0, // The indicators' border width.
    borderColor: "#404040", // The indicators' border color.
    horizontalAlignment: "center", // The horizontal alignment of the indicators.
    verticalAlignment: "bottom", // The vertical alignment of the indicators.
    iconShadow: false, // Icon shadow. Can be a boolean or an object
    forceVisibility: false, // By default, indicators will only show up if there are 2 slides or more.
    disabled: false // Disable the indicators.
  }
}

itemTemplate 属性是特殊的，因为根据 Repeater 文档，它必须是 XML 格式的字符串。

fallbackWidth 和 fallbackHeight 属性在继承的宽度和高度在视图加载状态下尚未设置时有时是必需的。

indicators.iconShadow 可以通过将其设置为对象来自定义。以下是默认属性

{
  color: "#000000", // HEX color
  alpha: 1, // Opacity (1 to 0)
  x: 0, // Horizontal offset
  y: 0, // Vertical offset
  radius: 2 // Radius amount
}

方法

init()

必须调用此方法来初始化幻灯片视图。

init(template, props)

• template - 将成为幻灯片的视图容器（模板）。
• props - 设置任何实例属性（可选）。

var frameModule = require("ui/frame");
var observableArray = require("data/observable-array").ObservableArray;
var container = frameModule.topmost().currentPage.getViewById("slideShow");
var slideShow = new NASlideShow();

slideShow.init(container, {
  items: new ObservableArray("Slide 1", "Slide 2", "Slide 3"),
  itemTemplate: '<GridLayout><Label text="{{ $value }}" horizontalAlignment="center" /></GridLayout>',
  indicators: {
    forceVisibility: true,
    verticalAlignment: "top",
    color: "#ffffff"
  }
});

insertSlide()

调用此方法以插入新幻灯片。根据幻灯片是否仅使用 XML 或 ObservableArray 实例来启动，视图参数的工作方式略有不同。

insertSlide(slideView, props)

• slideView - 将成为幻灯片的视图容器/字符串/对象。
• props - 设置任何实例属性（可选）。

XML

var GridLayout = require("ui/layouts/grid-layout").GridLayout;
var Label = require("ui/label").Label;

var slideView = new GridLayout();
var textLabel = new Label();
textLabel.text = "Slide 4";
slideView.insertChild(textLabel, 0);

slideShow.insertSlide(slideView, {
  indicator: {
    icon: "+",
    float: true
  }
});

ObservableArray

slideShow.insertSlide("Slide 4", {
  indicator: {
    icon: "+",
    float: true
  }
});

props 参数的默认值如下

{
  atIndex: [last] // Inserts the slide at specified index number.
  indicator: {
    icon: false, // Custom icon (or character) instead of a dot.
    fontFamily: false, // The icon font family.
    float: false // Set to true to make the icon float to the right, as in not adjusting the indicators horizontal alignment.
  }
}

float 属性在 atIndex 设置为除最后一个以外的任何值或幻灯片实例的 horizontalAlignment 设置为 "right" 时会被忽略。这是为了防止视觉错误。

removeSlide()

在指定的索引处删除幻灯片。

removeSlide(index)

• index - 要在指定索引处删除的幻灯片。

要删除第一个幻灯片

slideShow.removeSlide(0);

on()

每个幻灯片滚动的监听器。当幻灯片完成滚动时，将调用事件。

on("slideChange", callback)

• "slideChange" - 唯一可用的 eventName。
• callback - 每次通知时的回调。

slideShow.on("slideChange", function(eventData) {
  console.log("Slide index: " + eventData.index);
});

回调函数内部的 eventData 参数包含以下属性

• eventName - 事件的名称。
• object - 幻灯片视图。
• index - 当前幻灯片索引。
• 长度 - 幻灯片总数。

setSlide()

设置现有幻灯片的新视图/值。

setSlide(index, value)

• index - 指定索引处的幻灯片视图/值。
• value - 幻灯片视图/值（取决于 slideShow 是否使用 ObservableArray）。

设置第一张幻灯片

slideShow.setSlide(0, { text: "Updated content", backgroundColor: "#ffffff" });

scrollToSlide()

设置现有幻灯片的新视图/值。

scrollToSlide(index, animated)

• index - 滚动到指定索引的幻灯片。
• animated - 布尔参数。是否应该动画滚动（默认为 false）。

滚动到最后一张幻灯片（动画效果）

slideShow.scrollToSlide(slideShow.getSlidesCount()-1, true);

其他方法

• getSlide(index) - 获取指定索引处的幻灯片。
  • 返回幻灯片视图/值
• getSlidesCount() - 获取幻灯片总数。
  • 返回 number
• getSlideIndex() - 获取当前幻灯片索引。
  • 返回 number
• clearSlides() - 清除整个幻灯片播放。

其他属性

• view - 返回幻灯片播放视图对象（用于启动幻灯片播放的视图容器/模板）。
• viewsList - 所有子视图列表
  • scrollView - 滚动视图。
  • container - 幻灯片播放的内部容器。
  • indicators - 指示器视图。
  • repeater - 重复视图（仅在使用 ObservableArray 时可用）。
• items - 返回 ObservableArray（仅在使用 ObservableArray 时可用）。

已知问题

• 尚未兼容 Android。

历史记录

版本 1.5.0（2016 年 12 月 3 日）

• 更好的代码结构。
• 错误修复：当 forceVisibility 设置为 false 时，在删除倒数第二张幻灯片时被忽略。

版本 1.4.3（2016 年 10 月 17 日）

• 错误修复：clipToBounds 属性未正确工作。

版本 1.4.2（2016 年 10 月 16 日）

• 将指示器属性从 disable 更改为 disabled（请参阅 init() 文档）。
• 在 init() 中添加了 clipToBounds 属性（请参阅文档）。

版本 1.4.1（2016 年 10 月 13 日）

• 错误修复
  • 当使用 ObservableArray/Repeater 删除幻灯片后，无法插入新幻灯片。
  • 删除幻灯片后，活动幻灯片指示器颜色未保留。

版本 1.4.0（2016 年 10 月 12 日）

• 新方法：clearSlides()
• 还可以从 XML 创建 Repeater（请参阅 用法）。

版本 1.3.2（2016 年 9 月 16 日）

• 新方法：scrollToSlide()

版本 1.3.1（2016 年 9 月 15 日）

• 热修复：完全忽略 forceVisibility。

版本 1.3.0（2016 年 9 月 15 日）

• 新方法：getSlide() 和 setSlide()
• 现在可以为活动幻灯片指示器设置自定义颜色。
• 修复了 forceVisibility 的错误。
• 修复了当在最后一个索引处使用 removeSlide() 时导致应用崩溃的错误。

版本 1.2.0（2016 年 9 月 12 日）

对于快速更新（同一天，哇）表示歉意。这一次有很多新增内容

• 新方法：removeSlide()
• 为指示器添加了水平和垂直对齐（请参阅 init() 文档）。
• 为指示器添加了 iconShadow 属性（请参阅 init() 文档）。
• appendSlide() 已重命名为 insertSlide()。
• insertSlide() 现在可以使用 atIndex 属性在指定索引处插入幻灯片。
• 修复了当在 init() 时 ObservableArray 为空时，指示器圆点仍然出现的问题。

版本 1.1.0（2016 年 9 月 12 日）

• 新方法：getSlidesCount()
• 更新了 README.md
• 错误修复。存在与 appendSlide() 函数的问题。

版本 1.0.0（2016 年 9 月 9 日）

• init()
• appendSlide()
• on()
• getSlideIndex()

致谢

• NordlingArt

许可证

MIT - for {N} version 2.0.0+