Skip to content

Latest commit

 

History

History
369 lines (252 loc) · 8.12 KB

app-context.md

File metadata and controls

369 lines (252 loc) · 8.12 KB

AppContext

AppContext is the context passed in when the plugin runs. You can operate the ui of the APP through this object, get the status of the current room, and subscribe to the status change.

API

  • context.appId

    Unique ID generated when inserting app

    const appId = context.appId;

  • context.isReplay

    Type: boolean

    Whether the current playback mode

  • context.getDisplayer()

    By default Displayer is the room instance of the whiteboard

    A Player instance during playback

    const displayer = context.getDisplayer();

assert(displayer, room); // interactive room
assert(displayer, player); // playback room

  • context.getIsWritable()

    Get whether the current state is writable
    You can get the change of writable state by listening to writableChange event

    const isWritable = context.getIsWritable();

  • context.getBox()

    Get the box of the current app

    const box = context.getBox();

box.$content; // main element of the box
box.$footer;

Mount whiteboard

When the application wants a whiteboard that can be drawn on, the following interface can be used

  • context.mountView()

    Mount the whiteboard to the specified dom

    context.mountView(element);

Note When calling addApp of manager, you must fill in scenePath to use view

manager.addApp({
     kind: "xxx",
     options: { // optional configuration
         scenePath: "/example-path"
     }
})

Page

The whiteboard has the concept of multiple pages, which can be added, switched, and deleted through the following interfaces

  • context.addPage()

    Add a page to view

    context.addPage() // add a page at the end by default
context.addPage({ after: true }) // add a page after the current page
context.addPage({ scene: { name: "page2" } }) // pass in page information

  • context.nextPage()

    previous page

    context.nextPage();

  • context.prevPage()

    next page

    context.prevPage();

  • context.removePage()

    delete a page

    context.removePage() // delete the current page by default
context.removePage(1) // You can also specify index to delete

  • context.pageState

    Get the current index and how many pages there are
    When you want to monitor the change of pageState, you can listen to the pageStateChange event to get the latest pageState

    context.pageState;
// {
//    index: number,
//    length: number,
// }

storage

Store and synchronize state, and send a collection of events

  • context.storage

    Storage instance created by default

    context.storage

  • context.createStorage(namespace)

    At the same time you can also create multiple storage instances

    Returns: Storage<State>

    type State = { count: number };
const defaultState = { count: 0 };
const storage = context.createStorage<State>("store1", defaultState);

  • storage.state

    Type: State
    Default: defaultState

    State synchronized between all clients, call storage.setState() to change it.

  • storage.ensureState(partialState)

    Make sure storage.state contains some initial values, something like doing:

    // This code cannot be run directly because app.state is read-only
storage.state = { ...partialState, ...storage.state };

    partialState

    Type: Partial<State>

    storage.state; // { a: 1 }
storage.ensureState({ a: 0, b: 0 });
storage.state; // { a: 1, b: 0 }

  • storage.setState(partialState)

    Similar to React's setState, update storage.state and sync to all clients.

    When setting a field to undefined, it will be removed from storage.state.

    The time required for state synchronization and the network state are related to the data size. It is recommended to only store necessary data in the state.

    partialState

    Type: Partial<State>

    storage.state; //=> { count: 0, a: 1 }
storage.setState({ count: storage.state.count + 1, b: 2 });
storage.state; //=> { count: 1, a: 1, b: 2 }

  • storage.addStateChangedListener(listener)

    It fires after someone calls storage.setState() (including the current storage)

    return: () => void

    const disposer = storage.addStateChangedListener(diff => {
  console.log("state changed", diff.oldValue, diff.newValue);
  disposer(); // remove listener by calling disposer
});

  • context.dispatchMagixEvent(event, payload)

    Broadcast event messages to other clients

    context.dispatchMagixEvent("click", { data: "data" });

  • context.addMagixEventListener(event, listener)

    It is triggered when receiving messages from other clients (when other clients call context.dispatchMagixEvent())

    Returns: () => void a disposer function.

    const disposer = context.addMagixEventListener("click", ({ payload }) => {
  console.log(payload.data);
  disposer();
});

context.dispatchMagixEvent("click", { data: "data" });

UI (box)

Box is the default UI created by whiteboard for all apps. All operable UI parts of the application are within the bounds of the box.

  • context.getBox()

    get box Return type: ReadonlyTeleBox

  • box.mountStyles()

    Mount styles to box Parameters: string | HTMLStyleElement

    const box = context. getBox();
box. mountStyles(`
    .app-span {
        color: red;
    }
`)

  • box.mountContent()

    Mount element to box Parameters: HTMLElement

    const box = context. getBox();
const content = document. createElement("div");
box. mountContent(context);

  • box.mountFooter()

    Mount element to footer of box Parameters: HTMLElement

    const box = context. getBox();
const footer = document. createElement("div");
box. mountFooter(context);

events

  • destroy

    Sent when the app is closed

    context.emitter.on("destroy", () => {
    // release your listeners
});

  • writableChange

    Triggered when the whiteboard's writable state is switched

    context.emitter.on("writableChange", isWritable => {
    //
});

  • focus

    Triggered when the current app gains or loses focus

    context.emitter.on("focus", focus => {
    //
});

  • pageStateChange

    PageState

    type PateState {
    index: number;
    length: number;
}

    Triggered when the current page number and the total page number change

    context.emitter.on("pageStateChange", pageState => {
    // { index: 0, length: 1 }
});

  • roomStageChange

    Triggered when the state of the room changes
    For example, when teaching aids are switched

    context.emitter.on("roomStageChange", stage => {
    if (state. memberState) {
        console.log("appliance change to", state.memberState.currentApplianceName);
    }
});

    or when the number of people in the current room changes

     context.emitter.on("roomStageChange", stage => {
    if (state. roomMembers) {
        console.log("current room members change", state.roomMembers);
    }
});

    For detailed status introduction, please refer to https://developer.netless.link/javascript-zh/home/business-state-management

Advanced

  • context.getView()

    Get view instance

    const view = context.getView();