企业官网建设流程全解析

• 后端

ReelsTrayFeedResponseStoryPollsItem是 instagram-private-api 用来描述「Reels 故事托盘（Reels Tray）响应中，单条故事上投票贴纸（poll sticker）布局与内容」的 TypeScript 接口。本篇以该接口为骨架，完整讲解其全部属性、在响应层级中的挂载位置、配套的poll_sticker子结构，以及如何基于这些数据完成读取、渲染和投票等实战操作。读完本文，你可以准确解析feed/reels_tray/接口返回的投票贴纸数据，并与投票、拉取投票人列表等仓库内能力串起完整链路。

接口定位：它描述的是故事里的一个投票贴纸

该接口定义在 src/responses/reels-tray.feed.response.ts，是ReelsTrayFeed响应类型族中的一员。从源码结构看，整个响应按「托盘 → 用户 → 故事项 → 贴纸」的层级组织：

• 根对象 ReelsTrayFeedResponseRootObject 包含tray（各用户的托盘）、broadcasts（直播）等字段；
• 每个 ReelsTrayFeedResponseTrayItem 下挂可选的items?: ReelsTrayFeedResponseItemsItem[]，代表该用户的每条快拍故事；
• 每条故事项 ReelsTrayFeedResponseItemsItem 携带多种可选贴纸数组，其中story_polls?: ReelsTrayFeedResponseStoryPollsItem[]就是投票贴纸数组（定义位置）。

因此，ReelsTrayFeedResponseStoryPollsItem表示的是一条故事中「一个投票贴纸」的完整描述：既包含贴纸在画布上的几何摆放（坐标、尺寸、旋转、层级），也包含贴纸自身的业务数据（问题文案、各选项票数等）。

属性全解：几何字段与贴纸内容

原文档列出的全部属性如下，均已在源码中逐一确认。注意两个值得留意的类型细节：y和height声明为string而非number，这是接口对服务端真实返回值的如实映射，取值形如"0.51562500"，客户端使用前需自行Number()转换。

这些字段在源码中的逐行定义见 src/responses/reels-tray.feed.response.ts#L207-L218。

is_pinned/is_hidden/is_sticker采用「数值表示布尔」的写法并非疏漏——同一文件里的其他贴纸接口（如 ReelsTrayFeedResponseStoryQuizsItem、ReelsTrayFeedResponseStoryLocationsItem、ReelsTrayFeedResponseStoryQuestionsItem）使用了完全相同的 9 字段布局：x, y, z, width, height, rotation, is_pinned, is_hidden, is_sticker加一个专属贴纸对象。可以推断这是 Instagram 私有协议对所有「贴纸画布元素」的统一编码方式，几何字段只描述贴纸如何摆放，业务字段则由各自的*_sticker对象承载。

poll_sticker 子结构：问题与票数统计

poll_sticker的类型是 ReelsTrayFeedResponsePoll_sticker，它承载投票贴纸的实际内容：

