NativeScript Angular 阴影指令插件

此存储库是基于 @Especializa 的 NativeScript Shadow Directive 分支而来。https://github.com/Especializa/nativescript-ng-shadow

安装

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

tns plugin add nativescript-ngx-shadow

演示

如何使用它

这是一个 Angular 指令，使您在处理原生阴影时更加轻松。

阴影是 Material 设计规范的重要组成部分。它引入了提升概念，这体现了人类自然地感知物体从表面抬起的方式。

有了这个指令，您无需担心 Android 和 iOS 上的所有阴影相关方面。另一方面，如果您关心细节，只需提供额外的属性，它们将覆盖默认属性。

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

导入 NgShadowModule

// ...
import { NgShadowModule } from "nativescript-ngx-shadow";

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

`AndroidData` 和 `IOSData`

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

组件

import { AndroidData, ShapeEnum } from "nativescript-ngx-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
菜单：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
对话框：24
选择器：24

如果您甚至不想每次阴影视图时都检查它，只需导入Elevation枚举并享受即可 :)

组件

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

关于版本2+的说明

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

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

覆盖Android默认StateListAnimator

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

从版本2.1.0开始，此插件用一个新的StateListAnimator替换了默认的StateListAnimator，该新动画器会恢复您提供的elevation和translationZ值。

如果您想定义自己的StateListAnimator，请随意提交一个问题。到目前为止，动机很简单，即使此插件在没有更改原始状态的情况下与按钮一起工作。

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

插件开发工作流程

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

变更日志

6.0.0 分支：现在与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月