dpogue opened a new pull request, #1465:
URL: https://github.com/apache/cordova-ios/pull/1465
### Platforms affected
iOS (watchOS, and macOS Catalyst technically)
### Motivation and Context
Xcode now supports generating all the app icons sizes automatically from a
single 1024⨉1024 PNG image. Supporting this drastically simplifies the
requirements for app developers.
That said, there are cases where an app developer might want to provide
specific icons for specific situations (such as watchOS notifications, or a
macOS Catalyst app) and historically Cordova has been pretty bad at supporting
those customizations due to relying solely on image sizes to handle mappings.
iOS 18 is also introducing dark mode and tinted app icon variants, and we
need a way to support those.
### Description
#### Simple case
For the simplest case, an app developer can provide a single 1024⨉1024 icon
image and list it in their config.xml file with no attributes:
```xml
<platform name="ios">
<icon src="appicon.png" />
</platform>
```
#### With iOS 18 variants
We make use of the `foreground` and `monochrome` attributes, already
supported in Cordova Android, to handle the dark mode and tint-able icon
variants.
The dark mode icon should have a transparent background (hence, the
`foreground` attribute).
The tint-able icon should be a greyscale mask that gets multiplied by the
system tint colour (hence, the `monochrome` attribute).
Example images:
Example config:
```xml
<platform name="ios">
<icon src="appicon.png" foreground="appicon-dark.png"
monochrome="appicon-tint.png" />
</platform>
```
You can provide variants for all iOS icons (but variants are not supported
on watchOS or macOS Catalyst).
#### Platform-specific icons
Apple watchOS supports the same automatic generation of icons from a single
1024⨉1024 icon. By default this will use the app icon, but it can be overridden
by providing another icon with a `target` attribute.
```xml
<platform name="ios">
<icon src="appicon.png" />
<icon src="watchicon.png" target="watchos" />
</platform>
```
Supported targets are `watchos` and `mac`. There's a special case target
`spotlight` for iOS to disambiguate some icons that otherwise have identical
sizes (only applicable if you are providing all your own icon sizes).
The macOS icons do **not** support a single 1024⨉1024 image, so if you want
to customize those then you will need to provide all the required icon sizes
yourself.
#### Providing all the icon sizes
If you prefer to provide all the icons yourself, you can still do so. Note
that if you provide any sized icons, you are required to provide **all** the
sized icons for that platform.
```xml
<platform name="ios">
<icon src="appicon-40.png" width="40" height="40" />
<icon src="appicon-58.png" width="58" height="58" />
<icon src="appicon-60.png" width="60" height="60" />
<icon src="appicon-72.png" width="72" height="72" />
<icon src="appicon-80.png" width="80" height="80" target="spotlight" />
<icon src="appicon-87.png" width="87" height="87" />
<icon src="appicon-120.png" width="120" height="120" />
<icon src="appicon-120.png" width="120" height="120" target="spotlight"
/>
<icon src="appicon-128.png" width="128" height="128" />
<icon src="appicon-136.png" width="136" height="136" />
<icon src="appicon-144.png" width="144" height="144" />
<icon src="appicon-152.png" width="152" height="152" />
<icon src="appicon-167.png" width="167" height="167" />
<icon src="appicon-180.png" width="180" height="180" />
<icon src="appicon-196.png" width="196" height="196" />
<icon src="appicon-1024.png" width="1024" height="1024" />
</platform>
```
You can also provide all the icons for the `watchos` and `mac` targets, with
all their respective sizes.
### Testing
<!-- Please describe in detail how you tested your changes. -->
- [x] Existing unit tests pass
- [ ] New unit tests written to provide code coverage of icon mapping changes
- [ ] Testing in a real project with simple icon mapping
- [ ] Tested in a real project with complex icon mapping
### Closed issues
Closes #592.
Closes #623.
Closes #657.
Closes #658.
Closes #1019.
Closes #1233.
Closes #1387.
Closes #1462.
### Checklist
- [ ] I've run the tests to see all new and existing tests pass
- [ ] I added automated test coverage as appropriate for this change
- [ ] Commit is prefixed with `(platform)` if this change only applies to
one platform (e.g. `(android)`)
- [ ] If this Pull Request resolves an issue, I linked to the issue in the
text above (and used the correct [keyword to close issues using
keywords](https://help.github.com/articles/closing-issues-using-keywords/))
- [ ] I've updated the documentation if necessary
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscr...@cordova.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@cordova.apache.org
For additional commands, e-mail: issues-h...@cordova.apache.org
