LLDark 1.1.7

LLDark 1.1.7

internetwei维护。



LLDark 1.1.7

  • 作者:
  • internetwei

LLDark

License MIT  Carthage  CocoaPods  Platform  Support

为iOS提供暗黑主题框架,快速且易于适应暗黑模式。
中国大陆用户可以访问此链接
中文介绍
GitHub不显示图片解决方案

特性

  • 集成非常简单,只需要几处更改,项目结构不会被破坏。
  • 高性能,仅在需要刷新时刷新当前页面的UI。
  • 强大,覆盖UIColor、UIImage、CGColor的所有使用场景。
  • 兼容iOS13以下的模型。
  • 支持从互联网获取暗黑主题配置。
  • 自动适应启动图片是APP当前的暗黑模式,支持iOS13以下的模型。
  • 支持动态修改任何类型的启动图片。

示例

Manual.gif System.gif Screen.gif LightVertical.gif

用法

前提条件

配置深色资源:在项目中的任何NSObject分类中创建 + (NSDictionary *)llDarkTheme 类方法(建议创建一个单独的分类)。字典的键代表浅色主题下的颜色/图片名称/图片地址,字典的值代表深色主题下的颜色/图片名称/图片地址。可以参考示例代码

+ (NSDictionary<id, id> *)llDarkTheme {
    return @{
             UIColor.whiteColor : kColorRGB(27, 27, 27),
             kColorRGB(240, 238, 245) : kColorRGB(39, 39, 39),
             [UIColor colorWithRed:14.0 / 255.0 green:255.0 / 255.0 blue:0.0 alpha:1.0] : [UIColor colorWithRed:0.0 green:14.0 / 255.0 blue:255.0 / 255.0 alpha:1.0],
             @"background_light" : @"background_dark",
             @"~/path/background_light.png" : @"~/path/background_dark.png",
    };
}

提示:1.在所有情况下没有必要填写所有颜色/图片。对于偶尔或很少使用的深色,可以参考高级用法进行单独的适配。2.如果填写了图片路径,必须填写完整的图片路径(包括后缀)。

基本用法

UIColor 和 CGColor 只需附加 .themeColor(nil)。UIImage 只需使用 themeImage 替换 imageNamed 或 imageWithContentsOfFile。

// UIColor
UIColor.redColor; // Previous usage
UIColor.redColor.themeColor(nil); // Current usage

// CGColor
UIColor.redColor.CGColor; // Previous usage
UIColor.redColor.themeCGColor(nil); // Current usage

// UIImage
[UIImage imageNamed:@"lightImageName"]; // Previous usage
[UIImage themeImage:@"lightImageName"]; // Current usage

提示:1.themeImage 适配了 imageNamed 和 imageWithContentsOfFile 两种方法,可以传递图片名称或图片路径。2.主题切换时,只有适配过的颜色和图片会刷新。

高级用法

1. If the parameter in themeColor() is a specific Color object, the dark theme will refresh with the specified Color object.
If it is nil, it will return to the dark color refresh configured in llDarkTheme,
If llDarkTheme is not configured, it will return the color under the light theme.

2. The function of the themeCGColor() parameter is the same as the function of the themeColor() parameter.

3. themeImage() has 2 parameters, the parameter can be the image name or the image address,
The first parameter represents the picture used under the light theme (required),
The second parameter represents the picture used under the dark theme (can be empty),
If the second parameter is empty, the treatment is the same as if themeColor() is empty.

4. appearanceBindUpdater,All objects inherited from UIView have this property,
It will be called when the object needs to be refreshed, and you can implement your own refresh logic here.
It is only called when a refresh is needed, and the theme change does not necessarily require refreshing the UI.

5. userInterfaceStyle,Similar to the overrideUserInterfaceStyle method of iOS13 system,
But the function is more powerful than overrideUserInterfaceStyle,
It supports all objects, such as CALayer.
It supports system usage below iOS13.

6. themeDidChange,All objects have this property, which is the same as ThemeDidChangeNotification.
themeDidChange will be released when the object is released,
Can be used in multiple places, the callback order is not guaranteed,
Unlike appearanceBindUpdater, themeDidChange is called whenever the theme changes.

7. systemThemeDidChange,All objects have this property, which is the same as SystemThemeDidChangeNotification.
The release timing is the same as themeDidChange,
Can be used in multiple places, the callback order is not guaranteed,
As long as the system theme changes, systemThemeDidChange will be called.

8. darkStyle,All UIImageView objects have this method to adapt to image objects without dark images, such as web images.
DarkStyle has 3 parameters. The first parameter determines how to adapt to the dark theme. There are currently two types: LLDarkStyleSaturation and LLDarkStyleMask.
LLDarkStyleMask uses mask adaptation, and LLDarkStyleSaturation adapts by reducing the saturation of the original image.
The second parameter determines the transparency/saturation value of the mask. For specific usage, please refer to the source code comments.
The third parameter can be nil. When using LLDarkStyleSaturation, you need to pass a unique string as an identifier, usually the url of the image.
Sample code:
UIImageView *imageView = [[UIImageView alloc] init];
NSString *url = @"Picture URL";
imageView.darkStyle(LLDarkStyleSaturation, 0.2, url);
// imageView.darkStyle(LLDarkStyleMask, 0.5, nil);

9. updateDarkTheme:,If you need to modify the dark theme configuration information at runtime, or need to obtain dark theme configuration information from the Internet, you can use updateDarkTheme: to achieve the goal.
Please ensure that the dark theme information is configured before the first UI object is loaded, otherwise it will be invalid.
Sample code:
NSDictionary *darkTheme = @{
    UIColor.whiteColor : kColorRGB(27, 27, 27),
    kColorRGB(240, 238, 245) : kColorRGB(39, 39, 39),
    [UIColor colorWithRed:14.0 / 255.0 green:255.0 / 255.0 blue:0.0 alpha:1.0] : [UIColor colorWithRed:0.0 green:14.0 / 255.0 blue:255.0 /  255.0 alpha:1.0],
    @"background_light" : @"background_dark",
    @"~/path/background_light.png" : @"~/path/background_dark.png",
};
[LLDarkSource updateDarkTheme:darkTheme];

10. thirdControlClassName,If you need to support the refresh method of the third-party control, you can implement the refresh logic separately in appearanceBindUpdater, or you can implement the refresh logic according to the following methods, and the following methods are more recommended.
First, you need to implement the thirdControlClassName class method and return an array containing the class name string of the third party control.
Then implement the refresh+class name string object method, and implement the refresh logic of the third-party control in the method. You can refer to the YYLabel refresh logic that has been implemented in the LLThird.m file.
For details, you can download the project and view the Demo to understand the specific implementation.

11. If you need to support the adaptation of the dark startup image in iOS13 or lower, please name the dark image according to the specified rules and place it in any directory of the project.
Naming rule: launchImage_<screen width>_<screen height>.
For example: launchImage_414_736, this dark launch image will appear after switching to dark mode on models with a screen width of 414×736 and systems below iOS13.
If you want to adapt the horizontal image, you only need to exchange the width and height positions, for example: launchImage_736_414.
The specific effect can be viewed by running Demo on the system below iOS13 and switching to dark mode.
For specific naming, please refer to the image naming method under the LaunchImage folder in the Demo project. It contains the dark launch image of all models below iOS 13 (including horizontal screen, excluding models before iPhone 6).

12. LLLaunchScreen provides some class methods, reasonable use of these class methods can perfectly replace any startup image of APP, including "dark vertical launch Image", "dark horizontal launch Image", "light vertical launch Image", "Light horizontal launch Image".
Please refer to the LLLaunchScreen.h file for specific methods.
For usage method, please refer to Demo.

高级用法中第8号 darkStyle 方法示例图(为了突出效果,饱和度和透明度调整得非常低):5fc91820394ac523788c48f4

快速适应

只需3步即可快速完美适应深色主题模式。经过测试,大多数项目可以在0.5天内完成适应。

  1. 要配置深色主题资源,请参阅先决条件,或参阅高级方法9以从网络获取资源适应。
  2. 适应需要适应到主题颜色和主题图片的颜色和图片。关于适应方法,请参阅基本用法高级用法
  3. 运行项目并检查完整性。

提示

  1. 如果您还需要适应WKWebView,可以点击此链接,参考文章进行适应。
  2. 默认情况下,iOS13及以上系统将自动适应启动图片,以跟随APP主题模式的变化,如果您想使用iOS13以下的系统,此功能也支持,请参阅高级用法11高级用法12

安装

CocoaPods

  1. 运行
  2. 导入

Carthage

  1. github "internetWei/LLDark"添加到您的Cartfile中。
  2. 运行carthage update --platform ios并将框架添加到项目中。
  3. 导入

手动

  1. 下载LLDark子目录下的所有文件。
  2. 将LLDark文件夹添加(拖放)到您的项目中。
  3. 导入LLDark.h。

需求

项目支持至少iOS 9.0和Xcode 10.0。如果您想在更低版本的系统中使用,请联系作者。

注意

  1. LLDark不会修改状态栏样式,您需要监控主题模式来修改状态栏样式。
  2. 不建议将需要适配暗黑主题的图片资源放置在Assets.xcassets中。测试发现,在 NSAttributedString 中的图片在主题切换时不会刷新(使用imageNamed:加载)。这是一个系统漏洞。解决方案是将图片放在项目下,并使用themeImage:加载。
  3. UIKit实例对象有一个imageWithRenderingMode:方法。调用此方法将重新生成并返回UIKit实例对象,这会导致正常刷新。请使用renderingModeFrom方法代替。

已知问题

  • 目前不支持其他主题模式,未来将自由支持各种主题。

联系

如果您有更好的改进,请向我提出拉取请求。

如果您有任何更好的评论,请创建一个问题

作者可以通过此邮箱联系[email protected]

许可

LLDark遵循MIT许可证发布。有关详细信息,请参阅LICENSE文件。