Torch

Фонарик телефона — светодиод рядом с задней камерой, зажжённый как лампа: включить и выключить, задать яркость, узнать, есть ли он у устройства. Из плагина torch; разрешение не нужно. Свет в 3D-сцене (фонарик игрока, фары машины) — это Light.spot() (light.md).

  • включать и выключать фонарик телефона кнопкой
  • задать яркость фонарика
  • спрятать кнопку фонарика на устройстве, где его нет (Torch.available())
  • показать, что фонарик погас, когда его выключила система или другое приложение (Torch.onChange)
  • объяснить пользователю, почему фонарик не зажёгся
  • выключить фонарик, когда закрывается экран

Платформы: iOS, Android; не в вебе, не в веб-плеере, не на десктопе и не в headless-тестах — проверяй Torch.supported.

Обзор

TypeScript
// app.json: "plugins": { "torch": "*" }
const lit = signal(false)
const hasTorch = signal(false)

Torch.available().then(yes => { hasTorch.value = yes })    // false в вебе, в симуляторе iOS, на большинстве планшетов
Torch.onChange(state => { lit.value = state.on })           // его изменила система или другое приложение

const toggle = async () => {
  try {
    lit.value = (await Torch.toggle()).on
  } catch (e) {
    toast(e.message === 'busy' ? 'The camera is using the flashlight' : 'The flashlight is not available')
  }
}

Router.init(UIScreen(
  UIColumn(() => [hasTorch.value
    ? UIButton(UIText(() => (lit.value ? 'Flashlight off' : 'Flashlight on')).style({ color: 'white' })).onClick(toggle)
    : UIText('This device has no flashlight').style({ color: 'gray' })]),
).style({ bgColor: 'black', p: 20, pt: 'safe-top', gap: 16 }))

Подключить плагин фонарика к приложению: app.json

Фонарик — это плагин torch: перечисли его в app.json проекта — "plugins": { "torch": "*" }. Список один на все платформы: плагина, которого в нём нет, нет и в приложении, а компиляция предупреждает о плагине, который приложение использует, но не перечислило. В приложении-вьюере le.codes плагин есть, что бы ни было в списке. Ни разрешения, ни строки с описанием: чтобы зажечь фонарик, камеру не открывают ни на одной платформе. На Android вспышка объявлена необязательной, так что приложение ставится и на устройство без неё.

Включить и выключить фонарик: Torch.set, Torch.toggle

TypeScript
Torch.set(on: boolean, level?: number): Promise<TorchState>   // level 0..1, ограничивается; 0 = выкл.; без него — умолчание платформы
Torch.toggle(): Promise<TorchState>                           // выкл. → вкл. с уровнем, с которым приложение зажигало его в последний раз; вкл. → выкл.
Torch.state(): Promise<TorchState>                            // никогда не отклоняется; выключен, где фонарика нет

interface TorchState { on: boolean, level: number }           // level (0, 1], пока горит (1 у фонарика без регулировки), 0 — когда выключен

Оба резолвятся состоянием, в котором фонарик оказался после вызова. set(false) выключает его при любом уровне. state() спрашивает устройство: фонарик мог измениться с тех пор, как приложение задало его в последний раз.

TypeScript
const lightUp = async () => {
  const state = await Torch.set(true)              // полная яркость на iOS, яркость вспышки по умолчанию на Android
  console.log(state.on, state.level)
}
const lightDown = () => Torch.set(false)

Задать яркость фонарика: level, info().dimmable

TypeScript
Torch.info(): Promise<TorchInfo>                   // никогда не отклоняется

interface TorchInfo {
  available: boolean                               // у устройства есть фонарик, который приложение может зажечь
  dimmable: boolean                                // его яркость можно задать
}

Уровень — доля полной яркости. iOS регулирует плавно, и нагретый светодиод даёт меньше, чем попросили, — состояние говорит, сколько он взял. Android 13+ регулирует ступенями силы, которые есть у его вспышки, если их несколько, и состояние сообщает ступень, на которую он встал. Любое другое устройство светит своей единственной яркостью и сообщает level: 1; info().dimmable там false.

