ForwardWidget Framework

ForwardWidget supports segmented Danmu loading for long videos. To implement this, declare modules in WidgetMetadata.modules with type: "danmu".

Required Module IDs:

• searchDanmu: Search for Danmu resources by title.
• getCommentsById: Fetch Danmu segment info.
• getDanmuWithSegmentTime: (Optional) Fetch Danmu for a specific timestamp.

Danmu Loading Flow:

1. Search (searchDanmu) $\rightarrow$ 2. Fetch Segments (getCommentsById) $\rightarrow$ 3. Match Time (getDanmuWithSegmentTime).

Supported Response Formats:

Format 1 (Object-based):

[
  { p: "time/pos/color", m: "content", cid: "id" }
]

Format 2 (Array-based):

[
  [0, "position", "#color", "", "content"]
]

// Module configuration
modules: [
  {
    id: "searchDanmu",
    title: "搜索弹幕",
    functionName: "searchDanmu",
    type: "danmu",
    params: []
  },
  {
    id: "getComments",
    title: "获取弹幕",
    functionName: "getCommentsById",
    type: "danmu",
    params: []
  }
]

Widgets typically consist of a list module and a detail module.

List Modules Declared in WidgetMetadata.modules. The handler function must return an array of VideoItem objects. When a user clicks a category or person in a detail view, the client returns to the list module and passes the relevant ID in params (e.g., params.genreId or params.peopleId).

Detail Modules loadDetail(link) is a top-level function (not inside modules). It is called by the client using the link property of a VideoItem. It is used to fetch supplementary data like trailers, cast, or related items. It should return the same VideoItem model, potentially with additional fields.

Forward Resource Matching If an item represents a stable Forward cloud drive resource, set type: "forward" and use the same ID for both id and link. The client will automatically normalize the ID to fw-<id> for resource matching.

// List module example
async function loadList(params) {
  return [{
    id: 550,
    type: "tmdb",
    title: "Fight Club",
    mediaType: "movie",
  }];
}

// Detail module example
async function loadDetail(link) {
  // Returns supplementary data for the item at 'link'
  return { id: "550", type: "tmdb", title: "Fight Club", ... };
}

Every Widget script must begin with a WidgetMetadata object. This object defines the widget's identity, versioning, and its functional modules (which contain the actual logic).

Key fields include:

• id: A unique identifier for the widget.
• modules: An array of module objects. Each module defines a functionName (the handler), params (user-configurable settings), and cacheDuration.
• search: (Optional) Configuration for search functionality, including a functionName and params array.
• detailCacheDuration: How long to cache detail data (in seconds).

var WidgetMetadata = {
    id: "unique_id",
    title: "Widget Title",
    description: "Description",
    author: "Author Name",
    site: "https://example.com",
    version: "1.0.0",
    requiredVersion: "0.0.1",
    detailCacheDuration: 60,
    modules: [
        {
            title: "Module Title",
            description: "Description",
            requiresWebView: false,
            functionName: "functionName",
            sectionMode: false,
            cacheDuration: 3600,
            params: [
                {
                    name: "paramName",
                    title: "Param Title",
                    type: "input", // input | constant | enumeration | count | page | offset
                    description: "Description",
                    value: "defaultValue",
                    belongTo: {
                        paramName: "param name",
                        value: ["value"]
                    },
                    placeholders: [
                        { title: "Option Title", value: "optionValue" }
                    ],
                    enumOptions: [
                        { title: "Option Title", value: "optionValue" }
                    ]
                }
            ]
        }
    ],
    search: {
        title: "Search",
        functionName: "search",
        params: []
    }
};

If a subtitle is provided as a .zip archive, the client will download and extract it. To select the best subtitle from the extracted files, define a top-level function resolveSubtitleArchive(params). This function is called before the subtitle is used.

Available params:

• archiveName: Filename of the archive.
• archiveUrl: Download URL.
• subtitleId / subtitleName / subtitleLanguage: Current subtitle context.
• files: JSON string of all extracted files.
• subtitleFiles: JSON string of files supported by the client.

File Object Structure (inside files):

• path: The relative path within the archive (e.g., Season 1/E02.zh.ass). Use this value for the return.
• name: Filename.
• extension: Lowercase extension.
• size: File size.

Return Value: A relative path string, a string array, or an object { path: "..." }.

async function resolveSubtitleArchive(params) {
  const subtitleFiles = JSON.parse(params.subtitleFiles || "[]");
  // Find the first subtitle containing "简体" (Simplified Chinese)
  const best = subtitleFiles.find(file => file.name.includes("简体")) || subtitleFiles[0];
  return best ? best.path : null;
}

Each module in WidgetMetadata.modules must implement a handler function whose name matches the functionName property. The handler is an async function that receives a params object containing all configured parameter values.

Standard workflow inside a handler:

1. Validate required parameters.
2. Perform network requests using Widget.http.
3. Parse response data using Widget.dom.
4. Return an array of objects matching the VideoItem data model.

async function functionName(params = {}) {
  try {
    if (!params.requiredParam) {
      throw new Error("缺少必要参数");
    }

    const response = await Widget.http.get(url, {
      headers: {
        "User-Agent": "Mozilla/5.0 ...",
        Referer: "https://example.com",
      },
    });

    const docId = Widget.dom.parse(response.data);
    const elements = Widget.dom.select(docId, "selector");

    return elements.map((element) => ({
      id: "unique_id",
      type: "type",
      title: "title",
      coverUrl: "url",
    }));
  } catch (error) {
    console.error("处理失败:", error);
    throw error;
  }
}