Torch
Фонарик телефона — светодиод рядом с задней камерой, зажжённый как лампа: включить и выключить,
задать яркость, узнать, есть ли он у устройства. Из плагина torch; разрешение не нужно. Свет в
3D-сцене (фонарик игрока, фары машины) — это Light.spot() (light.md).
- включать и выключать фонарик телефона кнопкой
- задать яркость фонарика
- спрятать кнопку фонарика на устройстве, где его нет (
Torch.available()) - показать, что фонарик погас, когда его выключила система или другое приложение (
Torch.onChange) - объяснить пользователю, почему фонарик не зажёгся
- выключить фонарик, когда закрывается экран
Платформы: iOS, Android; не в вебе, не в веб-плеере, не на десктопе и не в headless-тестах —
проверяй Torch.supported.
Обзор
// 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
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() спрашивает устройство: фонарик мог измениться с тех пор, как приложение
задало его в последний раз.
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
Torch.info(): Promise<TorchInfo> // никогда не отклоняется
interface TorchInfo {
available: boolean // у устройства есть фонарик, который приложение может зажечь
dimmable: boolean // его яркость можно задать
}Уровень — доля полной яркости. iOS регулирует плавно, и нагретый светодиод даёт меньше, чем
попросили, — состояние говорит, сколько он взял. Android 13+ регулирует ступенями силы, которые есть у
его вспышки, если их несколько, и состояние сообщает ступень, на которую он встал. Любое другое
устройство светит своей единственной яркостью и сообщает level: 1; info().dimmable там false.
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()
Torch.supported: boolean // этот хост зарегистрировал сервис "torch"
Torch.available(): Promise<boolean> // у устройства есть фонарик, который приложение может зажечь; никогда не отклоняетсяsupported равен false в вебе, в веб-плеере, в headless-тестах, на десктопе и в оболочке, собранной
без плагина. available() там тоже false, а ещё в симуляторе iOS и на большинстве планшетов — его и
спрашивай, прежде чем показывать кнопку. На хосте без сервиса info(), available() и state()
отвечают «фонарика нет, выключен», а set() / toggle() отклоняются с "unavailable" — тем же
кодом, который приложение и так обрабатывает для телефона без вспышки. Ничего там не бросает.
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" |
всё остальное |
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
Torch.onChange(listener: (state: TorchState) => void): () => void // возвращает функцию, которая прекращает слушатьФонарик принадлежит устройству, а не приложению: его может изменить другое приложение, камера или
система — от нагрева светодиода iOS снижает уровень, а потом выключает его. onChange сообщает о
каждом изменении, пока приложение слушает, в том числе о собственных set() приложения; на хосте без
сервиса он не вызывается никогда. Рисуй кнопку по нему, а не по тому, что приложение попросило в
последний раз.
const lit = signal(false)
const stop = Torch.onChange(state => { lit.value = state.on })
Torch.state().then(state => { lit.value = state.on }) // фонарик может уже горетьВыключить фонарик, когда закрывается экран: onClose
Ничто не выключает фонарик за приложение: он горит и после того, как экрана, который его зажёг, уже нет, — пока его не выключит приложение, пользователь или система. Экран, который зажигает фонарик, выключает его, когда закрывается.
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()