TypeScript
const level = signal(1)

const brightness = async (wanted: number) => {
  const { dimmable } = await Torch.info()
  if (!dimmable) return                                    // одна яркость: только вкл. или выкл.
  level.value = (await Torch.set(true, wanted)).level      // что фонарик взял: нагретый светодиод, ступень Android
}

UIRow(
  UIButton(UIText('Dim')).onClick(() => brightness(0.25)),
  UIButton(UIText('Bright')).onClick(() => brightness(1)),
).style({ gap: 12 })

Спрятать кнопку фонарика, где его нет: Torch.supported, Torch.available()

TypeScript
Torch.supported: boolean                 // этот хост зарегистрировал сервис "torch"
Torch.available(): Promise<boolean>      // у устройства есть фонарик, который приложение может зажечь; никогда не отклоняется

supported равен false в вебе, в веб-плеере, в headless-тестах, на десктопе и в оболочке, собранной без плагина. available() там тоже false, а ещё в симуляторе iOS и на большинстве планшетов — его и спрашивай, прежде чем показывать кнопку. На хосте без сервиса info(), available() и state() отвечают «фонарика нет, выключен», а set() / toggle() отклоняются с "unavailable" — тем же кодом, который приложение и так обрабатывает для телефона без вспышки. Ничего там не бросает.

TypeScript
const hasTorch = signal(false)
Torch.available().then(yes => { hasTorch.value = yes })

UIColumn(() => [hasTorch.value
  ? UIButton(UIText('Flashlight')).onClick(() => Torch.toggle().catch(e => toast(e.message)))
  : UIText('No flashlight on this device')])

Объяснить пользователю, почему фонарик не зажёгся: коды

set() и toggle() отклоняются с кодом в e.message:

код когда
"unavailable" фонарика нет (так же на любом хосте без сервиса); iOS не даёт его зажечь, пока светодиод перегрет
"busy" Android: вспышку держит камера — другого приложения или открытая камера этого (CameraView, QRScanner)
"failed" всё остальное
TypeScript
const toggle = async () => {
  try {
    await Torch.toggle()
  } catch (e) {
    if (e.message === 'busy') toast('Close the camera to use the flashlight')
    else if (e.message === 'unavailable') toast('The flashlight is not available right now')
    else toast('The flashlight did not turn on')
  }
}

Следить за тем, что с ним делают система и другие приложения: Torch.onChange

TypeScript
Torch.onChange(listener: (state: TorchState) => void): () => void   // возвращает функцию, которая прекращает слушать

Фонарик принадлежит устройству, а не приложению: его может изменить другое приложение, камера или система — от нагрева светодиода iOS снижает уровень, а потом выключает его. onChange сообщает о каждом изменении, пока приложение слушает, в том числе о собственных set() приложения; на хосте без сервиса он не вызывается никогда. Рисуй кнопку по нему, а не по тому, что приложение попросило в последний раз.

TypeScript
const lit = signal(false)
const stop = Torch.onChange(state => { lit.value = state.on })
Torch.state().then(state => { lit.value = state.on })     // фонарик может уже гореть

Выключить фонарик, когда закрывается экран: onClose

Ничто не выключает фонарик за приложение: он горит и после того, как экрана, который его зажёг, уже нет, — пока его не выключит приложение, пользователь или система. Экран, который зажигает фонарик, выключает его, когда закрывается.

TypeScript
const screen = UIScreen(
  UIButton(UIText('Flashlight')).onClick(() => Torch.toggle().catch(e => toast(e.message))),
).onClose(() => {
  Torch.set(false).catch(() => {})                 // на хосте без фонарика выключать нечего
})

Смотрите также

  • camera-view.md — предпросмотр камеры и фото (своего управления вспышкой нет)
  • light.md — фонарик внутри 3D-сцены: Light.spot()