NativeScript Angular Shadow Directive 插件

此仓库是 @Especializa 的 NativeScript Shadow Directive 的分支。https://github.com/Especializa/nativescript-ng-shadow

安装

从命令提示符进入您的应用根目录并执行

tns plugin add @imagene.me/nativescript-shadow

演示

如何使用

这是一个 Angular 指令，可以帮助您更容易地实现原生阴影。

阴影是 Material Design 规范的重要组成部分。它提出了提升概念，即在自然的人类感知物体从表面升起的方式中。

使用此指令，您不必担心 Android 和 iOS 上的所有阴影方面。另一方面，如果您关心任何细节，只需提供额外的属性，它们将覆盖默认属性。

然而，在 Android 上运行此指令需要 SDK 版本大于或等于 21（Android 5.0 Lollipop 或更高版本），否则阴影将不会显示。在 iOS 上的任何版本上运行都不会有问题。

导入 NgShadowModule

// ...
import { NgShadowModule } from "@imagene.me/nativescript-shadow/angular";

@NgModule({
  imports: [
    NgShadowModule
    // ...
  ]
  // ...
})
export class MyModule {}

只需在模板中使用即可

简单属性 shadow

<Label shadow="2"></Label>

当然可以绑定属性

<Label [shadow]="myCustomShadow"></Label>

要提供其他详细信息，请结合使用 shadow 指令和其他属性

<Label shadow [elevation]="myElevation" cornerRadius="5"></Label>

有几个平台特定的属性，您可能想要使用以自定义视图。请注意，其中一些与应用于相同视图的 CSS 样式冲突。在这种情况下，Android 上的默认行为是保留由本指令提供的样式，而忽略原始的 HTML/CSS 样式。另一方面，iOS 上将考虑现有的 HTML/CSS 样式，因此阴影可能不会应用。

建议避免将诸如 背景颜色 和 边框半径 等内容应用于要应用此指令的同一视图（注意：现在已支持）。您始终可以嵌套视图并得到您想要的结果。如果不可以，请留言，以便我们尝试帮助。

属性列表

下表列出了所有可能的属性，并描述了每个属性以及支持它们的平台

属性	类型	平台	描述
shadow	string \| number \| AndroidData \| IOSData	both	指令属性。提供 `null` 或空字符串且没有 `elevation` 属性时，将关闭阴影
elevation	number \| string	both	确定视图从表面提升的高度。它执行所有与阴影相关的计算。您可能想看看此枚举中标准材料设计提升的高度。 PS：自2.0版本起，在Android上使用DIP（或DP，密度无关像素）进行计算，在iOS上使用PT（点）。
pressedElevation	number \| string	Android	确定视图在按下状态下的高度。
shape	string => `'RECTANGLE'` \| `'OVAL'` \| `'RING'` \| `'LINE'` 默认：`'RECTANGLE'`	Android	确定视图的形状并覆盖其格式样式。
bgcolor	string => 颜色 #RGB	Android	确定视图的背景颜色并覆盖其之前背景。如果未设置，则使用之前的背景。注意：将背景设置为透明在Android上可能导致问题（阴影可能会重叠背景）
cornerRadius	number	Android	确定视图的圆角半径（CSS border-radius）并覆盖其之前的样式。如果未设置，则使用视图的CSS border-radius。 PS：自2.0版本起，它以DIP（或DP，密度无关像素）计算。
translationZ	number	Android	确定到表面的额外距离（以DIP为单位）。
pressedTranslationZ	number	Android	确定视图处于按下状态时到表面的额外距离（以DIP为单位）。
forcePressAnimation	boolean => 默认：false	Android	默认情况下，如果视图有StateAnimator，它将被一个抬起视图的动画器覆盖。将此设置为true将始终定义此新动画器，从而使任何可点击的视图都能像按钮一样工作。
maskToBounds	boolean => 默认：false	iOS	确定阴影是否将限制在视图边距内。
shadowColor	string => 颜色 #RGB	iOS	确定阴影颜色。如果视图已经有背景，则不会应用阴影。
shadowOffset	number	iOS	确定阴影在点（仅在Y轴上）的距离。负值表示阴影在视图上方。
shadowOpacity	number	iOS	从0到1。确定阴影的不透明度级别。
shadowRadius	number	iOS	确定阴影的模糊效果（以点为单位）。值越高，模糊度越大。
useShadowPath	boolean => 默认：true	iOS	确定是否使用shadowPath渲染阴影。将此设置为false会负面影响性能。
rasterize	boolean => 默认：false	iOS	确定视图是否应该被光栅化。启用此选项会增加内存使用量，因为光栅化的视图存储在内存中，但将大大提高性能。

`AndroidData` 和 `IOSData`

如您所注意到的，主要的 shadow 属性接受对象作为参数。您可以在属性绑定中分配它，并将覆盖您可能定义的任何可能的单独属性。

组件

import { AndroidData, ShapeEnum } from "@imagene.me/nativescript-shadow";
// ...
export class MyComponent {
  fabShadow: AndroidData = {
    elevation: 6,
    bgcolor: "#ff1744",
    shape: ShapeEnum.OVAL
  };
  // ...
}

在模板中，您可以执行以下操作

<Label [shadow]="fabShadow" width="56" height="56"></Label>

预定义的高度

如果您想与Material Design规范保持一致，但又厌倦了记住视图应该具有哪个高度，我们为您准备了一个预定义高度的列表

切换：1
CARD_RESTING：2
RAISED_BUTTON_RESTING：2
SEARCH_BAR_RESTING：2
REFRESH_INDICATOR：3
SEARCH_BAR_SCROLLED：3
APPBAR：4
FAB_RESTING：6
SNACKBAR：6
BOTTOM_NAVIGATION_BAR：8
MENU：8
CARD_PICKED_UP：8
RAISED_BUTTON_PRESSED：8
SUBMENU_LEVEL1：9
SUBMENU_LEVEL2：10
SUBMENU_LEVEL3：11
SUBMENU_LEVEL4：12
SUBMENU_LEVEL5：13
FAB_PRESSED：12
NAV_DRAWER：16
RIGHT_DRAWER：16
MODAL_BOTTOM_SHEET：16
DIALOG：24
PICKER：24

如果您甚至不想每次需要为视图添加阴影时都检查，只需导入Elevation枚举并享受即可：）

组件

import { Elevation } from "@imagene.me/nativescript-shadow";
class MyComponent {
  // ...
  ngOnInit(): init {
    this.mySnackBar.elevation = Elevation.SNACKBAR;
  }
  // ...
}

关于版本2+的说明

以下是2.0版本上的改进列表

BugFix：整数指令在iOS上不渲染。
密度无关像素：现在您无需再担心根据设备的屏幕密度提供像素相关属性的准确值。自iPhone 6S以来，每个点对应9个设备像素（水平方向3个，垂直方向3个——这就是@3x图片的原因——更多信息请查看这里）。在Android中也是如此，其中基准值（mdpi）被认为是每英寸大约160像素（或点），而大多数现代设备的屏幕密度要高得多，达到大约640dpi或更高。更多信息请查看这里。
新增一个名为translationZ的特定于Android的新属性。elevation属性是虚拟Z轴（3D轴）的基准，但根据官方文档，它并非唯一的部分。然后，translationZ将为表面添加额外的距离，它主要用于动画。
2.1.X 如下所述覆盖Android默认的StateListAnimator

覆盖Android默认的StateListAnimator

Android按钮分为三类：浮动、提升和平坦。与标签和其他UI元素不同，每个按钮类别都有自己的状态动画器。因此，当按钮被按下时，Android会以Angular未通知的方式影响它们的elevation（和Z轴平移）。在触摸动画结束时，按钮会回到静止默认状态（即提升按钮的elevation为2dp，translationZ为0），覆盖由该插件建立的阴影。

自2.1.0版本以来，此插件替换了默认的StateListAnimator，使其回到您提供的elevation和translationZ值。

如果您想定义自己的StateListAnimator，请随时提交问题。到目前为止，动机仅仅是让此插件在没有更改按钮原始状态的情况下工作。

还可以将此StateListAnimator设置到任何View中，使其表现得像按钮。

插件开发工作流程

将仓库克隆到您的机器上。
运行npm install来准备项目
使用npm run android或npm run ios运行并部署到您的设备或模拟器
使用npm run build构建ngPackagr版本

变更日志

6.0.0 Fork：现在与ngPackagr打包以兼容Angular 6
2.1.0 解耦阴影逻辑/覆盖默认StateListAnimator
2.0.1 修复旧Android设备（< Lollipop）的错误
2.0.0 密度无关像素/TranslationZ
1.1.3 小问题
1.1.2 修复CI构建
1.1.0 支持iOS自定义属性
1.0.0 初始实现

许可证

Apache许可证版本2.0，2004年1月