AliPlayerKit iOS scene types - ApsaraVideo VOD: Central de Documentação do Alibaba Cloud

Introdução

O que é SceneType?

SceneType é uma enumeração que define o cenário de negócio atual do player. Ao configurar o SceneType, o AliPlayerKit automaticamente:

Ajusta a visibilidade dos slots, como ocultar a miniatura em um cenário de transmissão ao vivo.
Filtra gestos, desativando a busca na barra de progresso e o ajuste de velocidade de reprodução em cenários ao vivo ou restritos, ou desabilitando gestos verticais em listas de vídeos.
Adapta-se a limitações de recursos, garantindo, por exemplo, que os usuários assistam ao conteúdo integralmente e em ordem em um cenário restrito.

Basta definir um valor de enumeração para que o framework gerencie essas adaptações automaticamente. Isso reduz significativamente o esforço necessário para personalizar o player para diferentes cenários de negócio.

Valor principal

Valor	Descrição
Adaptação sem configuração	Após definir uma cena, a UI e os comportamentos interativos se ajustam automaticamente. Não há necessidade de configurar cada slot e gesto individualmente.
Garantia de consistência	Todas as instâncias do player no mesmo cenário mantêm uma UI e um comportamento interativo consistentes.
Redução do custo de personalização	Substitua dezenas de linhas de código de visibilidade de slots e filtragem de gestos por uma única linha de código.
Escalabilidade	Faça ajustes finos adicionais usando SlotConfig e GestureControlSlotConfig.

Recursos

Visão geral dos cenários

O AliPlayerKit possui cinco tipos de cena integrados que cobrem a maioria dos requisitos de reprodução:

Cenário	Valor da enumeração	Descrição	Negócio aplicável	Diferenças em relação ao VOD
VOD	`SceneTypeVOD`	Cenário padrão. Suporta todas as capacidades de controle.	VOD padrão, cursos, Media Library	—
Live	`SceneTypeLive`	Stream em tempo real sem duração fixa. Operações na linha do tempo são desativadas automaticamente.	Transmissão ao vivo, eventos esportivos, E-commerce live streaming	Desativa a busca na barra de progresso e o ajuste de velocidade de reprodução. Oculta a miniatura.
Video List	`SceneTypeVideoList`	Desativa gestos verticais para evitar conflitos com a rolagem da lista.	Feeds, listas de vídeos curtos	Desativa gestos verticais de volume e brilho.
Restricted Playback	`SceneTypeRestricted`	Impede avanços para garantir que os usuários assistam a todo o vídeo.	Monitoramento de exames, cursos de treinamento	Desativa a busca na barra de progresso e o ajuste de velocidade de reprodução. Oculta a miniatura.
Minimal	`SceneTypeMinimal`	Interface limpa. Todos os controles devem ser implementados separadamente.	Reprodução em segundo plano, UI totalmente personalizada	Oculta todos os componentes de controle e gestos.

Definição da enumeração

// SceneType.h
typedef NS_ENUM(NSInteger, SceneType) {
    /** VOD scenario (default) */
    SceneTypeVOD = 0,

    /** Live streaming scenario */
    SceneTypeLive = 1,

    /** Video list or short video stream scenario */
    SceneTypeVideoList = 2,

    /** Restricted playback scenario */
    SceneTypeRestricted = 3,

    /** Minimal playback page scenario */
    SceneTypeMinimal = 4,
};

Matriz de capacidades dos cenários

Visibilidade dos slots

O sistema de slots controla automaticamente a visibilidade dos componentes com base no tipo de cena. A matriz a seguir mostra as regras padrão de DefaultSlotFactory.defaultConfigs:

Slot	VOD	Live	VideoList	Restricted	Minimal
PlayerSurface	✓	✓	✓	✓	✓
GestureControl	✓	✓	✓	✓	✗
LandscapeHint	✓	✓	✓	✓	✗
Cover	✓	✗	✓	✗	✗
CenterDisplay	✓	✓	✓	✓	✗
PlayState	✓	✓	✓	✓	✓
LogPanel	✓	✓	✓	✓	✗
TopBar	✓	✓	✓	✓	✗
BottomBar	✓	✓	✓	✓	✗
SettingMenu	✓	✓	✓	✓	✗
OptionPanel	✓	✓	✓	✓	✗

Descrições das regras de visibilidade:

PlayerSurface e PlayState: Visíveis em todos os cenários (sem configuração de excludedScenes).
Cover: Não visível nos cenários Live, Restricted ou Minimal.
Demais slots (GestureControl, LandscapeHint, CenterDisplay, LogPanel, TopBar, BottomBar, SettingMenu, OptionPanel): Não visíveis apenas no cenário Minimal.

Diferenças no comportamento dos gestos

O GestureControlSlot filtra internamente os gestos em cada método de tratamento com base no currentSceneType:

Gesto	VOD	Live	VideoList	Restricted	Minimal
Clique (Mostrar/Ocultar barra de controle)	✓	✓	✓	✓	✗
Clique duplo (Reproduzir/Pausar)	✓	✓	✓	✓	✗
Pressionar e segurar (Avanço rápido)	✓	✗	✓	✗	✗
Arrastar horizontalmente (Buscar progresso)	✓	✗	✓	✗	✗
Arrastar verticalmente à esquerda (Brilho)	✓	✓	✗	✓	✗
Arrastar verticalmente à direita (Volume)	✓	✓	✗	✓	✗

Descrições da lógica de filtro:

Minimal: Todos os métodos de tratamento de gestos (handleSingleTap:, handleDoubleTap:, handleLongPress: e handlePan:) executam return imediatamente no ponto de entrada.
Live / Restricted: Os gestos de pressionar e segurar e arrastar horizontalmente são desativados. Essa verificação ocorre em handleLongPress: e tryStartDragWithCurrentPoint:.
VideoList: O arrasto vertical é desativado. O método tryStartDragWithCurrentPoint: executa return imediatamente ao detectar SceneTypeVideoList.

Uso

Uso básico

Especifique o tipo de cena usando a propriedade AliPlayerModel.sceneType. O padrão é SceneTypeVOD, portanto não é necessário defini-lo explicitamente.

Cenário VOD (padrão, sem configuração necessária):

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
// model.sceneType defaults to SceneTypeVOD, no setup required

[controller configure:model];

Cenário de transmissão ao vivo:

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://live.example.com/stream.m3u8"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeLive;
model.videoTitle = @"Live Channel";

[controller configure:model];

Cenário de lista de vídeos:

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://live.example.com/stream.m3u8"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeLive;
model.videoTitle = @"live channel";

[controller configure:model];

Descrição detalhada de cada cenário

VOD - Cenário VOD (padrão)

Cenários: Reprodução de vídeo padrão, cursos online, navegação na Media Library, entre outros.

Capacidades:

Suporta todos os 11 slots padrão
Suporta todos os 6 gestos
Permite busca na barra de progresso, ajuste de velocidade de reprodução e troca de resolução
Permite alternância para tela cheia

// No need to explicitly specify SceneType, the default is VOD
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.coverUrl = @"https://example.com/cover.jpg";
model.videoTitle = @"Great Video";
model.autoPlay = YES;

[controller configure:model];

Live - Cenário de transmissão ao vivo

Cenários: Transmissões ao vivo em tempo real, eventos esportivos, E-commerce live streaming, entre outros.

Principais diferenças em relação ao VOD:

Desativado: Busca na barra de progresso (gesto horizontal) e ajuste de velocidade de reprodução (gesto de pressionar e segurar), pois streams ao vivo não têm duração fixa.
Oculto: Slot de miniatura, já que streams ao vivo não precisam de miniatura.
Mantido: Gestos de clique/clique duplo e ajuste de volume/brilho.

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:liveSource];
model.sceneType = SceneTypeLive;
model.videoTitle = @"Popular Live Stream";
model.autoPlay = YES;

[controller configure:model];

VideoList - Cenário de lista de vídeos

Cenários: Vídeos incorporados em feeds, listas de vídeos curtos, coleções de vídeos com rolagem, entre outros.

Principais diferenças em relação ao VOD:

Desativado: Gestos de arrasto vertical para evitar conflitos com a rolagem da UIScrollView da lista.
Mantido: Todos os demais recursos, como busca na barra de progresso, ajuste de velocidade de reprodução e gestos de clique/clique duplo/pressionar e segurar.

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeVideoList;
model.autoPlay = YES;

[controller configure:model];

Restricted - Cenário de reprodução restrita

Cenários: Vídeos de monitoramento de exames online, cursos de treinamento e certificação, cenários de proteção de direitos autorais, entre outros.

Principais diferenças em relação ao VOD:

Desativado: Busca na barra de progresso (gesto horizontal) e ajuste de velocidade de reprodução (gesto de pressionar e segurar) para garantir que os usuários assistam ao conteúdo integralmente e em ordem.
Oculto: Slot de miniatura.
Mantido: Gestos de clique/clique duplo e ajuste de volume/brilho.

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeRestricted;
model.videoTitle = @"Security Training Course";
model.autoPlay = YES;
// Usually used with screenshot prevention
model.disableScreenshot = YES;

[controller configure:model];

Minimal - Modo mínimo

Cenários: Reprodução em segundo plano, UI totalmente personalizada, reprodução de miniaturas de pré-visualização, entre outros.

Principais diferenças em relação ao VOD:

Oculto: Quase todos os slots de controle da UI. Apenas PlayerSurface e PlayState são mantidos.
Desativado: Todos os gestos. O slot GestureControl não fica visível no cenário Minimal, e seus métodos internos de tratamento de gestos executam return imediatamente.
Casos de uso: Cenários que exigem uma UI de controle de reprodução totalmente personalizada.

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;

[controller configure:model];
// All controls must be implemented using the controller's API
// For example: [controller play]; [controller pause]; [controller seekTo:position];

Desenvolvimento personalizado

Ajuste fino da visibilidade dos slots

Se a visibilidade predefinida dos slots para um cenário não atender aos seus requisitos, faça ajustes finos usando SlotConfig:

// Example: Hide the TopBar in the Live scenario
SlotConfig *topBarConfig = [SlotConfig configWithSlotType:SlotTypeTopBar
                                           excludedScenes:[NSSet setWithObjects:
                                               @(SceneTypeMinimal),
                                               @(SceneTypeLive), nil]];

// Register with SlotManager (overwrites the default SlotConfig for this slot type)
[playerView.slotManager registerSlotConfig:topBarConfig];

Também é possível ocultar um slot inteiro diretamente usando hideSlot:. Este método não depende do cenário:

// Unconditionally hide the TopBar (requires calling rebuildSlots to take effect)
[playerView.slotManager hideSlot:SlotTypeTopBar];

Nota

registerSlotConfig: fornece controle de visibilidade no nível da cena, enquanto hideSlot: fornece controle de visibilidade no nível do slot. Eles funcionam de forma independente. Um slot só é criado se passar por ambas as verificações.

Ajuste fino do comportamento dos gestos

O controle de gestos suporta dois métodos para ajustes finos:

Método 1: Desative gestos específicos usando a API de máscara de bits de elementos do SlotManager. Este é o método recomendado. Configure-o antes da chamada attach.

// Disable long press for fast-forward in the VOD scenario
[playerView.slotManager hideElements:GestureElementLongPress
                             forSlot:SlotTypeGestureControl];

Método 2: Controle os gestos diretamente usando GestureControlSlotConfig. Recupere a instância do slot após a chamada attach:

// Get the gesture control slot instance
GestureControlSlot *gestureSlot = (GestureControlSlot *)[playerView.slotManager slotViewForType:SlotTypeGestureControl];

// Modify the configuration (takes effect immediately)
GestureControlSlotConfig *config = [GestureControlSlotConfig defaultConfig];
config.longPressEnabled = NO;
config.horizontalDragEnabled = NO;
gestureSlot.config = config;

Nota

Os dois métodos funcionam de forma independente. A máscara de bits de elementos é aplicada quando o slot é criado (durante a fase setupContentView). O GestureControlSlotConfig entra em vigor dinamicamente em tempo de execução.

Registro de slots personalizados no cenário Minimal

No cenário Minimal, a configuração da cena exclui a maioria dos slots padrão. Para restaurar um slot, substitua seu SlotConfig:

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;

// Override the scene configuration for BottomBar to remove the Minimal exclusion rule
[playerView.slotManager registerSlotConfig:
    [SlotConfig configWithSlotType:SlotTypeBottomBar]]; // No excludedScenes = visible in all scenarios

[controller configure:model];

Condições dinâmicas de visibilidade

Use o callback SlotConfig visibilityCondition para implementar controle dinâmico em tempo de execução:

SlotConfig *coverConfig = [SlotConfig configWithSlotType:SlotTypeCover
                                          excludedScenes:nil
                                     visibilityCondition:^BOOL{
    // Show the cover slot only if a cover URL exists
    return model.coverUrl != nil;
}];

[playerView.slotManager registerSlotConfig:coverConfig];

Nota

O método isVisibleInScene: verifica primeiro excludedScenes. Se houver correspondência, o slot não ficará visível. Em seguida, o método verifica visibilityCondition. Se este callback retornar NO, o slot não ficará visível. Um slot só é visível se passar por ambas as verificações.

