docs-translations/th-TH/api/native-image.md

   1 # nativeImage
   2
   3 > Create tray, dock, and application icons using PNG or JPG files.
   4
   5 Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
   6
   7 In Electron, for the APIs that take images, you can pass either file paths or
   8 `NativeImage` instances. An empty image will be used when `null` is passed.
   9
  10 For example, when creating a tray or setting a window's icon, you can pass an
  11 image file path as a `String`:
  12
  13 ```javascript
  14 const {BrowserWindow, Tray} = require('electron')
  15
  16 const appIcon = new Tray('/Users/somebody/images/icon.png')
  17 let win = new BrowserWindow({icon: '/Users/somebody/images/window.png'})
  18 console.log(appIcon, win)
  19 ```
  20
  21 Or read the image from the clipboard which returns a `NativeImage`:
  22
  23 ```javascript
  24 const {clipboard, Tray} = require('electron')
  25 const image = clipboard.readImage()
  26 const appIcon = new Tray(image)
  27 console.log(appIcon)
  28 ```
  29
  30 ## Supported Formats
  31
  32 Currently `PNG` and `JPEG` image formats are supported. `PNG` is recommended
  33 because of its support for transparency and lossless compression.
  34
  35 On Windows, you can also load `ICO` icons from file paths. For best visual
  36 quality it is recommended to include at least the following sizes in the:
  37
  38 * Small icon
  39  * 16x16 (100% DPI scale)
  40  * 20x20 (125% DPI scale)
  41  * 24x24 (150% DPI scale)
  42  * 32x32 (200% DPI scale)
  43 * Large icon
  44  * 32x32 (100% DPI scale)
  45  * 40x40 (125% DPI scale)
  46  * 48x48 (150% DPI scale)
  47  * 64x64 (200% DPI scale)
  48 * 256x256
  49
  50 Check the *Size requirements* section in [this article][icons].
  51
  52 [icons]:https://msdn.microsoft.com/en-us/library/windows/desktop/dn742485(v=vs.85).aspx
  53
  54 ## High Resolution Image
  55
  56 On platforms that have high-DPI support such as Apple Retina displays, you can
  57 append `@2x` after image's base filename to mark it as a high resolution image.
  58
  59 For example if `icon.png` is a normal image that has standard resolution, then
  60 `icon@2x.png` will be treated as a high resolution image that has double DPI
  61 density.
  62
  63 If you want to support displays with different DPI densities at the same time,
  64 you can put images with different sizes in the same folder and use the filename
  65 without DPI suffixes. For example:
  66
  67 ```text
  68 images/
  69 ├── icon.png
  70 ├── icon@2x.png
  71 └── icon@3x.png
  72 ```
  73
  74
  75 ```javascript
  76 const {Tray} = require('electron')
  77 let appIcon = new Tray('/Users/somebody/images/icon.png')
  78 console.log(appIcon)
  79 ```
  80
  81 Following suffixes for DPI are also supported:
  82
  83 * `@1x`
  84 * `@1.25x`
  85 * `@1.33x`
  86 * `@1.4x`
  87 * `@1.5x`
  88 * `@1.8x`
  89 * `@2x`
  90 * `@2.5x`
  91 * `@3x`
  92 * `@4x`
  93 * `@5x`
  94
  95 ## Template Image
  96
  97 Template images consist of black and clear colors (and an alpha channel).
  98 Template images are not intended to be used as standalone images and are usually
  99 mixed with other content to create the desired final appearance.
 100
 101 The most common case is to use template images for a menu bar icon so it can
 102 adapt to both light and dark menu bars.
 103
 104 **Note:** Template image is only supported on macOS.
 105
 106 To mark an image as a template image, its filename should end with the word
 107 `Template`. For example:
 108
 109 * `xxxTemplate.png`
 110 * `xxxTemplate@2x.png`
 111
 112 ## Methods
 113
 114 The `nativeImage` module has the following methods, all of which return
 115 an instance of the `NativeImage` class:
 116
 117 ### `nativeImage.createEmpty()`
 118
 119 Returns `NativeImage`
 120
 121 Creates an empty `NativeImage` instance.
 122
 123 ### `nativeImage.createFromPath(path)`
 124
 125 * `path` String
 126
 127 Returns `NativeImage`
 128
 129 Creates a new `NativeImage` instance from a file located at `path`. This method
 130 returns an empty image if the `path` does not exist, cannot be read, or is not
 131 a valid image.
 132
 133 ```javascript
 134 const nativeImage = require('electron').nativeImage
 135
 136 let image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
 137 console.log(image)
 138 ```
 139
 140 ### `nativeImage.createFromBuffer(buffer[, options])`
 141
 142 * `buffer` [Buffer][buffer]
 143 * `options` Object (optional)
 144   * `width` Integer (optional) - Required for bitmap buffers.
 145   * `height` Integer (optional) - Required for bitmap buffers.
 146   * `scaleFactor` Double (optional) - Defaults to 1.0.
 147
 148 Returns `NativeImage`
 149
 150 Creates a new `NativeImage` instance from `buffer`.
 151
 152 ### `nativeImage.createFromDataURL(dataURL)`
 153
 154 * `dataURL` String
 155
 156 Creates a new `NativeImage` instance from `dataURL`.
 157
 158 ## Class: NativeImage
 159
 160 > Natively wrap images such as tray, dock, and application icons.
 161
 162 Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
 163
 164 ### Instance Methods
 165
 166 The following methods are available on instances of the `NativeImage` class:
 167
 168 #### `image.toPNG()`
 169
 170 Returns `Buffer` - A [Buffer][buffer] that contains the image's `PNG` encoded data.
 171
 172 #### `image.toJPEG(quality)`
 173
 174 * `quality` Integer (**required**) - Between 0 - 100.
 175
 176 Returns `Buffer` - A [Buffer][buffer] that contains the image's `JPEG` encoded data.
 177
 178 #### `image.toBitmap()`
 179
 180 Returns `Buffer` - A [Buffer][buffer] that contains a copy of the image's raw bitmap pixel
 181 data.
 182
 183 #### `image.toDataURL()`
 184
 185 Returns `String` - The data URL of the image.
 186
 187 #### `image.getBitmap()`
 188
 189 Returns `Buffer` - A [Buffer][buffer] that contains the image's raw bitmap pixel data.
 190
 191 The difference between `getBitmap()` and `toBitmap()` is, `getBitmap()` does not
 192 copy the bitmap data, so you have to use the returned Buffer immediately in
 193 current event loop tick, otherwise the data might be changed or destroyed.
 194
 195 #### `image.getNativeHandle()` _macOS_
 196
 197 Returns `Buffer` - A [Buffer][buffer] that stores C pointer to underlying native handle of
 198 the image. On macOS, a pointer to `NSImage` instance would be returned.
 199
 200 Notice that the returned pointer is a weak pointer to the underlying native
 201 image instead of a copy, so you _must_ ensure that the associated
 202 `nativeImage` instance is kept around.
 203
 204 #### `image.isEmpty()`
 205
 206 Returns `Boolean` -  Whether the image is empty.
 207
 208 #### `image.getSize()`
 209
 210 Returns `Object`:
 211
 212 * `width` Integer
 213 * `height` Integer
 214
 215 #### `image.setTemplateImage(option)`
 216
 217 * `option` Boolean
 218
 219 Marks the image as a template image.
 220
 221 #### `image.isTemplateImage()`
 222
 223 Returns `Boolean` - Whether the image is a template image.
 224
 225 #### `image.crop(rect)`
 226
 227 * `rect` Object - The area of the image to crop
 228   * `x` Integer
 229   * `y` Integer
 230   * `width` Integer
 231   * `height` Integer
 232
 233 Returns `NativeImage` - The cropped image.
 234
 235 #### `image.resize(options)`
 236
 237 * `options` Object
 238   * `width` Integer (optional)
 239   * `height` Integer (optional)
 240   * `quality` String (optional) - The desired quality of the resize image.
 241     Possible values are `good`, `better` or `best`. The default is `best`.
 242     These values express a desired quality/speed tradeoff. They are translated
 243     into an algorithm-specific method that depends on the capabilities
 244     (CPU, GPU) of the underlying platform. It is possible for all three methods
 245     to be mapped to the same algorithm on a given platform.
 246
 247 Returns `NativeImage` - The resized image.
 248
 249 If only the `height` or the `width` are specified then the current aspect ratio
 250 will be preserved in the resized image.
 251
 252 #### `image.getAspectRatio()`
 253
 254 Returns `Float` - The image's aspect ratio.
 255
 256 [buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer