Skip to content

Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.

feat(scroll): add scroll param to screen ratio (#6029)

Univer5a8de18d6ef8
diff --git a/packages/sheets-ui/src/commands/operations/scroll.operation.ts b/packages/sheets-ui/src/commands/operations/scroll.operation.ts
index a345b4890a..b9f8f63bc9 100644
--- a/packages/sheets-ui/src/commands/operations/scroll.operation.ts
+++ b/packages/sheets-ui/src/commands/operations/scroll.operation.ts
@@ -31,7 +31,7 @@ export const SetScrollOperation: IOperation<IScrollStateWithSearchParam> = {
}
// freeze is handled by set-scroll.command.ts
- const { unitId, sheetId, offsetX, offsetY, sheetViewStartColumn, sheetViewStartRow, duration } = params;
+ const { unitId, sheetId, offsetX = 0, offsetY = 0, sheetViewStartColumn, sheetViewStartRow, duration, screenRatioX, screenRatioY } = params;
const renderManagerService = accessor.get(IRenderManagerService);
const scrollManagerService = renderManagerService.getRenderById(unitId)!.with(SheetScrollManagerService);
// const currentService = accessor.get(IUniverInstanceService);
@@ -39,11 +39,24 @@ export const SetScrollOperation: IOperation<IScrollStateWithSearchParam> = {
// const worksheet = workbook!.getSheetBySheetId(sheetId);
// const { xSplit, ySplit } = worksheet!.getConfig().freeze;
+ const renderUnit = renderManagerService.getRenderById(unitId);
+
+ if (!renderUnit) {
+ return false;
+ }
+
+ const engine = renderUnit.engine;
+ const canvasWidth = engine.width;
+ const canvasHeight = engine.height;
+
+ const finalOffsetX = screenRatioX !== undefined ? (canvasWidth * screenRatioX) + offsetX : offsetX;
+ const finalOffsetY = screenRatioY !== undefined ? (canvasHeight * screenRatioY) + offsetY : offsetY;
+
scrollManagerService.emitRawScrollParam({
unitId,
sheetId,
- offsetX,
- offsetY,
+ offsetX: finalOffsetX,
+ offsetY: finalOffsetY,
sheetViewStartRow,
sheetViewStartColumn,
duration,
diff --git a/packages/sheets-ui/src/services/scroll-manager.service.ts b/packages/sheets-ui/src/services/scroll-manager.service.ts
index fee542e5c5..113b71cd07 100644
--- a/packages/sheets-ui/src/services/scroll-manager.service.ts
+++ b/packages/sheets-ui/src/services/scroll-manager.service.ts
@@ -50,6 +50,46 @@ export interface IScrollState {
* The duration of the scroll animation in milliseconds.
*/
duration?: number;
+
+ /**
+ * The relative screen offset ratio (horizontal).
+ *
+ * - Represents how far the target scroll position is along the **visible screen width**.
+ * - The value is **relative**, not absolute — for example:
+ * - `screenRatioX = 0` → aligns the target with the **left edge** of the visible area.
+ * - `screenRatioX = 0.5` → centers the target horizontally.
+ * - `screenRatioX = 1` → aligns the target with the **right edge**.
+ *
+ * The final horizontal scroll offset is calculated as:
+ * ```ts
+ * offsetX = screenWidth * screenRatioX
+ * ```
+ *
+ * @example
+ * // Scroll to 60% of the screen width to make the range appear slightly right-centered
+ * screenRatioX = 0.6
+ */
+ screenRatioX?: number;
+
+ /**
+ * The relative screen offset ratio (vertical).
+ *
+ * - Represents how far the target scroll position is along the **visible screen height**.
+ * - The value is **relative**, not absolute — for example:
+ * - `screenRatioY = 0` → aligns the target with the **top edge** of the visible area.
+ * - `screenRatioY = 0.5` → centers the target vertically.
+ * - `screenRatioY = 1` → aligns the target with the **bottom edge**.
+ *
+ * The final vertical scroll offset is calculated as:
+ * ```ts
+ * offsetY = screenHeight * screenRatioY
+ * ```
+ *
+ * @example
+ * // Scroll to 55% of the screen height for a slightly lower visual bias
+ * screenRatioY = 0.55
+ */
+ screenRatioY?: number;
}
export interface IViewportScrollState extends IScrollState {