Guia de seleção de cena

Fluxo de decisão

Do you need a player control UI?
├── No → SceneTypeMinimal
└── Yes → Is it a live stream?
         ├── Yes → SceneTypeLive
         └── No → Is the player embedded in a scrollable list?
                   ├── Yes → SceneTypeVideoList
                   └── No → Do you need to prevent users from skipping?
                             ├── Yes → SceneTypeRestricted
                             └── No → SceneTypeVOD (default)

Tabela resumida de seleção de cena

Requisito de negócio	Cenário recomendado	Principais motivos
Reprodução de vídeo padrão	`SceneTypeVOD`	Cenário padrão, suporte completo a recursos
Transmissão ao vivo / Evento esportivo em tempo real	`SceneTypeLive`	Desativa automaticamente operações de progresso não aplicáveis
Vídeo incorporado em UIScrollView	`SceneTypeVideoList`	Evita automaticamente conflitos de gestos verticais
Treinamento / Exame / Proteção de direitos autorais	`SceneTypeRestricted`	Desativa automaticamente avanços e ajuste de velocidade de reprodução
UI totalmente personalizada	`SceneTypeMinimal`	Tela limpa sem interferência de UI integrada
Reprodução em segundo plano / Picture-in-Picture (PiP)	`SceneTypeMinimal`	Nenhum componente de controle de UI necessário

Referência rápida da API

Enumeração SceneType

Valor da enumeração	Valor inteiro	Descrição
`SceneTypeVOD`	0	Cenário VOD (padrão)
`SceneTypeLive`	1	Cenário de transmissão ao vivo
`SceneTypeVideoList`	2	Cenário de lista de vídeos/stream de vídeos curtos
`SceneTypeRestricted`	3	Cenário de reprodução restrita
`SceneTypeMinimal`	4	Cenário de página de reprodução mínima

SlotConfig

Método / Propriedade	Descrição
`configWithSlotType:`	Cria uma configuração sem cenas excluídas (visível em todos os cenários)
`configWithSlotType:excludedScenes:`	Cria uma configuração com cenas excluídas especificadas
`configWithSlotType:excludedScenes:visibilityCondition:`	Cria uma configuração com cenas excluídas e uma condição dinâmica
`slotType`	Tipo de slot (`readonly`)
`excludedScenes`	Conjunto de cenas excluídas, `NSSet<NSNumber *>` (`readonly`, nullable)
`visibilityCondition`	Bloco de condição de visibilidade dinâmica (`readonly`, nullable)
`isVisibleInScene:`	Verifica se o slot está visível em um cenário especificado

GestureControlSlotConfig

Propriedade	Tipo	Valor padrão	Descrição
`singleTapEnabled`	`BOOL`	`YES`	Ativa ou desativa o gesto de clique
`doubleTapEnabled`	`BOOL`	`YES`	Ativa ou desativa o gesto de clique duplo
`longPressEnabled`	`BOOL`	`YES`	Ativa ou desativa o gesto de pressionar e segurar
`horizontalDragEnabled`	`BOOL`	`YES`	Ativa ou desativa o gesto de arrastar horizontalmente
`leftVerticalDragEnabled`	`BOOL`	`YES`	Ativa ou desativa o gesto de arrastar verticalmente à esquerda
`rightVerticalDragEnabled`	`BOOL`	`YES`	Ativa ou desativa o gesto de arrastar verticalmente à direita
`+defaultConfig`	Método de classe	—	Cria uma configuração padrão com todos os gestos ativados

APIs relacionadas a cenários do SlotManager

Método	Descrição
`registerSlotConfig:`	Registra uma configuração de visibilidade de cena para um tipo de slot (substitui a configuração padrão)
`unregisterSlotConfigForType:`	Remove a configuração de cena para um tipo de slot especificado (torna-se visível por padrão após a remoção)
`slotConfigForType:`	Obtém a configuração de visibilidade de cena para um tipo de slot especificado
`hideSlot:`	Oculta um slot especificado (nível de slot, independente da configuração de cena)
`showSlot:`	Mostra um slot previamente oculto
`hideElements:forSlot:`	Oculta elementos dentro de um slot ou desativa gestos usando uma máscara de bits
`showElements:forSlot:`	Mostra elementos dentro de um slot ou ativa gestos usando uma máscara de bits
`slotViewForType:`	Obtém a instância de visualização de um slot montado
`rebuildSlots`	Reconstrói todos os slots (deve ser chamado após uma alteração na configuração de cena)