export interface ReelsTrayFeedResponsePoll_sticker { id: string; // 贴纸实例 id poll_id: string; // 投票 id，投票与拉取投票人时作为 stickerId 使用 question: string; // 投票问题文案 tallies: ReelsTrayFeedResponseTalliesItem[]; // 各选项的统计 promotion_tallies: null; viewer_can_vote: boolean; // 当前登录用户是否还能投票 is_shared_result: boolean; // 是否已分享结果 finished: boolean; // 投票是否已结束 }

其中tallies的每一项是 ReelsTrayFeedResponseTalliesItem：text（选项文案）、count（得票数）、可选的font_size。投票贴纸通常为两项选项，因此解析时可直接按下标访问tallies[0]、tallies[1]做进度条渲染。

对照仓库内其他故事响应，同一协议字段在 MediaUpdatedMediaResponseStoryPollsItem（投票操作后的返回）中也存在，且其poll_sticker额外多了viewer_vote: number字段，用于回显当前用户投的是第几项——这为「投票后确认自己选项」提供了直接依据。

数据获取路径：从 Feed 到投票贴纸

要拿到该接口的实例，调用链如下：

1. 通过 FeedFactory 创建ReelsTrayFeed。src/core/feed.factory.ts#L161-L163 中的reelsTray(reason)接受'pull_to_refresh' | 'cold_start'两个取值，默认'cold_start'；
2. ReelsTrayFeed以 POST 方式请求/api/v1/feed/reels_tray/，表单携带supported_capabilities_new、reason、_csrftoken、_uuid，实现在 src/feeds/reels-tray.feed.ts#L17-L30；
3. items()只返回tray数组（不含 broadcasts），随后沿trayItem.items[]→story_polls[]即可定位到所有投票贴纸：

import { IgApiClient } from 'instagram-private-api'; const ig = new IgApiClient(); ig.state.generateDevice(username, password); await ig.account.login(username, password); const tray = await ig.feed.reelsTray().items(); // ReelsTrayFeedResponseTrayItem[] for (const userTray of tray) { for (const storyItem of userTray.items ?? []) { for (const poll of storyItem.story_polls ?? []) { // poll: ReelsTrayFeedResponseStoryPollsItem console.log(poll.poll_sticker.question, poll.poll_sticker.tallies); // 几何信息：画布相对坐标（y/height 为字符串，需转换） console.log({ x: poll.x, y: Number(poll.y), z: poll.z, w: poll.width, h: Number(poll.height), rotation: poll.rotation, }); } } }

需要说明的是：story_polls是可选字段（?），只有故事里确实添加了投票贴纸时才会出现；同层可选的story_quizs、story_questions、story_locations、reel_mentions等字段遵循相同的「有内容才返回」模式，健壮的消费代码应统一做空值判断。

周边能力：投票与投票人列表

拿到poll_sticker后，仓库提供了与之配套的读、写、查三类能力，可以作为该接口数据的直接消费场景：

投票（写）：MediaRepository.storyPollVote 向/api/v1/media/{mediaId}/{pollId}/story_poll_vote/发起 POST，参数为vote: '0' | '1'（对应 tallies 的两个选项下标），返回 MediaUpdatedMediaResponseRootObject。这里mediaId取故事项的pk，pollId正是poll_sticker.poll_id——两个字段恰好由本接口及其子结构提供。

拉取投票人（查）：src/core/feed.factory.ts#L256-L267 的storyPollVoters(mediaId, stickerId)构造了一个MediaStickerResponsesFeed，stickerId同样使用poll_id，其响应类型为 StoryPollVotersFeedResponseRootObject，用于查看各选项的投票人明细。

创建投票（发布侧）：若关心这些字段的写入形态，可以看仓库的 sticker-builder。StickerBuilder.poll 创建 PollSticker：其keygetter 返回'story_polls'，与响应侧数组字段名严格对应；talliessetter 会为每个选项补默认fontSize: 28.0，width/height默认值为0.49934897 / 0.1266892——这解释了为什么读侧几何值多为小数比例：贴纸尺寸本身就是「相对故事画布的宽高比」，与 StoryPoll 类型注释 中 “width & height have an aspect-ratio” 的说法一致。发布时 PublishService 会把options.poll塞进configureOptions.story_polls并附带internal_features: 'polling_sticker'，最终由 stringifyStoryStickers 序列化为 JSON 随media/configure/提交——也就是说，读接口中story_polls数组的每一项，其结构与发布侧写入的贴纸对象同源。

使用注意点与小结

• y、height为string类型是接口真实映射，做数值计算（如画布布局、进度动画）前先转换；width在该接口中却是number，这种混合类型在同类贴纸接口中同样存在（如 ReelsTrayFeedResponseStoryQuizsItem 的x为string），跨贴纸类型处理几何数据时应统一做类型归一；
• tallies的font_size为可选字段，缺省时不应假设固定值；
• viewer_can_vote与finished决定了贴纸的交互状态，配合storyPollVote的返回值（含viewer_vote）可以完整覆盖「可投 → 已投 → 结束」的状态机；
• 该接口属于响应类型层，仅描述服务端返回结构，不依赖具体客户端版本逻辑；但私有协议可能随 Instagram 端更新变化，使用时应以当前仓库 src/responses/reels-tray.feed.response.ts 的定义为准。

一句话总结：ReelsTrayFeedResponseStoryPollsItem= 贴纸画布几何布局（9 个通用字段）+poll_sticker业务内容；它是reels_tray响应中投票贴纸的完整数据契约，并直接为投票接口story_poll_vote和story_poll_voters查询提供了所需的mediaId与poll_id。

• 后端