Arquivos relacionados

Arquivo	Descrição
`PlayerKit/Source/Data/SceneType.h`	Definição da enumeração SceneType
`PlayerKit/Source/AliPlayerModel.h`	Ponto de entrada para definir o tipo de cena (propriedade `sceneType`)
`PlayerKit/Source/Slot/SlotConfig.h`	Configuração de visibilidade de slots
`PlayerKit/Source/Slot/DefaultSlotFactory.h`	Provedor padrão de slots e regras de visibilidade de cena
`PlayerKit/Source/Slot/SlotManager.h`	Ponto de entrada unificado para gerenciamento do sistema de slots
`PlayerKit/Source/Slot/SlotElements.h`	Definições de máscara de bits de elementos de gestos
`PlayerKit/Source/UI/Slots/GestureControlSlot.h`	Slot de controle de gestos e definição de `GestureControlSlotConfig`
`PlayerKit/Source/Slot/BaseSlot.h`	Classe base de slots (método `currentSceneType`)

Para mais informações, consulte API Reference.

Melhores práticas

Observações

Item	Descrição
Definir na criação	Especifique o SceneType ao criar o `AliPlayerModel`. Não o alterne dinamicamente durante a reprodução.
Priorizar o cenário de lista	Sempre use `SceneTypeVideoList` ao incorporar o player em uma `UIScrollView` ou `UICollectionView`.
Minimal exige controle manual	Após selecionar Minimal, o desenvolvedor deve implementar todos os controles de reprodução usando a API do `AliPlayerController`.
Ajuste fino combinável	Caso o comportamento predefinido não atenda totalmente às suas necessidades, faça ajustes adicionais usando `SlotConfig` e `SlotManager`.
Live e Restricted têm comportamento semelhante	Suas regras de filtragem de gestos são idênticas (desativam busca na barra de progresso e ajuste de velocidade de reprodução). As diferenças residem apenas na visibilidade da miniatura (oculta em ambos) e na semântica de negócio.

FAQ

A principal diferença reside nos gestos verticais. O SceneTypeVideoList desativa gestos verticais de volume e brilho para evitar conflitos com o gesto de rolagem do contêiner da lista. Os demais recursos são iguais aos do VOD.

Como implementar controles personalizados no cenário Minimal?

Controle o comportamento de reprodução diretamente pela API do AliPlayerController. Também é possível registrar slots personalizados para substituir a UI:

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;
[controller configure:model];

// Control directly through the controller API
[controller play];
[controller pause];
[controller seekTo:30000]; // Seek to 30 seconds

Como restaurar a busca na barra de progresso em um cenário Live?

Se o seu cenário de transmissão ao vivo suportar timeshifting, restaure o gesto desativado usando a API de controle de elementos do SlotManager:

// Restore the horizontal drag gesture (progress seeking)
[playerView.slotManager showElements:GestureElementHorizontalDrag
                             forSlot:SlotTypeGestureControl];

Nota

Este método restaura apenas a visibilidade no nível do elemento. A lógica de filtragem de cena dentro do GestureControlSlot é codificada rigidamente e não pode ser ignorada usando showElements:. Para personalizar totalmente o comportamento dos gestos, use GestureControlSlotConfig ou substitua o GestureControlSlot.

Introdução

O que é SceneType?

Valor principal

Recursos

Visão geral dos cenários

Definição da enumeração

Matriz de capacidades dos cenários

Visibilidade dos slots

Diferenças no comportamento dos gestos

Uso

Uso básico

Descrição detalhada de cada cenário

VOD - Cenário VOD (padrão)

Live - Cenário de transmissão ao vivo

VideoList - Cenário de lista de vídeos

Restricted - Cenário de reprodução restrita

Minimal - Modo mínimo

Desenvolvimento personalizado

Ajuste fino da visibilidade dos slots

Ajuste fino do comportamento dos gestos

Registro de slots personalizados no cenário Minimal

Condições dinâmicas de visibilidade

Guia de seleção de cena

Fluxo de decisão

Tabela resumida de seleção de cena

Referência rápida da API

Enumeração SceneType

SlotConfig

GestureControlSlotConfig

APIs relacionadas a cenários do SlotManager

Arquivos relacionados

Melhores práticas

Observações

FAQ

Qual é a diferença entre VOD e VideoList?

Como implementar controles personalizados no cenário Minimal?

Como restaurar a busca na barra de progresso em um cenário Live?